@vibecuting/component-project-helper 0.1.1

package/README.md

@@ -0,0 +1,27 @@
+# @vibecuting/component-project-helper
+
+组件工程辅助包。
+
+职责：
+
+- 作为可发布的 npm 包承载组件工程辅助逻辑
+- 安装时扫描 `src/components/**/*.tsx`，把组件元数据生成到 `.agents/skills/project-allow-component/components/`
+- 通过 `postinstall` / `preuninstall` 维护生成文件和清理清单
+- 提供 `VideoComponent` 装饰器和 `defineComponentProjectComponentMetadata()` 注解定义，供后续需要元数据注解的组件复用
+- `postinstall` / `preuninstall` 的实际执行入口在 `scripts/` 下，便于 npm 安装时直接运行
+- 作为主工程之外的独立 helper 包，避免把辅助逻辑重新塞回主站代码里
+
+目录结构：
+
+- `src/decorators`：注解定义和元数据读写
+- `src/schemas`：zod schema
+- `src/discovery`：组件发现与解析
+- `src/markdown`：Markdown 渲染
+- `src/runtime`：安装根与输出路径解析
+- `src/lifecycle`：postinstall / preuninstall 生命周期逻辑
+
+常用命令：
+
+- `pnpm typecheck`
+- `pnpm test`
+- `node ./bin/component-project-helper.mjs postinstall`

package/bin/component-project-helper.mjs

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+
+import { spawnSync } from 'node:child_process'
+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 result = spawnSync(process.execPath, [scriptPath], {
+  stdio: 'inherit',
+  env: process.env,
+})
+
+process.exit(result.status ?? 1)

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@vibecuting/component-project-helper",
+  "version": "0.1.1",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "bin",
+    "scripts",
+    "src",
+    "README.md",
+    "package.json"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "scripts": {
+    "postinstall": "node ./scripts/postinstall.mjs",
+    "preuninstall": "node ./scripts/preuninstall.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"
+  },
+  "dependencies": {
+    "reflect-metadata": "^0.2.2",
+    "typescript": "^5.9.3",
+    "zod": "4.1.12"
+  },
+  "devDependencies": {
+    "vitest": "^3.2.4"
+  }
+}

package/scripts/discover-components.mjs

