@vibecuting/component-project-helper 0.1.15 → 0.1.17

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.15",
+  "version": "0.1.17",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",
   "main": "./src/index.ts",
@@ -20,8 +20,8 @@
     "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": "pnpm run update-component-meta",
     "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"
@@ -29,6 +29,7 @@
   "dependencies": {
     "reflect-metadata": "^0.2.2",
     "typescript": "^5.9.3",
+    "tsx": "^4.19.2",
     "zod": "4.1.12"
   },
   "devDependencies": {

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

@@ -43,3 +43,26 @@ test('attaches normalized metadata to decorated function components', () => {
   expect(decorated).toBe(SceneTitle)
   expect(getComponentProjectComponentMetadata(SceneTitle)).toEqual(metadata)
 })
+
+test('attaches metadata to components with required props', () => {
+  type RequiredProps = {
+    title: string
+  }
+
+  const metadata = defineComponentProjectComponentMetadata({
+    name: 'RequiredPropsScene',
+    description: 'Exercises required props support',
+    sourceFile: 'src/components/RequiredPropsScene.tsx',
+    aspectRatio: '16:9',
+    sceneType: 'scene',
+    tags: ['required', 'props'],
+    propsTypeName: 'RequiredProps',
+  })
+
+  const RequiredPropsScene = (_props: RequiredProps) => null
+
+  const decorated = VideoComponent(metadata)(RequiredPropsScene)
+
+  expect(decorated).toBe(RequiredPropsScene)
+  expect(getComponentProjectComponentMetadata(RequiredPropsScene)).toEqual(metadata)
+})

package/src/decorators/index.ts

@@ -1,40 +1,116 @@
-import 'reflect-metadata'
-
-import type { ComponentType } from 'react'
-
+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 ComponentType<any>>(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')
 })