@vibecuting/component-project-helper 0.1.6 → 0.1.8

package/README.md

@@ -8,12 +8,13 @@ NPM 地址：
 
 职责：
 
-- 作为可发布的 npm 包承载组件工程辅助逻辑
-- 安装时扫描 `src/components/**/*.tsx`，把组件元数据生成到 `.agents/skills/project-allow-component/components/`
-- 通过 `postinstall` / `preuninstall` 维护生成文件和清理清单
-- 提供 `VideoComponent` 装饰器和 `defineComponentProjectComponentMetadata()` 注解定义，供后续需要元数据注解的组件复用
-- `postinstall` / `preuninstall` 的实际执行入口在 `scripts/` 下，便于 npm 安装时直接运行
-- 作为主工程之外的独立 helper 包，避免把辅助逻辑重新塞回主站代码里
+- 作为可发布的 npm 包承载组件工程辅助逻辑。
+- 提供组件注解、schema、发现器、Markdown 生成和安装期生命周期逻辑。
+- 安装时扫描 `src/components/**/*.tsx`，把组件元数据生成到 `.agents/skills/project-allow-component/components/`。
+- 通过 `postinstall` / `preuninstall` 维护生成文件和清理清单。
+- 安装时会给宿主工程的 `package.json` 补上 `update-component-skills`，它会调用同一套 `postinstall` 逻辑。
+- 宿主工程也可以直接运行 `pnpm update-component-skills` 手动刷新同一套生成结果。
+- 作为主工程之外的独立 helper 包，避免把辅助逻辑重新塞回主站代码里。
 
 目录结构：
 
@@ -29,3 +30,9 @@ NPM 地址：
 - `pnpm typecheck`
 - `pnpm test`
 - `node ./bin/component-project-helper.mjs postinstall`
+- `pnpm update-component-skills`
+
+发布与安装：
+
+- 发布到 npmjs 公共 registry 时使用 `@vibecuting/component-project-helper`
+- 组件模板和主工程只依赖这个包的已发布版本，不依赖 workspace 软链接

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibecuting/component-project-helper",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./src/index.ts",

package/scripts/discover-components.mjs

@@ -62,7 +62,47 @@ function parseMetadataLiteral(literal) {
   }
 }
 