@@ -0,0 +1,133 @@
+import fs from 'node:fs/promises'
+import path from 'node:path'
+
+import { ComponentProjectComponentMetadataSchema } from './schemas.mjs'
+
+function extractBalancedObjectLiteral(source, startIndex) {
+  let depth = 0
+  let inString = false
+  let stringQuote = ''
+  let escaped = false
+
+  for (let index = startIndex; index < source.length; index += 1) {
+    const character = source[index]
+
+    if (inString) {
+      if (escaped) {
+        escaped = false
+        continue
+      }
+
+      if (character === '\\') {
+        escaped = true
+        continue
+      }
+
+      if (character === stringQuote) {
+        inString = false
+      }
+
+      continue
+    }
+
+    if (character === '"' || character === "'" || character === '`') {
+      inString = true
+      stringQuote = character
+      continue
+    }
+
+    if (character === '{') {
+      depth += 1
+      continue
+    }
+
+    if (character === '}') {
+      depth -= 1
+      if (depth === 0) {
+        return source.slice(startIndex, index + 1)
+      }
+    }
+  }
+
+  return undefined
+}
+
+function parseMetadataLiteral(literal) {
+  try {
+    const value = Function(`"use strict"; return (${literal});`)()
+    const parsed = ComponentProjectComponentMetadataSchema.safeParse(value)
+    return parsed.success ? parsed.data : undefined
+  } catch {
+    return undefined
+  }
+}
+
+function readMetadataFromSource(source) {
+  const patterns = [
+    /componentMetadata\s*=\s*defineComponentProjectComponentMetadata\s*\(/m,
+    /componentMetadata\s*=\s*VideoComponent\s*\(/m,
+    /componentMetadata\s*=\s*/m,
+  ]
+
+  for (const pattern of patterns) {
+    const match = pattern.exec(source)
+    if (!match) {
+      continue
+    }
+
+    const startIndex = source.indexOf('{', match.index)
+    if (startIndex < 0) {
+      continue
+    }
+
+    const literal = extractBalancedObjectLiteral(source, startIndex)
+    if (!literal) {
+      continue
+    }
+
+    const parsed = parseMetadataLiteral(literal)
+    if (parsed) {
+      return parsed
+    }
+  }
+
+  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 = []
+
+  for (const entry of entries) {
+    if (!entry.endsWith('.tsx')) {
+      continue
+    }
+
+    const absolutePath = path.join(componentsDir, entry)
+    const source = await fs.readFile(absolutePath, 'utf8')
+    const metadata = readMetadataFromSource(source)
+    if (!metadata) {
+      continue
+    }
+
+    discovered.push({
+      ...metadata,
+      sourceFile: path.relative(projectRoot, absolutePath),
+    })
+  }
+
+  return discovered.sort((left, right) => left.name.localeCompare(right.name))
+}

package/scripts/postinstall.mjs

@@ -0,0 +1,60 @@
+import fs from 'node:fs/promises'
+import path from 'node:path'
+
+import { discoverComponentProjectComponents } from './discover-components.mjs'
+import {
+  resolveComponentProjectGeneratedDocsDir,
+  resolveComponentProjectGeneratedManifestPath,
+  resolveComponentProjectInstallRoot,
+} from './runtime-root.mjs'
+import { renderComponentProjectMarkdown } from './render-markdown.mjs'
+import { ComponentProjectGeneratedManifestSchema } from './schemas.mjs'
+
+async function ensureDirectory(dir) {
+  await fs.mkdir(dir, { recursive: true })
+}
+
+async function removeStaleGeneratedFiles(manifestPath, nextFiles) {
+  try {
+    const previous = ComponentProjectGeneratedManifestSchema.parse(
+      JSON.parse(await fs.readFile(manifestPath, 'utf8')),
+    )
+    const staleFiles = previous.files.filter((filePath) => !nextFiles.includes(filePath))
+    await Promise.all(staleFiles.map((filePath) => fs.rm(filePath, { force: true })))
+  } catch (error) {
+    if (error?.code !== 'ENOENT') {
+      throw error
+    }
+  }
+}
+
+export async function runComponentProjectPostinstall(projectRoot = resolveComponentProjectInstallRoot()) {
+  const docsDir = resolveComponentProjectGeneratedDocsDir(projectRoot)
+  const manifestPath = resolveComponentProjectGeneratedManifestPath(projectRoot)
+  const components = await discoverComponentProjectComponents(projectRoot)
+
+  await ensureDirectory(docsDir)
+
+  const files = []
+  for (const component of components) {
+    const filePath = path.join(docsDir, `${component.name}.md`)
+    await fs.writeFile(filePath, renderComponentProjectMarkdown(component), 'utf8')
+    files.push(filePath)
+  }
+
+  await removeStaleGeneratedFiles(manifestPath, files)
+
+  const manifest = ComponentProjectGeneratedManifestSchema.parse({
+    projectRoot,
+    generatedAt: new Date().toISOString(),
+    docsDir,
+    files,
+  })
+  await fs.writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, 'utf8')
+}
+
+const isDirectRun = process.argv[1] && path.resolve(process.argv[1]) === path.resolve(new URL(import.meta.url).pathname)
+
+if (isDirectRun) {
+  await runComponentProjectPostinstall()
+}

package/scripts/preuninstall.mjs

@@ -0,0 +1,34 @@
+import fs from 'node:fs/promises'
+import path from 'node:path'
+
+import { resolveComponentProjectGeneratedManifestPath } from './runtime-root.mjs'
+import { ComponentProjectGeneratedManifestSchema } from './schemas.mjs'
+
+export async function runComponentProjectPreuninstall(
+  projectRoot = process.env.INIT_CWD ?? process.env.npm_config_local_prefix ?? process.cwd(),
+) {
+  const manifestPath = resolveComponentProjectGeneratedManifestPath(projectRoot)
+
+  try {
+    const manifest = ComponentProjectGeneratedManifestSchema.parse(
+      JSON.parse(await fs.readFile(manifestPath, 'utf8')),
+    )
+
+    for (const filePath of manifest.files) {
+      await fs.rm(filePath, { force: true })
+    }
+
+    await fs.rm(manifestPath, { force: true })
+    await fs.rm(manifest.docsDir, { recursive: true, force: true })
+  } catch (error) {
+    if (error?.code !== 'ENOENT') {
+      throw error
+    }
+  }
+}
+
+const isDirectRun = process.argv[1] && path.resolve(process.argv[1]) === path.resolve(new URL(import.meta.url).pathname)
+
+if (isDirectRun) {
+  await runComponentProjectPreuninstall()
+}

package/scripts/render-markdown.mjs

@@ -0,0 +1,32 @@
+import { ComponentProjectComponentMetadataSchema } from './schemas.mjs'
+
+function escapeInline(value) {
+  return value.replaceAll('`', '\\`')
+}
+
+export function renderComponentProjectMarkdown(input) {
+  const metadata = ComponentProjectComponentMetadataSchema.parse(input)
+  const tags = metadata.tags.length > 0 ? metadata.tags : ['component']
+
+  return [
+    '---',
+    `name: ${metadata.name}`,
+    `description: ${metadata.description}`,
+    `sourceFile: ${metadata.sourceFile}`,
+    `propsTypeName: ${metadata.propsTypeName ?? ''}`,
+    'tags:',
+    ...tags.map((tag) => `  - ${tag}`),
+    '---',
+    '',
+    `# ${metadata.name}`,
+    '',
+    metadata.description,
+    '',
+    '## Metadata',
+    '',
+    `- Source file: \`${escapeInline(metadata.sourceFile)}\``,
+    `- Props type: \`${escapeInline(metadata.propsTypeName ?? 'unknown')}\``,
+    `- Tags: ${tags.map((tag) => `\`${escapeInline(tag)}\``).join(', ')}`,
+    '',
+  ].join('\n')
+}

package/scripts/runtime-root.mjs

@@ -0,0 +1,34 @@
+import path from 'node:path'
+import process from 'node:process'
+
+export function resolveComponentProjectInstallRoot() {
+  const candidates = [
+    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())
+}
+
+export function resolveComponentProjectGeneratedDocsDir(projectRoot = resolveComponentProjectInstallRoot()) {
+  return path.join(
+    projectRoot,
+    '.agents',
+    'skills',
+    'project-allow-component',
+    'components',
+  )
+}
+
+export function resolveComponentProjectGeneratedManifestPath(
+  projectRoot = resolveComponentProjectInstallRoot(),
+) {
+  return path.join(
+    projectRoot,
+    '.agents',
+    'skills',
+    'project-allow-component',
+    'component-project-helper.manifest.json',
+  )
+}

package/scripts/schemas.mjs

@@ -0,0 +1,16 @@
+import { z } from 'zod'
+
+export const ComponentProjectComponentMetadataSchema = z.object({
+  name: z.string().min(1),
+  description: z.string().min(1),
+  sourceFile: z.string().min(1),
+  tags: z.array(z.string().min(1)).default([]),
+  propsTypeName: z.string().min(1).optional(),
+})
+
+export const ComponentProjectGeneratedManifestSchema = z.object({
+  projectRoot: z.string().min(1),
+  generatedAt: z.string().min(1),
+  docsDir: z.string().min(1),
+  files: z.array(z.string().min(1)),
+})

package/src/decorators/index.test.ts

@@ -0,0 +1,45 @@
+import { expect, test } from 'vitest'
+
+import {
+  VideoComponent,
+  defineComponentProjectComponentMetadata,
+  getComponentProjectComponentMetadata,
+} from './index'
+
+test('attaches normalized metadata to decorated function components', () => {
+  const metadata = defineComponentProjectComponentMetadata({
+    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',
+  })
+
+  const SceneFrame = () => null
+
+  const decorated = VideoComponent(metadata)(SceneFrame)
+
+  expect(decorated).toBe(SceneFrame)
+  expect(getComponentProjectComponentMetadata(SceneFrame)).toEqual(metadata)
+})
+
+test('attaches normalized metadata to decorated function components', () => {
+  const metadata = defineComponentProjectComponentMetadata({
+    name: 'SceneTitle',
+    description: 'Renders the title block for scene hero content',
+    sourceFile: 'src/components/SceneTitle.tsx',
+    aspectRatio: '16:9',
+    sceneType: 'intro',
+    tags: ['title', 'hero'],
+    propsTypeName: 'SceneTitleProps',
+  })
+
+  const SceneTitle = () => null
+
+  const decorated = VideoComponent(metadata)(SceneTitle)
+
+  expect(decorated).toBe(SceneTitle)
+  expect(getComponentProjectComponentMetadata(SceneTitle)).toEqual(metadata)
+})

package/src/decorators/index.ts

@@ -0,0 +1,40 @@
+import 'reflect-metadata'
+
+import type { ComponentType } from 'react'
+
+import {
+  ComponentProjectComponentMetadataSchema,
+  type ComponentProjectComponentMetadata,
+} from '../schemas'
+
+export const COMPONENT_PROJECT_METADATA_KEY = Symbol.for(
+  '@vibecuting/component-project-helper/component-metadata',
+)
+
+export function defineComponentProjectComponentMetadata(
+  metadata: ComponentProjectComponentMetadata,
+): ComponentProjectComponentMetadata {
+  return ComponentProjectComponentMetadataSchema.parse(metadata)
+}
+
+export function VideoComponent(metadata: ComponentProjectComponentMetadata) {
+  const normalized = defineComponentProjectComponentMetadata(metadata)
+
+  return function componentProjectDecorator<T extends ComponentType<any>>(target: T): T {
+    Reflect.defineMetadata(COMPONENT_PROJECT_METADATA_KEY, normalized, target)
+    return target
+  }
+}
+
+export function getComponentProjectComponentMetadata(
+  target: unknown,
+): ComponentProjectComponentMetadata | undefined {
+  if (!target || (typeof target !== 'object' && typeof target !== 'function')) {
+    return undefined
+  }
+
+  return Reflect.getMetadata(
+    COMPONENT_PROJECT_METADATA_KEY,
+    target,
+  ) as ComponentProjectComponentMetadata | undefined
+}

package/src/discovery/index.ts

@@ -0,0 +1,140 @@
+import fs from 'node:fs/promises'
+import path from 'node:path'
+
+import {
+  ComponentProjectComponentMetadataSchema,
+  type ComponentProjectComponentMetadata,
+} from '../schemas'
+
+export type ComponentProjectComponentDiscovery = ComponentProjectComponentMetadata
+
+function extractBalancedObjectLiteral(source: string, startIndex: number): string | undefined {
+  let depth = 0
+  let inString = false
+  let stringQuote = ''
+  let escaped = false
+
+  for (let index = startIndex; index < source.length; index += 1) {
+    const character = source[index]
+
+    if (inString) {
+      if (escaped) {
+        escaped = false
+        continue
+      }
+
+      if (character === '\\') {
+        escaped = true
+        continue
+      }
+
+      if (character === stringQuote) {
+        inString = false
+      }
+
+      continue
+    }
+
+    if (character === '"' || character === "'" || character === '`') {
+      inString = true
+      stringQuote = character
+      continue
+    }
+
+    if (character === '{') {
+      depth += 1
+      continue
+    }
+
+    if (character === '}') {
+      depth -= 1
+      if (depth === 0) {
+        return source.slice(startIndex, index + 1)
+      }
+    }
+  }
+
+  return undefined
+}
+
+function parseMetadataLiteral(literal: string): ComponentProjectComponentMetadata | undefined {
+  try {
+    const value = Function(`"use strict"; return (${literal});`)()
+    const parsed = ComponentProjectComponentMetadataSchema.safeParse(value)
+    return parsed.success ? parsed.data : undefined
+  } catch {
+    return undefined
+  }
+}
+
+function readMetadataFromSource(source: string): ComponentProjectComponentMetadata | undefined {
+  const candidates = [
+    /componentMetadata\s*=\s*defineComponentProjectComponentMetadata\s*\(/m,
+    /componentMetadata\s*=\s*VideoComponent\s*\(/m,
+    /componentMetadata\s*=\s*/m,
+  ]
+
+  for (const pattern of candidates) {
+    const match = pattern.exec(source)
+    if (!match) {
+      continue
+    }
+
+    const startIndex = source.indexOf('{', match.index)
+    if (startIndex < 0) {
+      continue
+    }
+
+    const literal = extractBalancedObjectLiteral(source, startIndex)
+    if (!literal) {
+      continue
+    }
+
+    const parsed = parseMetadataLiteral(literal)
+    if (parsed) {
+      return parsed
+    }
+  }
+
+  const decoratorMatch = /@VideoComponent\s*\((\{[\s\S]*?\})\)/m.exec(source)
+  if (decoratorMatch) {
+    return parseMetadataLiteral(decoratorMatch[1])
+  }
+
+  return undefined
+}
+
+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[] = []
+
+  for (const entry of entries) {
+    if (!entry.endsWith('.tsx')) {
+      continue
+    }
+
+    const absolutePath = path.join(componentsDir, entry)
+    const source = await fs.readFile(absolutePath, 'utf8')
+    const metadata = readMetadataFromSource(source)
+    if (!metadata) {
+      continue
+    }
+
+    discovered.push({
+      ...metadata,
+      sourceFile: path.relative(projectRoot, absolutePath),
+    })
+  }
+
+  return discovered.sort((left, right) => left.name.localeCompare(right.name))
+}

package/src/index.test.ts

@@ -0,0 +1,7 @@
+import { expect, test } from 'vitest'
+
+import { componentProjectHelperPackageName } from './index'
+
+test('exports the package name', () => {
+  expect(componentProjectHelperPackageName).toBe('@vibecuting/component-project-helper')
+})

package/src/index.ts

@@ -0,0 +1,26 @@
+export {
+  VideoComponent,
+  defineComponentProjectComponentMetadata,
+  getComponentProjectComponentMetadata,
+} from './decorators'
+export {
+  ComponentProjectComponentMetadataSchema,
+  ComponentProjectGeneratedManifestSchema,
+} from './schemas'
+export {
+  discoverComponentProjectComponents,
+  type ComponentProjectComponentDiscovery,
+} from './discovery'
+export {
+  renderComponentProjectMarkdown,
+  type ComponentProjectMarkdownDocument,
+} from './markdown'
+export {
+  resolveComponentProjectGeneratedDocsDir,
+  resolveComponentProjectGeneratedManifestPath,
+  resolveComponentProjectInstallRoot,
+} from './runtime'
+export { runComponentProjectPostinstall } from './lifecycle/postinstall'
+export { runComponentProjectPreuninstall } from './lifecycle/preuninstall'
+
+export const componentProjectHelperPackageName = '@vibecuting/component-project-helper' as const

package/src/lifecycle/postinstall.test.ts

@@ -0,0 +1,79 @@
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import { tmpdir } from 'node:os'
+
+import { expect, test } from 'vitest'
+
+import { runComponentProjectPostinstall } from './postinstall'
+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.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
+`,
+    '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
+`,
+    'utf8',
+  )
+
+  return projectRoot
+}
+
+test('postinstall generates markdown and preuninstall removes it', async () => {
+  const projectRoot = await createFixtureProjectRoot()
+  const docsDir = path.join(
+    projectRoot,
+    '.agents',
+    'skills',
+    'project-allow-component',
+    'components',
+  )
+  const manifestPath = path.join(
+    projectRoot,
+    '.agents',
+    'skills',
+    'project-allow-component',
+    'component-project-helper.manifest.json',
+  )
+
+  await runComponentProjectPostinstall(projectRoot)
+
+  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 runComponentProjectPreuninstall(projectRoot)
+
+  await expect(fs.stat(path.join(docsDir, 'SceneFrame.md'))).rejects.toMatchObject({
+    code: 'ENOENT',
+  })
+  await expect(fs.stat(path.join(docsDir, 'SceneTitle.md'))).rejects.toMatchObject({
+    code: 'ENOENT',
+  })
+  await expect(fs.stat(manifestPath)).rejects.toMatchObject({ code: 'ENOENT' })
+})

