@vibecuting/component-project-helper 0.1.16 → 0.1.18

package/src/index.ts

@@ -1,26 +1,68 @@
+export {
+  VIDEO_RESOURCE_METADATA_KEY,
+  BaseVideoResourceMetadataSchema,
+  ScenePluginMetadataSchema,
+  SceneSlotsSchema,
+  SceneSlotHintSchema,
+  ThemePluginMetadataSchema,
+  TransitionPluginMetadataSchema,
+  VideoResourceKindSchema,
+  VideoResourceMetadataSchema,
+  createVideoResourceAnnotation,
+  getVideoResourceMetadata,
+  type ScenePluginMetadata,
+  type SceneSlotHint,
+  type ThemePluginMetadata,
+  type TransitionPluginMetadata,
+  type VideoResourceAnnotation,
+  type VideoResourceDescriptor,
+  type VideoResourceKind,
+  type VideoResourceMetadata,
+} from './resources/video-resource'
+export {
+  sceneResourceDescriptor,
+  themeResourceDescriptor,
+  transitionResourceDescriptor,
+  videoResourceDescriptorDefinitions,
+  videoResourceDescriptors,
+} from './resources/resource-descriptors'
+export {
+  discoverComponentProjectComponents,
+  discoverVideoResources,
+  type DiscoveredVideoResource,
+} from './discovery'
+export {
+  generateVideoResourceMeta,
+  writeVideoResourceMeta,
+} from './meta/generate-video-resource-meta'
+export {
+  updateComponentMeta,
+} from './meta/update-component-meta'
+export {
+  updateComponentSkills,
+} from './meta/update-component-skills'
 export {
   VideoComponent,
   defineComponentProjectComponentMetadata,
+  defineScenePluginMetadata,
+  defineThemePluginMetadata,
+  defineTransitionPluginMetadata,
+  getScenePluginMetadata,
   getComponentProjectComponentMetadata,
+  getThemePluginMetadata,
+  getTransitionPluginMetadata,
+  ThemeComponent,
+  TransitionComponent,
 } from './decorators'
 export {
+  type ComponentProjectComponentMetadata,
   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/meta/generate-video-resource-meta.ts

@@ -0,0 +1,198 @@
+import crypto from 'node:crypto'
+import fs from 'node:fs/promises'
+import path from 'node:path'
+
+import type { DiscoveredVideoResource } from '../discovery/index.ts'
+
+type ResourceEntry = {
+  packageName: string
+  packageVersion: string
+}
+
+type GeneratedResourceRecord = {
+  packageName: string
+  exportName: string
+  metadata: DiscoveredVideoResource['metadata']
+}
+
+type GeneratedModuleInput = {
+  projectRoot: string
+  resources: DiscoveredVideoResource[]
+}
+
+function groupResourcesByPackage(resources: DiscoveredVideoResource[]): Map<string, DiscoveredVideoResource[]> {
+  const result = new Map<string, DiscoveredVideoResource[]>()
+
+  for (const resource of resources) {
+    const items = result.get(resource.packageName) ?? []
+    items.push(resource)
+    result.set(resource.packageName, items)
+  }
+
+  for (const [packageName, items] of result.entries()) {
+    result.set(
+      packageName,
+      items.sort((left, right) => left.exportName.localeCompare(right.exportName)),
+    )
+  }
+
+  return result
+}
+
+function stableJson(value: unknown): string {
+  return JSON.stringify(
+    value,
+    (_key, nestedValue) => {
+      if (nestedValue && typeof nestedValue === 'object' && !Array.isArray(nestedValue)) {
+        return Object.fromEntries(
+          Object.entries(nestedValue as Record<string, unknown>).sort(([left], [right]) =>
+            left.localeCompare(right),
+          ),
+        )
+      }
+
+      return nestedValue
+    },
+    2,
+  )
+}
+
+function createFingerprint(resources: DiscoveredVideoResource[]): string {
+  const hash = crypto.createHash('sha256')
+  hash.update(
+    stableJson(
+      resources.map((resource) => ({
+        packageName: resource.packageName,
+        packageVersion: resource.packageVersion,
+        exportName: resource.exportName,
+        annotationName: resource.annotationName,
+        metadata: resource.metadata,
+        sourceDigest: resource.sourceDigest,
+      })),
+    ),
+  )
+  return `sha256:${hash.digest('hex')}`
+}
+
+function buildImportSpecifier(projectRoot: string, resource: DiscoveredVideoResource): string {
+  if (resource.packageRoot !== projectRoot) {
+    return resource.packageName
+  }
+
+  const relativePath = path
+    .relative(path.join(projectRoot, '.vibecuting'), path.join(projectRoot, resource.sourceFile))
+    .replaceAll(path.sep, '/')
+    .replace(/\.(tsx?|jsx?|mjs|cjs)$/, '')
+
+  return relativePath.startsWith('.') ? relativePath : `./${relativePath}`
+}
+
+function buildImports(projectRoot: string, resources: DiscoveredVideoResource[]): string {
+  const grouped = new Map<string, DiscoveredVideoResource[]>()
+
+  for (const resource of resources) {
+    const specifier = buildImportSpecifier(projectRoot, resource)
+    const items = grouped.get(specifier) ?? []
+    items.push(resource)
+    grouped.set(specifier, items)
+  }
+
+  return Array.from(grouped.entries())
+    .map(([specifier, packageResources]) => {
+      const names = packageResources.map((resource) => resource.exportName).join(', ')
+      return `import { ${names} } from '${specifier}'`
+    })
+    .join('\n')
+}
+
+function buildRegistryArray(
+  name: string,
+  kind: DiscoveredVideoResource['metadata']['resourceKind'],
+  resources: DiscoveredVideoResource[],
+): string {
+  const imports = resources
+    .filter((resource) => resource.metadata.resourceKind === kind)
+    .map((resource) => resource.exportName)
+
+  const factoryName =
+    kind === 'scene'
+      ? 'createScenePluginRegistry'
+      : kind === 'transition'
+        ? 'createTransitionPluginRegistry'
+        : 'createSceneThemeRegistry'
+
+  return `export const ${name} = ${factoryName}([${imports.join(', ')}])`
+}
+
+function buildMetadataRecords(resources: DiscoveredVideoResource[]): GeneratedResourceRecord[] {
+  return resources.map((resource) => ({
+    packageName: resource.packageName,
+    exportName: resource.exportName,
+    metadata: resource.metadata,
+  }))
+}
+
+export async function generateVideoResourceMeta({
+  projectRoot,
+  resources,
+}: GeneratedModuleInput): Promise<{ filePath: string; contents: string }> {
+  const sortedResources = [...resources].sort((left, right) => {
+    return (
+      left.packageName.localeCompare(right.packageName) ||
+      left.metadata.resourceKind.localeCompare(right.metadata.resourceKind) ||
+      left.metadata.pluginKey.localeCompare(right.metadata.pluginKey) ||
+      left.exportName.localeCompare(right.exportName)
+    )
+  })
+
+  const filePath = path.join(projectRoot, '.vibecuting', 'video-resource-meta.generated.ts')
+  const fingerprint = createFingerprint(sortedResources)
+  const packageEntries: ResourceEntry[] = []
+  const seenPackages = new Set<string>()
+
+  for (const resource of sortedResources) {
+    if (seenPackages.has(resource.packageName)) {
+      continue
+    }
+
+    seenPackages.add(resource.packageName)
+    packageEntries.push({
+      packageName: resource.packageName,
+      packageVersion: resource.packageVersion,
+    })
+  }
+
+  const contents = [
+    '// Generated by update-component-meta. Do not edit.',
+    '',
+    buildImports(projectRoot, sortedResources),
+    "import { createScenePluginRegistry, createSceneThemeRegistry, createTransitionPluginRegistry } from '@vibecuting/video-project-core'",
+    '',
+    `export const videoResourceMeta = ${stableJson({
+      schemaVersion: 1,
+      packageFingerprint: fingerprint,
+      packages: packageEntries,
+      resources: buildMetadataRecords(sortedResources),
+    })} as const`,
+    '',
+    buildRegistryArray('installedScenePluginRegistry', 'scene', sortedResources),
+    buildRegistryArray('installedTransitionPluginRegistry', 'transition', sortedResources),
+    buildRegistryArray('installedSceneThemeRegistry', 'theme', sortedResources),
+    '',
+  ]
+    .filter(Boolean)
+    .join('\n')
+
+  return { filePath, contents }
+}
+
+export async function writeVideoResourceMeta(
+  input: GeneratedModuleInput,
+): Promise<{ filePath: string; contents: string }> {
+  const generated = await generateVideoResourceMeta(input)
+  await fs.mkdir(path.dirname(generated.filePath), { recursive: true })
+  const tempPath = `${generated.filePath}.tmp`
+  await fs.writeFile(tempPath, `${generated.contents}\n`, 'utf8')
+  await fs.rename(tempPath, generated.filePath)
+  return generated
+}

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

@@ -0,0 +1,64 @@
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import { tmpdir } from 'node:os'
+
+import { expect, test } from 'vitest'
+
+import { updateComponentMeta } from './update-component-meta'
+
+test('writes and checks the unified video resource metadata file', async () => {
+  const projectRoot = await fs.mkdtemp(path.join(tmpdir(), 'component-project-helper-meta-'))
+  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(packageRoot, 'package.json'),
+    JSON.stringify({
+      name: '@vibecuting/demo-pack',
+      version: '0.1.0',
+      main: './src/index.ts',
+      types: './src/index.ts',
+    }),
+    'utf8',
+  )
+
+  await fs.writeFile(
+    path.join(srcRoot, 'index.ts'),
+    `
+      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',
+        sceneFamily: 'custom',
+        rootLayout: 'absolute-fill',
+      })
+
+      export const DemoScene = VideoComponent(sceneMetadata)(
+        defineSceneComponent({
+          family: 'custom',
+          propsSchema: null,
+          component: function DemoScene() {
+            return null
+          },
+        }),
+      )
+    `,
+    'utf8',
+  )
+
+  await updateComponentMeta(projectRoot)
+
+  const generatedFilePath = path.join(projectRoot, '.vibecuting', 'video-resource-meta.generated.ts')
+  const generatedContents = await fs.readFile(generatedFilePath, 'utf8')
+
+  expect(generatedContents).toContain('installedScenePluginRegistry')
+  expect(generatedContents).toContain('DemoScene')
+
+  await expect(updateComponentMeta(projectRoot, true)).resolves.toBeUndefined()
+})

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

