@vibecuting/component-project-helper 0.1.16 → 0.1.18

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/bin/component-project-helper.mjs

@@ -5,10 +5,10 @@ import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 
 const binDir = path.dirname(fileURLToPath(import.meta.url))
-const scriptName = process.argv[2] === 'preuninstall' ? 'preuninstall.mjs' : 'postinstall.mjs'
-const scriptPath = path.resolve(binDir, '../scripts', scriptName)
+const checkOnly = process.argv.includes('--check')
+const scriptPath = path.resolve(binDir, '../scripts', 'update-component-meta.mjs')
 
-const result = spawnSync(process.execPath, [scriptPath], {
+const result = spawnSync(process.execPath, checkOnly ? [scriptPath, '--check'] : [scriptPath], {
   stdio: 'inherit',
   env: process.env,
 })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibecuting/component-project-helper",
-  "version": "0.1.16",
+  "version": "0.1.18",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",
   "main": "./src/index.ts",
@@ -20,18 +20,21 @@
     "access": "public"
   },
   "scripts": {
-    "postinstall": "node ./scripts/postinstall.mjs",
-    "preuninstall": "node ./scripts/preuninstall.mjs",
+    "update-component-meta": "node ./scripts/update-component-meta.mjs",
+    "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",
     "typescript": "^5.9.3",
+    "tsx": "^4.19.2",
     "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/postinstall.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-meta.mjs

@@ -0,0 +1,60 @@
+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",
+    ),
+  ];
+
+  for (const candidate of candidates) {
+    if (existsSync(candidate)) {
+      return candidate;
+    }
+  }
+
+  return require.resolve("tsx");
+}
+
+const scriptPath = path.relative(process.cwd(), fileURLToPath(import.meta.url));
+
+if (!process.env.COMPONENT_PROJECT_HELPER_UPDATE_COMPONENT_META_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_META_LOADER: "1",
+      },
+      stdio: "inherit",
+    },
+  );
+
+  if (result.error) {
+    throw result.error;
+  }
+
+  process.exit(result.status ?? 1);
+}
+
+const helperModule = await import(
+  pathToFileURL(
+    path.resolve(process.cwd(), "src/meta/update-component-meta.ts"),
+  ).href
+);
+
+await helperModule.updateComponentMeta(
+  process.cwd(),
+  process.argv.includes("--check"),
+);

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/decorators/index.ts

@@ -1,38 +1,116 @@
-import 'reflect-metadata'
-
+import type {
+  ScenePluginMetadata,
+  ThemePluginMetadata,
+  TransitionPluginMetadata,
+  VideoResourceMetadata,
+} from '../resources/video-resource'
+import {
+  VIDEO_RESOURCE_METADATA_KEY,
+  createVideoResourceAnnotation,
+  defineScenePluginMetadata as defineScenePluginMetadataBase,
+  defineThemePluginMetadata as defineThemePluginMetadataBase,
+  defineTransitionPluginMetadata as defineTransitionPluginMetadataBase,
+  getVideoResourceMetadata,
+  ScenePluginMetadataSchema,
+  type VideoResourceDescriptor,
+} from '../resources/video-resource'
+import {
+  sceneResourceDescriptor,
+  themeResourceDescriptor,
+  transitionResourceDescriptor,
+} from '../resources/resource-descriptors'
 import {
   ComponentProjectComponentMetadataSchema,
-  type ComponentProjectComponentMetadata,
+  type ComponentProjectComponentMetadata as LegacyComponentProjectComponentMetadata,
 } from '../schemas'
 
-export const COMPONENT_PROJECT_METADATA_KEY = Symbol.for(
-  '@vibecuting/component-project-helper/component-metadata',
-)
+export const COMPONENT_PROJECT_METADATA_KEY = VIDEO_RESOURCE_METADATA_KEY
+
+export type ComponentProjectComponentMetadata = LegacyComponentProjectComponentMetadata
 
 export function defineComponentProjectComponentMetadata(
   metadata: ComponentProjectComponentMetadata,
 ): ComponentProjectComponentMetadata {
-  return ComponentProjectComponentMetadataSchema.parse(metadata)
+  return ComponentProjectComponentMetadataSchema.parse(metadata) as ComponentProjectComponentMetadata
 }
 