package/src/lifecycle/postinstall.ts

@@ -0,0 +1,71 @@
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { ComponentProjectGeneratedManifestSchema } from '../schemas'
+import { discoverComponentProjectComponents } from '../discovery'
+import { renderComponentProjectMarkdown } from '../markdown'
+import {
+  resolveComponentProjectGeneratedDocsDir,
+  resolveComponentProjectGeneratedManifestPath,
+  resolveComponentProjectInstallRoot,
+} from '../runtime'
+
+async function ensureDirectory(dir: string): Promise<void> {
+  await fs.mkdir(dir, { recursive: true })
+}
+
+async function removeStaleGeneratedFiles(
+  manifestPath: string,
+  nextFiles: string[],
+): Promise<void> {
+  try {
+    const previous = ComponentProjectGeneratedManifestSchema.parse(
+      JSON.parse(await fs.readFile(manifestPath, 'utf8')),
+    )
+    const staleFiles = previous.files.filter((filePath) => !nextFiles.includes(filePath))
+    await Promise.all(staleFiles.map((filePath) => fs.rm(filePath, { force: true })))
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== 'ENOENT') {
+      throw error
+    }
+  }
+}
+
+export async function runComponentProjectPostinstall(
+  projectRoot = resolveComponentProjectInstallRoot(),
+): Promise<void> {
+  const docsDir = resolveComponentProjectGeneratedDocsDir(projectRoot)
+  const manifestPath = resolveComponentProjectGeneratedManifestPath(projectRoot)
+  const components = await discoverComponentProjectComponents(projectRoot)
+
+  await ensureDirectory(docsDir)
+
+  const files: string[] = []
+
+  for (const component of components) {
+    const filePath = path.join(docsDir, `${component.name}.md`)
+    const markdown = renderComponentProjectMarkdown(component)
+    await fs.writeFile(filePath, markdown, 'utf8')
+    files.push(filePath)
+  }
+
+  await removeStaleGeneratedFiles(manifestPath, files)
+
+  const manifest = ComponentProjectGeneratedManifestSchema.parse({
+    projectRoot,
+    generatedAt: new Date().toISOString(),
+    docsDir,
+    files,
+  })
+
+  await fs.writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, 'utf8')
+}
+
+async function main(): Promise<void> {
+  await runComponentProjectPostinstall()
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === path.resolve(process.argv[1])) {
+  await main()
+}