@@ -0,0 +1,47 @@
+import fs from 'node:fs/promises'
+import path from 'node:path'
+
+import { discoverVideoResources } from '../discovery/index.ts'
+import { generateVideoResourceMeta } from './generate-video-resource-meta.ts'
+
+export async function updateComponentMeta(projectRoot: string, checkOnly = false): Promise<void> {
+  const resources = await discoverVideoResources(projectRoot)
+  const generated = await generateVideoResourceMeta({ projectRoot, resources })
+  const currentContents = await readOptionalFile(generated.filePath)
+
+  if (checkOnly) {
+    if (currentContents?.trimEnd() !== generated.contents.trimEnd()) {
+      throw new Error('Generated video resource metadata is stale. Run pnpm run update-component-meta')
+    }
+
+    return
+  }
+
+  await fs.mkdir(path.dirname(generated.filePath), { recursive: true })
+  const tempFilePath = `${generated.filePath}.tmp`
+  await fs.writeFile(tempFilePath, `${generated.contents}\n`, 'utf8')
+  await fs.rename(tempFilePath, generated.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
+  }
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const checkOnly = process.argv.includes('--check')
+  const cwd = process.cwd()
+
+  updateComponentMeta(cwd, checkOnly).catch((error: unknown) => {
+    const message = error instanceof Error ? error.message : String(error)
+    console.error(message)
+    process.exitCode = 1
+  })
+}

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()
+})