@vibecuting/component-project-helper 0.1.15 → 0.1.17

package/src/index.ts

@@ -1,26 +1,65 @@
+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 {
   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/resources/resource-descriptors.ts

@@ -0,0 +1,47 @@
+import { createRequire } from 'node:module'
+import type {
+  ScenePluginMetadata,
+  ThemePluginMetadata,
+  TransitionPluginMetadata,
+  VideoResourceDescriptor,
+  VideoResourceMetadata,
+} from './video-resource.ts'
+import {
+  ScenePluginMetadataSchema,
+  ThemePluginMetadataSchema,
+  TransitionPluginMetadataSchema,
+} from './video-resource.ts'
+
+const require = createRequire(import.meta.url)
+const videoResourceDescriptorDefinitionRows = require('./video-resource-descriptors.json')
+
+export const videoResourceDescriptorDefinitions = videoResourceDescriptorDefinitionRows
+
+export type VideoResourceDescriptorDefinition = (typeof videoResourceDescriptorDefinitions)[number]
+
+export const sceneResourceDescriptor: VideoResourceDescriptor<ScenePluginMetadata> = {
+  kind: 'scene',
+  annotationName: 'VideoComponent',
+  metadataFactoryName: 'defineScenePluginMetadata',
+  schema: ScenePluginMetadataSchema,
+}
+
+export const transitionResourceDescriptor: VideoResourceDescriptor<TransitionPluginMetadata> = {
+  kind: 'transition',
+  annotationName: 'TransitionComponent',
+  metadataFactoryName: 'defineTransitionPluginMetadata',
+  schema: TransitionPluginMetadataSchema,
+}
+
+export const themeResourceDescriptor: VideoResourceDescriptor<ThemePluginMetadata> = {
+  kind: 'theme',
+  annotationName: 'ThemeComponent',
+  metadataFactoryName: 'defineThemePluginMetadata',
+  schema: ThemePluginMetadataSchema,
+}
+
+export const videoResourceDescriptors = [
+  sceneResourceDescriptor,
+  transitionResourceDescriptor,
+  themeResourceDescriptor,
+] as const satisfies readonly VideoResourceDescriptor<VideoResourceMetadata>[]

package/src/resources/video-resource-descriptors.json

@@ -0,0 +1,17 @@
+[
+  {
+    "kind": "scene",
+    "annotationName": "VideoComponent",
+    "metadataFactoryName": "defineScenePluginMetadata"
+  },
+  {
+    "kind": "transition",
+    "annotationName": "TransitionComponent",
+    "metadataFactoryName": "defineTransitionPluginMetadata"
+  },
+  {
+    "kind": "theme",
+    "annotationName": "ThemeComponent",
+    "metadataFactoryName": "defineThemePluginMetadata"
+  }
+]

package/src/resources/video-resource.ts

@@ -0,0 +1,143 @@
+import 'reflect-metadata'
+
+import { z } from 'zod'
+
+export const VideoResourceKindSchema = z.enum(['scene', 'transition', 'theme'])
+
+export type VideoResourceKind = z.infer<typeof VideoResourceKindSchema>
+
+export const BaseVideoResourceMetadataSchema = z.object({
+  resourceKind: VideoResourceKindSchema,
+  name: z.string().min(1),
+  description: z.string().min(1),
+  sourceFile: z.string().min(1),
+  pluginKey: z.string().min(1),
+  tags: z.array(z.string().min(1)).default([]),
+})
+
+export const SceneSlotHintSchema = z.object({
+  name: z.string().min(1),
+  description: z.string().min(1).optional(),
+  required: z.boolean().optional(),
+  accepts: z.enum(['text', 'image', 'video', 'component', 'any']).optional(),
+})
+
+export const SceneSlotsSchema = z.union([
+  z.array(z.string().min(1)),
+  z.array(SceneSlotHintSchema),
+])
+
+const SceneFamilySchema = z.enum(['slide', 'canvas-2d', 'game-2d', 'three-3d', 'custom'])
+
+export const ScenePluginMetadataSchema = BaseVideoResourceMetadataSchema.extend({
+  resourceKind: z.literal('scene'),
+  aspectRatio: z.enum(['9:16', '16:9']),
+  sceneType: z.enum(['intro', 'scene', 'outro']).optional(),
+  sceneFamily: SceneFamilySchema.default('custom'),
+  themePreset: z.string().min(1).optional(),
+  slots: SceneSlotsSchema.optional(),
+  propsTypeName: z.string().min(1).optional(),
+  rootLayout: z.literal('absolute-fill').default('absolute-fill'),
+})
+
+export const TransitionPluginMetadataSchema = BaseVideoResourceMetadataSchema.extend({
+  resourceKind: z.literal('transition'),
+  transitionKind: z.enum(['transition', 'overlay']),
+})
+
+export const ThemePluginMetadataSchema = BaseVideoResourceMetadataSchema.extend({
+  resourceKind: z.literal('theme'),
+  supportedSceneFamilies: z.array(SceneFamilySchema).default([]),
+  cssVariables: z.array(z.string().regex(/^--scene-/)).default([]),
+})
+
+export const VideoResourceMetadataSchema = z.discriminatedUnion('resourceKind', [
+  ScenePluginMetadataSchema,
+  TransitionPluginMetadataSchema,
+  ThemePluginMetadataSchema,
+])
+
+export type ScenePluginMetadata = z.infer<typeof ScenePluginMetadataSchema>
+export type SceneSlotHint = z.infer<typeof SceneSlotHintSchema>
+export type TransitionPluginMetadata = z.infer<typeof TransitionPluginMetadataSchema>
+export type ThemePluginMetadata = z.infer<typeof ThemePluginMetadataSchema>
+export type VideoResourceMetadata = z.infer<typeof VideoResourceMetadataSchema>
+
+export const VIDEO_RESOURCE_METADATA_KEY = Symbol.for(
+  '@vibecuting/component-project-helper/video-resource-metadata',
+)
+
+export type VideoResourceDescriptor<TMetadata extends VideoResourceMetadata> = {
+  kind: TMetadata['resourceKind']
+  annotationName: string
+  metadataFactoryName: string
+  schema: z.ZodType<TMetadata>
+}
+
+export type VideoResourceAnnotation<TMetadata extends VideoResourceMetadata> = {
+  defineMetadata(input: TMetadata): TMetadata
+  annotate(metadata: TMetadata): <T extends object>(target: T) => T
+  getMetadata(target: unknown): TMetadata | undefined
+}
+
+export function createVideoResourceAnnotation<TMetadata extends VideoResourceMetadata>(
+  descriptor: VideoResourceDescriptor<TMetadata>,
+): VideoResourceAnnotation<TMetadata> {
+  return {
+    defineMetadata(input) {
+      return descriptor.schema.parse(input)
+    },
+    annotate(metadata) {
+      const normalized = descriptor.schema.parse(metadata)
+
+      return function annotateTarget<T extends object>(target: T): T {
+        Reflect.defineMetadata(VIDEO_RESOURCE_METADATA_KEY, normalized, target)
+        return target
+      }
+    },
+    getMetadata(target) {
+      if (!target || (typeof target !== 'object' && typeof target !== 'function')) {
+        return undefined
+      }
+
+      const metadata = Reflect.getMetadata(VIDEO_RESOURCE_METADATA_KEY, target)
+      const parsed = descriptor.schema.safeParse(metadata)
+      return parsed.success ? parsed.data : undefined
+    },
+  }
+}
+
+export function getVideoResourceMetadata<TMetadata extends VideoResourceMetadata>(
+  target: unknown,
+  expectedKind?: TMetadata['resourceKind'],
+): TMetadata | undefined {
+  if (!target || (typeof target !== 'object' && typeof target !== 'function')) {
+    return undefined
+  }
+
+  const metadata = Reflect.getMetadata(VIDEO_RESOURCE_METADATA_KEY, target)
+  const parsed = VideoResourceMetadataSchema.safeParse(metadata)
+  if (!parsed.success) {
+    return undefined
+  }
+
+  if (expectedKind && parsed.data.resourceKind !== expectedKind) {
+    return undefined
+  }
+
+  return parsed.data as TMetadata
+}
+
+export function defineScenePluginMetadata(input: ScenePluginMetadata): ScenePluginMetadata {
+  return ScenePluginMetadataSchema.parse(input)
+}
+
+export function defineTransitionPluginMetadata(
+  input: TransitionPluginMetadata,
+): TransitionPluginMetadata {
+  return TransitionPluginMetadataSchema.parse(input)
+}
+
+export function defineThemePluginMetadata(input: ThemePluginMetadata): ThemePluginMetadata {
+  return ThemePluginMetadataSchema.parse(input)
+}

package/src/schemas/index.ts

@@ -1,6 +1,25 @@
 import { z } from 'zod'
 
-export const ComponentProjectComponentMetadataSchema = z.object({
+export {
+  BaseVideoResourceMetadataSchema,
+  ScenePluginMetadataSchema,
+  SceneSlotHintSchema,
+  SceneSlotsSchema,
+  ThemePluginMetadataSchema,
+  TransitionPluginMetadataSchema,
+  VideoResourceKindSchema,
+  VideoResourceMetadataSchema,
+} from '../resources/video-resource.ts'
+export type {
+  ScenePluginMetadata,
+  SceneSlotHint,
+  ThemePluginMetadata,
+  TransitionPluginMetadata,
+  VideoResourceKind,
+  VideoResourceMetadata,
+} from '../resources/video-resource.ts'
+
+const ComponentProjectComponentMetadataInputSchema = z.object({
   name: z.string().min(1),
   description: z.string().min(1),
   sourceFile: z.string().min(1),
@@ -10,6 +29,9 @@ export const ComponentProjectComponentMetadataSchema = z.object({
   propsTypeName: z.string().min(1).optional(),
 })
 
+export const ComponentProjectComponentMetadataSchema =
+  ComponentProjectComponentMetadataInputSchema
+
 export const ComponentProjectGeneratedManifestSchema = z.object({
   projectRoot: z.string().min(1),
   generatedAt: z.string().min(1),
@@ -18,7 +40,7 @@ export const ComponentProjectGeneratedManifestSchema = z.object({
 })
 
 export type ComponentProjectComponentMetadata = z.infer<
-  typeof ComponentProjectComponentMetadataSchema
+  typeof ComponentProjectComponentMetadataInputSchema
 >
 export type ComponentProjectGeneratedManifest = z.infer<
   typeof ComponentProjectGeneratedManifestSchema