+async function collectComponentSourceFiles(directory) {
+  let entries = []
+
+  try {
+    entries = await fs.readdir(directory, { withFileTypes: true })
+  } catch {
+    return []
+  }
+
+  const files = []
+
+  for (const entry of entries) {
+    const entryPath = path.join(directory, entry.name)
+
+    if (entry.isDirectory()) {
+      files.push(...(await collectComponentSourceFiles(entryPath)))
+      continue
+    }
+
+    if (!entry.isFile()) {
+      continue
+    }
+
+    if (entry.name.endsWith('.d.ts')) {
+      continue
+    }
+
+    if (entry.name.endsWith('.ts') || entry.name.endsWith('.tsx')) {
+      files.push(entryPath)
+    }
+  }
+
+  return files
+}
+
 function readMetadataFromSource(source) {
+  const decoratorMatch = /@VideoComponent\s*\((\{[\s\S]*?\})\)/m.exec(source)
+  if (decoratorMatch) {
+    return parseMetadataLiteral(decoratorMatch[1])
+  }
+
   const patterns = [
     /componentMetadata\s*=\s*defineComponentProjectComponentMetadata\s*\(/m,
     /componentMetadata\s*=\s*VideoComponent\s*\(/m,
@@ -91,32 +131,15 @@ function readMetadataFromSource(source) {
     }
   }
 
-  const decoratorMatch = /@VideoComponent\s*\((\{[\s\S]*?\})\)/m.exec(source)
-  if (decoratorMatch) {
-    return parseMetadataLiteral(decoratorMatch[1])
-  }
-
   return undefined
 }
 
 export async function discoverComponentProjectComponents(projectRoot) {
   const componentsDir = path.join(projectRoot, 'src', 'components')
-  let entries = []
-
-  try {
-    entries = await fs.readdir(componentsDir)
-  } catch {
-    return []
-  }
-
   const discovered = []
+  const sourceFiles = await collectComponentSourceFiles(componentsDir)
 
-  for (const entry of entries) {
-    if (!entry.endsWith('.tsx')) {
-      continue
-    }
-
-    const absolutePath = path.join(componentsDir, entry)
+  for (const absolutePath of sourceFiles) {
     const source = await fs.readFile(absolutePath, 'utf8')
     const metadata = readMetadataFromSource(source)
     if (!metadata) {

package/scripts/render-markdown.mjs

@@ -13,6 +13,8 @@ export function renderComponentProjectMarkdown(input) {
     `name: ${metadata.name}`,
     `description: ${metadata.description}`,
     `sourceFile: ${metadata.sourceFile}`,
+    `aspectRatio: ${metadata.aspectRatio}`,
+    `sceneType: ${metadata.sceneType ?? ''}`,
     `propsTypeName: ${metadata.propsTypeName ?? ''}`,
     'tags:',
     ...tags.map((tag) => `  - ${tag}`),
@@ -25,6 +27,8 @@ export function renderComponentProjectMarkdown(input) {
     '## Metadata',
     '',
     `- Source file: \`${escapeInline(metadata.sourceFile)}\``,
+    `- Aspect ratio: \`${escapeInline(metadata.aspectRatio)}\``,
+    `- Scene type: \`${escapeInline(metadata.sceneType ?? 'unknown')}\``,
     `- Props type: \`${escapeInline(metadata.propsTypeName ?? 'unknown')}\``,
     `- Tags: ${tags.map((tag) => `\`${escapeInline(tag)}\``).join(', ')}`,
     '',

package/scripts/runtime-root.mjs

@@ -1,14 +1,43 @@
 import path from 'node:path'
+import fs from 'node:fs'
 import process from 'node:process'
 
+function hasComponentProjectSourceDir(directory) {
+  return fs.existsSync(path.join(directory, 'src', 'components'))
+}
+
+function findComponentProjectInstallRoot(startDirectory) {
+  let currentDirectory = path.resolve(startDirectory)
+
+  for (;;) {
+    if (hasComponentProjectSourceDir(currentDirectory)) {
+      return currentDirectory
+    }
+
+    const parentDirectory = path.dirname(currentDirectory)
+    if (parentDirectory === currentDirectory) {
+      return undefined
+    }
+
+    currentDirectory = parentDirectory
+  }
+}
+
 export function resolveComponentProjectInstallRoot() {
   const candidates = [
+    process.cwd(),
     process.env.INIT_CWD,
     process.env.npm_config_local_prefix,
-    process.cwd(),
   ].filter((value) => Boolean(value && String(value).trim()))
 
-  return path.resolve(candidates[0] ?? process.cwd())
+  for (const candidate of candidates) {
+    const resolved = findComponentProjectInstallRoot(candidate)
+    if (resolved) {
+      return resolved
+    }
+  }
+
+  return path.resolve(process.cwd())
 }
 
 export function resolveComponentProjectGeneratedDocsDir(projectRoot = resolveComponentProjectInstallRoot()) {

package/scripts/schemas.mjs

@@ -4,6 +4,8 @@ export const ComponentProjectComponentMetadataSchema = z.object({
   name: z.string().min(1),
   description: z.string().min(1),
   sourceFile: z.string().min(1),
+  aspectRatio: z.enum(['9:16', '16:9']),
+  sceneType: z.enum(['intro', 'scene', 'outro']).optional(),
   tags: z.array(z.string().min(1)).default([]),
   propsTypeName: z.string().min(1).optional(),
 })

package/src/discovery/index.test.ts

@@ -0,0 +1,70 @@
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import { tmpdir } from 'node:os'
+
+import { expect, test } from 'vitest'
+
+import { discoverComponentProjectComponents } from './index'
+
+test('discovers decorated components recursively', 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 })
+
+  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',
+    },
+  ])
+})

package/src/discovery/index.ts

@@ -1,4 +1,5 @@
 import fs from 'node:fs/promises'
+import type { Dirent } from 'node:fs'
 import path from 'node:path'
 
 import {
@@ -8,6 +9,41 @@ import {
 
 export type ComponentProjectComponentDiscovery = ComponentProjectComponentMetadata
 
+async function collectComponentSourceFiles(directory: string): Promise<string[]> {
+  let entries: Dirent[] = []
+
+  try {
+    entries = await fs.readdir(directory, { withFileTypes: true })
+  } catch {
+    return []
+  }
+
+  const files: string[] = []
+
+  for (const entry of entries) {
+    const entryPath = path.join(directory, entry.name)
+
+    if (entry.isDirectory()) {
+      files.push(...(await collectComponentSourceFiles(entryPath)))
+      continue
+    }
+
+    if (!entry.isFile()) {
+      continue
+    }
+
+    if (entry.name.endsWith('.d.ts')) {
+      continue
+    }
+
+    if (entry.name.endsWith('.ts') || entry.name.endsWith('.tsx')) {
+      files.push(entryPath)
+    }
+  }
+
+  return files
+}
+
 function extractBalancedObjectLiteral(source: string, startIndex: number): string | undefined {
   let depth = 0
   let inString = false
@@ -68,6 +104,11 @@ function parseMetadataLiteral(literal: string): ComponentProjectComponentMetadat
 }
 
 function readMetadataFromSource(source: string): ComponentProjectComponentMetadata | undefined {
+  const decoratorMatch = /@VideoComponent\s*\((\{[\s\S]*?\})\)/m.exec(source)
+  if (decoratorMatch) {
+    return parseMetadataLiteral(decoratorMatch[1])
+  }
+
   const candidates = [
     /componentMetadata\s*=\s*defineComponentProjectComponentMetadata\s*\(/m,
     /componentMetadata\s*=\s*VideoComponent\s*\(/m,
@@ -96,11 +137,6 @@ function readMetadataFromSource(source: string): ComponentProjectComponentMetada
     }
   }
 
-  const decoratorMatch = /@VideoComponent\s*\((\{[\s\S]*?\})\)/m.exec(source)
-  if (decoratorMatch) {
-    return parseMetadataLiteral(decoratorMatch[1])
-  }
-
   return undefined
 }
 
@@ -108,22 +144,10 @@ export async function discoverComponentProjectComponents(
   projectRoot: string,
 ): Promise<ComponentProjectComponentDiscovery[]> {
   const componentsDir = path.join(projectRoot, 'src', 'components')
-  let entries: string[] = []
-
-  try {
-    entries = await fs.readdir(componentsDir)
-  } catch {
-    return []
-  }
-
   const discovered: ComponentProjectComponentDiscovery[] = []
+  const sourceFiles = await collectComponentSourceFiles(componentsDir)
 
-  for (const entry of entries) {
-    if (!entry.endsWith('.tsx')) {
-      continue
-    }
-
-    const absolutePath = path.join(componentsDir, entry)
+  for (const absolutePath of sourceFiles) {
     const source = await fs.readFile(absolutePath, 'utf8')
     const metadata = readMetadataFromSource(source)
     if (!metadata) {

package/src/lifecycle/package-json.ts

@@ -0,0 +1,47 @@
+import fs from 'node:fs/promises'
+import path from 'node:path'
+
+export const componentProjectSkillsScriptName = 'update-component-skills' as const
+export const componentProjectSkillsScriptCommand =
+  'node ./node_modules/@vibecuting/component-project-helper/scripts/postinstall.mjs' as const
+
+async function readPackageJson(projectRoot: string): Promise<Record<string, unknown>> {
+  const packageJsonPath = path.join(projectRoot, 'package.json')
+  return JSON.parse(await fs.readFile(packageJsonPath, 'utf8'))
+}
+
+async function writePackageJson(
+  projectRoot: string,
+  packageJson: Record<string, unknown>,
+): Promise<void> {
+  const packageJsonPath = path.join(projectRoot, 'package.json')
+  await fs.writeFile(packageJsonPath, `${JSON.stringify(packageJson, null, 2)}\n`, 'utf8')
+}
+
+export async function ensureComponentProjectSkillsScript(projectRoot: string): Promise<void> {
+  const packageJson = await readPackageJson(projectRoot)
+  const scripts = (packageJson.scripts as Record<string, string> | undefined) ?? {}
+
+  if (scripts[componentProjectSkillsScriptName] !== componentProjectSkillsScriptCommand) {
+    packageJson.scripts = {
+      ...scripts,
+      [componentProjectSkillsScriptName]: componentProjectSkillsScriptCommand,
+    }
+    await writePackageJson(projectRoot, packageJson)
+  }
+}
+
+export async function removeComponentProjectSkillsScript(projectRoot: string): Promise<void> {
+  const packageJson = await readPackageJson(projectRoot)
+  const scripts = (packageJson.scripts as Record<string, string> | undefined) ?? {}
+
+  if (scripts[componentProjectSkillsScriptName] !== componentProjectSkillsScriptCommand) {
+    return
+  }
+
+  const nextScripts = { ...scripts }
+  delete nextScripts[componentProjectSkillsScriptName]
+  packageJson.scripts = nextScripts
+
+  await writePackageJson(projectRoot, packageJson)
+}

package/src/lifecycle/postinstall.test.ts

@@ -9,34 +9,53 @@ import { runComponentProjectPreuninstall } from './preuninstall'
 
 async function createFixtureProjectRoot(): Promise<string> {
   const projectRoot = await fs.mkdtemp(path.join(tmpdir(), 'component-project-helper-'))
-  await fs.mkdir(path.join(projectRoot, 'src', 'components'), { recursive: true })
+  await fs.mkdir(path.join(projectRoot, 'src', 'components', 'nested'), { recursive: true })
+  await fs.writeFile(
+    path.join(projectRoot, 'package.json'),
+    JSON.stringify(
+      {
+        name: 'component-project-fixture',
+        private: true,
+        scripts: {
+          build: 'echo build',
+        },
+      },
+      null,
+      2,
+    ),
+    'utf8',
+  )
 
   await fs.writeFile(
     path.join(projectRoot, 'src', 'components', 'SceneFrame.tsx'),
-    `export const componentMetadata = {
-  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',
-} as const
+    `
+      @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(projectRoot, 'src', 'components', 'SceneTitle.tsx'),
-    `export const componentMetadata = {
-  name: 'SceneTitle',
-  description: 'Renders the title block for scene hero content',
-  sourceFile: 'src/components/SceneTitle.tsx',
-  aspectRatio: '16:9',
-  sceneType: 'intro',
-  tags: ['title'],
-  propsTypeName: 'SceneTitleProps',
-} as const
+    path.join(projectRoot, 'src', 'components', 'nested', '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'],
+        propsTypeName: 'SceneTitleProps',
+      })
+      export const SceneTitle = () => null
 `,
     'utf8',
   )
@@ -66,6 +85,17 @@ test('postinstall generates markdown and preuninstall removes it', async () => {
   await expect(fs.stat(path.join(docsDir, 'SceneFrame.md'))).resolves.toBeDefined()
   await expect(fs.stat(path.join(docsDir, 'SceneTitle.md'))).resolves.toBeDefined()
   await expect(fs.stat(manifestPath)).resolves.toBeDefined()
+  await expect(await fs.readFile(path.join(docsDir, 'SceneTitle.md'), 'utf8')).toContain(
+    'src/components/nested/SceneTitle.tsx',
+  )
+  await expect(await fs.readFile(path.join(docsDir, 'SceneTitle.md'), 'utf8')).toContain(
+    '9:16',
+  )
+  await expect(
+    JSON.parse(await fs.readFile(path.join(projectRoot, 'package.json'), 'utf8')).scripts[
+      'update-component-skills'
+    ],
+  ).toBe('node ./node_modules/@vibecuting/component-project-helper/scripts/postinstall.mjs')
 
   await runComponentProjectPreuninstall(projectRoot)
 
@@ -76,4 +106,9 @@ test('postinstall generates markdown and preuninstall removes it', async () => {
     code: 'ENOENT',
   })
   await expect(fs.stat(manifestPath)).rejects.toMatchObject({ code: 'ENOENT' })
+  await expect(
+    JSON.parse(await fs.readFile(path.join(projectRoot, 'package.json'), 'utf8')).scripts[
+      'update-component-skills'
+    ],
+  ).toBeUndefined()
 })

package/src/lifecycle/postinstall.ts

@@ -10,6 +10,7 @@ import {
   resolveComponentProjectGeneratedManifestPath,
   resolveComponentProjectInstallRoot,
 } from '../runtime'
+import { ensureComponentProjectSkillsScript } from './package-json'
 
 async function ensureDirectory(dir: string): Promise<void> {
   await fs.mkdir(dir, { recursive: true })
@@ -51,6 +52,7 @@ export async function runComponentProjectPostinstall(
   }
 
   await removeStaleGeneratedFiles(manifestPath, files)
+  await ensureComponentProjectSkillsScript(projectRoot)
 
   const manifest = ComponentProjectGeneratedManifestSchema.parse({
     projectRoot,

package/src/lifecycle/preuninstall.ts

@@ -4,6 +4,7 @@ import { fileURLToPath } from 'node:url'
 
 import { ComponentProjectGeneratedManifestSchema } from '../schemas'
 import { resolveComponentProjectGeneratedManifestPath } from '../runtime'
+import { removeComponentProjectSkillsScript } from './package-json'
 
 export async function runComponentProjectPreuninstall(
   projectRoot = process.env.INIT_CWD ??
@@ -28,6 +29,8 @@ export async function runComponentProjectPreuninstall(
       throw error
     }
   }
+
+  await removeComponentProjectSkillsScript(projectRoot)
 }
 
 async function main(): Promise<void> {

package/src/runtime/index.ts

@@ -1,14 +1,43 @@
 import path from 'node:path'
+import fs from 'node:fs'
 import process from 'node:process'
 
+function hasComponentProjectSourceDir(directory: string): boolean {
+  return fs.existsSync(path.join(directory, 'src', 'components'))
+}
+
+function findComponentProjectInstallRoot(startDirectory: string): string | undefined {
+  let currentDirectory = path.resolve(startDirectory)
+
+  for (;;) {
+    if (hasComponentProjectSourceDir(currentDirectory)) {
+      return currentDirectory
+    }
+
+    const parentDirectory = path.dirname(currentDirectory)
+    if (parentDirectory === currentDirectory) {
+      return undefined
+    }
+
+    currentDirectory = parentDirectory
+  }
+}
+
 export function resolveComponentProjectInstallRoot(): string {
   const candidates = [
+    process.cwd(),
     process.env.INIT_CWD,
     process.env.npm_config_local_prefix,
-    process.cwd(),
   ].filter((value): value is string => Boolean(value && value.trim()))
 
-  return path.resolve(candidates[0] ?? process.cwd())
+  for (const candidate of candidates) {
+    const resolved = findComponentProjectInstallRoot(candidate)
+    if (resolved) {
+      return resolved
+    }
+  }
+
+  return path.resolve(process.cwd())
 }
 
 export function resolveComponentProjectGeneratedDocsDir(