package/src/lifecycle/preuninstall.ts

@@ -0,0 +1,39 @@
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { ComponentProjectGeneratedManifestSchema } from '../schemas'
+import { resolveComponentProjectGeneratedManifestPath } from '../runtime'
+
+export async function runComponentProjectPreuninstall(
+  projectRoot = process.env.INIT_CWD ??
+    process.env.npm_config_local_prefix ??
+    process.cwd(),
+): Promise<void> {
+  const manifestPath = resolveComponentProjectGeneratedManifestPath(projectRoot)
+
+  try {
+    const manifest = ComponentProjectGeneratedManifestSchema.parse(
+      JSON.parse(await fs.readFile(manifestPath, 'utf8')),
+    )
+
+    for (const filePath of manifest.files) {
+      await fs.rm(filePath, { force: true })
+    }
+
+    await fs.rm(manifestPath, { force: true })
+    await fs.rm(manifest.docsDir, { recursive: true, force: true })
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== 'ENOENT') {
+      throw error
+    }
+  }
+}
+
+async function main(): Promise<void> {
+  await runComponentProjectPreuninstall()
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === path.resolve(process.argv[1])) {
+  await main()
+}

package/src/markdown/index.test.ts

@@ -0,0 +1,20 @@
+import { expect, test } from 'vitest'
+
+import { renderComponentProjectMarkdown } from './index'
+
+test('renders markdown with metadata fields', () => {
+  const markdown = renderComponentProjectMarkdown({
+    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',
+  })
+
+  expect(markdown).toContain('# SceneFrame')
+  expect(markdown).toContain('SceneFrameProps')
+  expect(markdown).toContain('src/components/SceneFrame.tsx')
+  expect(markdown).toContain('16:9')
+})