-export function VideoComponent(metadata: ComponentProjectComponentMetadata) {
-  const normalized = defineComponentProjectComponentMetadata(metadata)
+const sceneAnnotation = createVideoResourceAnnotation(sceneResourceDescriptor)
+const transitionAnnotation = createVideoResourceAnnotation(transitionResourceDescriptor)
+const themeAnnotation = createVideoResourceAnnotation(themeResourceDescriptor)
 
-  return function componentProjectDecorator<T extends (...args: any[]) => unknown>(target: T): T {
-    Reflect.defineMetadata(COMPONENT_PROJECT_METADATA_KEY, normalized, target)
-    return target
+function normalizeSceneMetadata(
+  metadata: ComponentProjectComponentMetadata | ScenePluginMetadata,
+): ScenePluginMetadata {
+  if ('resourceKind' in metadata) {
+    return ScenePluginMetadataSchema.parse(metadata)
   }
+
+  return ScenePluginMetadataSchema.parse({
+    resourceKind: 'scene',
+    name: metadata.name,
+    description: metadata.description,
+    sourceFile: metadata.sourceFile,
+    aspectRatio: metadata.aspectRatio,
+    sceneType: metadata.sceneType,
+    sceneFamily: 'custom',
+    themePreset: undefined,
+    slots: undefined,
+    propsTypeName: metadata.propsTypeName,
+    rootLayout: 'absolute-fill',
+    tags: metadata.tags,
+    pluginKey: metadata.name,
+  })
 }
 
+export function VideoComponent(
+  metadata: ComponentProjectComponentMetadata | ScenePluginMetadata,
+) {
+  return sceneAnnotation.annotate(normalizeSceneMetadata(metadata))
+}
+export const TransitionComponent = transitionAnnotation.annotate
+export const ThemeComponent = themeAnnotation.annotate
+
+export const defineScenePluginMetadata = defineScenePluginMetadataBase
+export const defineTransitionPluginMetadata = defineTransitionPluginMetadataBase
+export const defineThemePluginMetadata = defineThemePluginMetadataBase
+
 export function getComponentProjectComponentMetadata(
   target: unknown,
 ): ComponentProjectComponentMetadata | undefined {
-  if (!target || (typeof target !== 'object' && typeof target !== 'function')) {
+  const metadata = getVideoResourceMetadata<ScenePluginMetadata>(target, 'scene')
+  if (!metadata) {
     return undefined
   }
 
-  return Reflect.getMetadata(
-    COMPONENT_PROJECT_METADATA_KEY,
-    target,
-  ) as ComponentProjectComponentMetadata | undefined
+  const { resourceKind, pluginKey, rootLayout, sceneFamily, themePreset, slots, ...legacy } =
+    metadata
+  void resourceKind
+  void pluginKey
+  void rootLayout
+  void sceneFamily
+  void themePreset
+  void slots
+  return legacy as ComponentProjectComponentMetadata
+}
+
+export function getScenePluginMetadata(target: unknown): ScenePluginMetadata | undefined {
+  return getVideoResourceMetadata<ScenePluginMetadata>(target, 'scene')
+}
+
+export function getTransitionPluginMetadata(
+  target: unknown,
+): TransitionPluginMetadata | undefined {
+  return getVideoResourceMetadata<TransitionPluginMetadata>(target, 'transition')
+}
+
+export function getThemePluginMetadata(target: unknown): ThemePluginMetadata | undefined {
+  return getVideoResourceMetadata<ThemePluginMetadata>(target, 'theme')
+}
+
+export type {
+  ScenePluginMetadata,
+  ThemePluginMetadata,
+  TransitionPluginMetadata,
+  VideoResourceMetadata,
+  VideoResourceDescriptor,
 }

package/src/discovery/index.test.ts

@@ -4,183 +4,110 @@ import { tmpdir } from 'node:os'
 
 import { expect, test } from 'vitest'
 
-import { discoverComponentProjectComponents } from './index'
+import { discoverVideoResources } from './index'
 
-test('discovers decorated components recursively', async () => {
+test('discovers scene, transition and theme resources from installed packages', async () => {
   const projectRoot = await fs.mkdtemp(path.join(tmpdir(), 'component-project-helper-discovery-'))
-  const componentsDir = path.join(projectRoot, 'src', 'components', 'nested')
-  await fs.mkdir(componentsDir, { recursive: true })
+  const packageRoot = path.join(projectRoot, 'node_modules', '@vibecuting', 'demo-pack')
+  const srcRoot = path.join(packageRoot, 'src')
 
+  await fs.mkdir(srcRoot, { recursive: true })
   await fs.writeFile(
-    path.join(projectRoot, 'src', 'components', 'SceneFrame.tsx'),
-    `
-      @VideoComponent({
-        name: 'SceneFrame',
-        description: 'Wraps the scene content in a consistent frame',
-        sourceFile: 'src/components/SceneFrame.tsx',
-        aspectRatio: '16:9',
-        sceneType: 'scene',
-        tags: ['layout', 'frame'],
-        propsTypeName: 'SceneFrameProps',
-      })
-      export const SceneFrame = () => null
-    `,
-    'utf8',
-  )
-
-  await fs.writeFile(
-    path.join(componentsDir, 'SceneTitle.tsx'),
-    `
-      @VideoComponent({
-        name: 'SceneTitle',
-        description: 'Renders the title block for scene hero content',
-        sourceFile: 'src/components/nested/SceneTitle.tsx',
-        aspectRatio: '9:16',
-        sceneType: 'intro',
-        tags: ['title', 'hero'],
-        propsTypeName: 'SceneTitleProps',
-      })
-      export const SceneTitle = () => null
-    `,
-    'utf8',
-  )
-
-  const discovered = await discoverComponentProjectComponents(projectRoot)
-
-  expect(discovered).toEqual([
-    {
-      name: 'SceneFrame',
-      description: 'Wraps the scene content in a consistent frame',
-      sourceFile: 'src/components/SceneFrame.tsx',
-      aspectRatio: '16:9',
-      sceneType: 'scene',
-      tags: ['layout', 'frame'],
-      propsTypeName: 'SceneFrameProps',
-    },
-    {
-      name: 'SceneTitle',
-      description: 'Renders the title block for scene hero content',
-      sourceFile: 'src/components/nested/SceneTitle.tsx',
-      aspectRatio: '9:16',
-      sceneType: 'intro',
-      tags: ['title', 'hero'],
-      propsTypeName: 'SceneTitleProps',
-    },
-  ])
-})
-
-test('discovers decorated components from installed video-project-core', async () => {
-  const projectRoot = await fs.mkdtemp(path.join(tmpdir(), 'component-project-helper-package-'))
-  const videoProjectCoreComponentDir = path.join(
-    projectRoot,
-    'node_modules',
-    '@vibecuting',
-    'video-project-core',
-    'src',
-    'core',
-    'intro',
-  )
-  await fs.mkdir(videoProjectCoreComponentDir, { recursive: true })
-
-  await fs.writeFile(
-    path.join(videoProjectCoreComponentDir, 'DefaultIntroBumper.tsx'),
-    `
-      @VideoComponent({
-        name: 'DefaultIntroBumper',
-        description: 'Default remotion intro bumper',
-        sourceFile: 'node_modules/@vibecuting/video-project-core/src/core/intro/DefaultIntroBumper.tsx',
-        aspectRatio: '16:9',
-        sceneType: 'intro',
-        tags: ['intro', 'core'],
-        propsTypeName: 'DefaultIntroBumperProps',
-      })
-      export const DefaultIntroBumper = () => null
-    `,
+    path.join(packageRoot, 'package.json'),
+    JSON.stringify({
+      name: '@vibecuting/demo-pack',
+      version: '0.1.0',
+      main: './src/index.ts',
+      types: './src/index.ts',
+    }),
     'utf8',
   )
 
-  const videoProjectHelperComponentDir = path.join(
-    projectRoot,
-    'node_modules',
-    '@vibecuting',
-    'video-project-helper',
-    'src',
-    'core',
-    'scene',
-  )
-  await fs.mkdir(videoProjectHelperComponentDir, { recursive: true })
-
   await fs.writeFile(
-    path.join(videoProjectHelperComponentDir, 'DefaultSceneFrame.tsx'),
+    path.join(srcRoot, 'index.ts'),
     `
-      @VideoComponent({
-        name: 'DefaultSceneFrame',
-        description: 'Default helper scene frame',
-        sourceFile: 'node_modules/@vibecuting/video-project-helper/src/core/scene/DefaultSceneFrame.tsx',
+      export const sceneMetadata = defineScenePluginMetadata({
+        resourceKind: 'scene',
+        name: 'DemoScene',
+        description: 'Demo scene resource',
+        sourceFile: 'src/index.ts',
+        pluginKey: 'demo.scene',
+        tags: ['demo'],
         aspectRatio: '16:9',
         sceneType: 'scene',
-        tags: ['scene', 'helper'],
-        propsTypeName: 'DefaultSceneFrameProps',
+        sceneFamily: 'custom',
+        rootLayout: 'absolute-fill',
       })
-      export const DefaultSceneFrame = () => null
-    `,
-    'utf8',
-  )
 
-  const discovered = await discoverComponentProjectComponents(projectRoot)
-
-  expect(discovered).toEqual([
-    {
-      name: 'DefaultIntroBumper',
-      description: 'Default remotion intro bumper',
-      sourceFile: 'node_modules/@vibecuting/video-project-core/src/core/intro/DefaultIntroBumper.tsx',
-      aspectRatio: '16:9',
-      sceneType: 'intro',
-      tags: ['intro', 'core'],
-      propsTypeName: 'DefaultIntroBumperProps',
-    },
-    {
-      name: 'DefaultSceneFrame',
-      description: 'Default helper scene frame',
-      sourceFile:
-        'node_modules/@vibecuting/video-project-helper/src/core/scene/DefaultSceneFrame.tsx',
-      aspectRatio: '16:9',
-      sceneType: 'scene',
-      tags: ['scene', 'helper'],
-      propsTypeName: 'DefaultSceneFrameProps',
-    },
-  ])
-})
-
-test('ignores test files from installed packages', async () => {
-  const projectRoot = await fs.mkdtemp(path.join(tmpdir(), 'component-project-helper-tests-'))
-  const packageTestDir = path.join(
-    projectRoot,
-    'node_modules',
-    '@vibecuting',
-    'video-project-helper',
-    'src',
-  )
-  await fs.mkdir(packageTestDir, { recursive: true })
+      export const transitionMetadata = defineTransitionPluginMetadata({
+        resourceKind: 'transition',
+        name: 'DemoTransition',
+        description: 'Demo transition resource',
+        sourceFile: 'src/index.ts',
+        pluginKey: 'demo.transition',
+        tags: ['demo'],
+        transitionKind: 'transition',
+      })
 
-  await fs.writeFile(
-    path.join(packageTestDir, 'index.test.ts'),
-    `
-      @VideoComponent({
-        name: 'ShouldBeIgnored',
-        description: 'This fixture lives in a test file and must not be discovered',
-        sourceFile: 'node_modules/@vibecuting/video-project-helper/src/index.test.ts',
-        aspectRatio: '16:9',
-        sceneType: 'scene',
-        tags: ['test'],
-        propsTypeName: 'ShouldBeIgnoredProps',
+      export const themeMetadata = defineThemePluginMetadata({
+        resourceKind: 'theme',
+        name: 'DemoTheme',
+        description: 'Demo theme resource',
+        sourceFile: 'src/index.ts',
+        pluginKey: 'demo.theme',
+        tags: ['demo'],
+        supportedSceneFamilies: ['custom'],
+        cssVariables: ['--scene-bg'],
       })
-      export const ShouldBeIgnored = () => null
+
+      export const DemoScene = VideoComponent(sceneMetadata)(
+        defineSceneComponent({
+          family: 'custom',
+          propsSchema: null,
+          component: function DemoScene() {
+            return null
+          },
+        }),
+      )
+
+      export const DemoTransition = TransitionComponent(transitionMetadata)(
+        defineTransitionPlugin({
+          key: 'demo.transition',
+          kind: 'transition',
+          metadata: transitionMetadata,
+          propsSchema: null,
+          renderBoundary: () => null,
+          getBoundaryDurationInFrames: () => 1,
+          getTimelineOverlapInFrames: () => 1,
+        }),
+      )
+
+      export const DemoTheme = ThemeComponent(themeMetadata)(
+        defineSceneTheme({
+          key: 'demo.theme',
+          name: 'Demo theme',
+          variables: {
+            '--scene-bg': '#000000',
+          },
+        }),
+      )
     `,
     'utf8',
   )
 
-  const discovered = await discoverComponentProjectComponents(projectRoot)
+  const discovered = await discoverVideoResources(projectRoot)
 
-  expect(discovered).toEqual([])
+  expect(discovered.map((resource) => resource.exportName)).toEqual([
+    'DemoScene',
+    'DemoTheme',
+    'DemoTransition',
+  ])
+  expect(discovered.map((resource) => resource.metadata.resourceKind)).toEqual([
+    'scene',
+    'theme',
+    'transition',
+  ])
+  expect(discovered[0]?.metadata.pluginKey).toBe('demo.scene')
+  expect(discovered[1]?.metadata.pluginKey).toBe('demo.theme')
+  expect(discovered[2]?.metadata.pluginKey).toBe('demo.transition')
 })