package/src/markdown/index.ts

@@ -0,0 +1,43 @@
+import {
+  ComponentProjectComponentMetadataSchema,
+  type ComponentProjectComponentMetadata,
+} from '../schemas'
+
+export type ComponentProjectMarkdownDocument = ComponentProjectComponentMetadata
+
+function escapeInline(value: string): string {
+  return value.replaceAll('`', '\\`')
+}
+
+export function renderComponentProjectMarkdown(
+  input: ComponentProjectMarkdownDocument,
+): string {
+  const metadata = ComponentProjectComponentMetadataSchema.parse(input)
+  const tags = metadata.tags.length > 0 ? metadata.tags : ['component']
+
+  return [
+    '---',
+    `name: ${metadata.name}`,
+    `description: ${metadata.description}`,
+    `sourceFile: ${metadata.sourceFile}`,
+    `aspectRatio: ${metadata.aspectRatio}`,
+    `sceneType: ${metadata.sceneType ?? ''}`,
+    `propsTypeName: ${metadata.propsTypeName ?? ''}`,
+    'tags:',
+    ...tags.map((tag) => `  - ${tag}`),
+    '---',
+    '',
+    `# ${metadata.name}`,
+    '',
+    metadata.description,
+    '',
+    '## 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(', ')}`,
+    '',
+  ].join('\n')
+}

package/src/runtime/index.ts

@@ -0,0 +1,36 @@
+import path from 'node:path'
+import process from 'node:process'
+
+export function resolveComponentProjectInstallRoot(): string {
+  const candidates = [
+    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())
+}
+
+export function resolveComponentProjectGeneratedDocsDir(
+  projectRoot = resolveComponentProjectInstallRoot(),
+): string {
+  return path.join(
+    projectRoot,
+    '.agents',
+    'skills',
+    'project-allow-component',
+    'components',
+  )
+}
+
+export function resolveComponentProjectGeneratedManifestPath(
+  projectRoot = resolveComponentProjectInstallRoot(),
+): string {
+  return path.join(
+    projectRoot,
+    '.agents',
+    'skills',
+    'project-allow-component',
+    'component-project-helper.manifest.json',
+  )
+}

package/src/schemas/index.test.ts

@@ -0,0 +1,17 @@
+import { expect, test } from 'vitest'
+
+import { ComponentProjectComponentMetadataSchema } from './index'
+
+test('validates component metadata', () => {
+  const metadata = ComponentProjectComponentMetadataSchema.parse({
+    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',
+  })
+
+  expect(metadata.tags).toEqual(['layout', 'frame'])
+})

package/src/schemas/index.ts

@@ -0,0 +1,25 @@
+import { z } from 'zod'
+
+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(),
+})
+
+export const ComponentProjectGeneratedManifestSchema = z.object({
+  projectRoot: z.string().min(1),
+  generatedAt: z.string().min(1),
+  docsDir: z.string().min(1),
+  files: z.array(z.string().min(1)),
+})
+
+export type ComponentProjectComponentMetadata = z.infer<
+  typeof ComponentProjectComponentMetadataSchema
+>
+export type ComponentProjectGeneratedManifest = z.infer<
+  typeof ComponentProjectGeneratedManifestSchema
+>