@vibecuting/component-project-helper 0.1.11 → 0.1.13

package/README.md

@@ -10,7 +10,7 @@ NPM 地址：
 
 - 作为可发布的 npm 包承载组件工程辅助逻辑。
 - 提供组件注解、schema、发现器、Markdown 生成和安装期生命周期逻辑。
-- 安装时扫描 `src/components/**/*.tsx`、`src/video/chapters/**/*.tsx` 以及 `node_modules/@vibecuting/*/src/**/*.tsx`，把组件元数据生成到 `.agents/skills/project-allow-component/components/`。
+- 安装时会优先把当前工程识别为包含 `src/components` 或 `src/video/chapters` 的独立项目，再扫描 `src/components/**/*.tsx`、`src/video/chapters/**/*.tsx` 以及 `node_modules/@vibecuting/*/src/**/*.tsx`，把组件元数据生成到 `.agents/skills/project-allow-component/components/`。
 - 通过 `postinstall` / `preuninstall` 维护生成文件和清理清单。
 - 安装时会给宿主工程的 `package.json` 补上 `update-component-skills`，它会调用同一套 `postinstall` 逻辑。
 - 宿主工程也可以直接运行 `pnpm update-component-skills` 手动刷新同一套生成结果。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibecuting/component-project-helper",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",
   "main": "./src/index.ts",

package/scripts/package-json.mjs

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

package/scripts/postinstall.mjs

@@ -2,6 +2,7 @@ import fs from 'node:fs/promises'
 import path from 'node:path'
 
 import { discoverComponentProjectComponents } from './discover-components.mjs'
+import { ensureComponentProjectSkillsScript } from './package-json.mjs'
 import {
   resolveComponentProjectGeneratedDocsDir,
   resolveComponentProjectGeneratedManifestPath,
@@ -33,6 +34,16 @@ export async function runComponentProjectPostinstall(projectRoot = resolveCompon
   const manifestPath = resolveComponentProjectGeneratedManifestPath(projectRoot)
   const components = await discoverComponentProjectComponents(projectRoot)
 
+  console.log('[component-project-helper] postinstall start')
+  console.log(`[component-project-helper] project root: ${projectRoot}`)
+  console.log(`[component-project-helper] docs dir: ${docsDir}`)
+  console.log(`[component-project-helper] manifest path: ${manifestPath}`)
+  console.log(
+    `[component-project-helper] discovered ${components.length} component(s): ${
+      components.map((component) => component.name).join(', ') || '(none)'
+    }`,
+  )
+
   await ensureDirectory(docsDir)
 
   const files = []
@@ -40,9 +51,21 @@ export async function runComponentProjectPostinstall(projectRoot = resolveCompon
     const filePath = path.join(docsDir, `${component.name}.md`)
     await fs.writeFile(filePath, renderComponentProjectMarkdown(component), 'utf8')
     files.push(filePath)
+    console.log(
+      `[component-project-helper] wrote ${path.relative(projectRoot, filePath)} <- ${component.sourceFile}`,
+    )
   }
 
+  console.log(
+    `[component-project-helper] cleaning stale docs relative to manifest ${path.relative(
+      projectRoot,
+      manifestPath,
+    )}`,
+  )
   await removeStaleGeneratedFiles(manifestPath, files)
+  await ensureComponentProjectSkillsScript(projectRoot)
+  console.log('[component-project-helper] ensured update-component-skills script')
+  console.log('[component-project-helper] ensured stale docs cleaned')
 
   const manifest = ComponentProjectGeneratedManifestSchema.parse({
     projectRoot,
@@ -51,6 +74,9 @@ export async function runComponentProjectPostinstall(projectRoot = resolveCompon
     files,
   })
   await fs.writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, 'utf8')
+  console.log(
+    `[component-project-helper] postinstall complete, manifest files: ${files.length}`,
+  )
 }
 
 const isDirectRun = process.argv[1] && path.resolve(process.argv[1]) === path.resolve(new URL(import.meta.url).pathname)

package/scripts/preuninstall.mjs

@@ -3,6 +3,7 @@ import path from 'node:path'
 
 import { resolveComponentProjectGeneratedManifestPath } from './runtime-root.mjs'
 import { ComponentProjectGeneratedManifestSchema } from './schemas.mjs'
+import { removeComponentProjectSkillsScript } from './package-json.mjs'
 
 export async function runComponentProjectPreuninstall(
   projectRoot = process.env.INIT_CWD ?? process.env.npm_config_local_prefix ?? process.cwd(),
@@ -25,6 +26,8 @@ export async function runComponentProjectPreuninstall(
       throw error
     }
   }
+
+  await removeComponentProjectSkillsScript(projectRoot)
 }
 
 const isDirectRun = process.argv[1] && path.resolve(process.argv[1]) === path.resolve(new URL(import.meta.url).pathname)

package/scripts/runtime-root.mjs

@@ -3,7 +3,10 @@ import fs from 'node:fs'
 import process from 'node:process'
 
 function hasComponentProjectSourceDir(directory) {
-  return fs.existsSync(path.join(directory, 'src', 'components'))
+  return (
+    fs.existsSync(path.join(directory, 'src', 'components')) ||
+    fs.existsSync(path.join(directory, 'src', 'video', 'chapters'))
+  )
 }
 
 function findComponentProjectInstallRoot(startDirectory) {

package/src/lifecycle/package-json.ts

@@ -7,7 +7,15 @@ export const componentProjectSkillsScriptCommand =
 
 async function readPackageJson(projectRoot: string): Promise<Record<string, unknown>> {
   const packageJsonPath = path.join(projectRoot, 'package.json')
-  return JSON.parse(await fs.readFile(packageJsonPath, 'utf8'))
+  try {
+    return JSON.parse(await fs.readFile(packageJsonPath, 'utf8'))
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+      return undefined as never
+    }
+
+    throw error
+  }
 }
 
 async function writePackageJson(
@@ -20,6 +28,10 @@ async function writePackageJson(
 
 export async function ensureComponentProjectSkillsScript(projectRoot: string): Promise<void> {
   const packageJson = await readPackageJson(projectRoot)
+  if (!packageJson) {
+    return
+  }
+
   const scripts = (packageJson.scripts as Record<string, string> | undefined) ?? {}
 
   if (scripts[componentProjectSkillsScriptName] !== componentProjectSkillsScriptCommand) {
@@ -33,6 +45,10 @@ export async function ensureComponentProjectSkillsScript(projectRoot: string): P
 
 export async function removeComponentProjectSkillsScript(projectRoot: string): Promise<void> {
   const packageJson = await readPackageJson(projectRoot)
+  if (!packageJson) {
+    return
+  }
+
   const scripts = (packageJson.scripts as Record<string, string> | undefined) ?? {}
 
   if (scripts[componentProjectSkillsScriptName] !== componentProjectSkillsScriptCommand) {

package/src/lifecycle/postinstall.ts

@@ -40,6 +40,16 @@ export async function runComponentProjectPostinstall(
   const manifestPath = resolveComponentProjectGeneratedManifestPath(projectRoot)
   const components = await discoverComponentProjectComponents(projectRoot)
 
+  console.log('[component-project-helper] postinstall start')
+  console.log(`[component-project-helper] project root: ${projectRoot}`)
+  console.log(`[component-project-helper] docs dir: ${docsDir}`)
+  console.log(`[component-project-helper] manifest path: ${manifestPath}`)
+  console.log(
+    `[component-project-helper] discovered ${components.length} component(s): ${
+      components.map((component) => component.name).join(', ') || '(none)'
+    }`,
+  )
+
   await ensureDirectory(docsDir)
 
   const files: string[] = []
@@ -49,10 +59,20 @@ export async function runComponentProjectPostinstall(
     const markdown = renderComponentProjectMarkdown(component)
     await fs.writeFile(filePath, markdown, 'utf8')
     files.push(filePath)
+    console.log(
+      `[component-project-helper] wrote ${path.relative(projectRoot, filePath)} <- ${component.sourceFile}`,
+    )
   }
 
+  console.log(
+    `[component-project-helper] cleaning stale docs relative to manifest ${path.relative(
+      projectRoot,
+      manifestPath,
+    )}`,
+  )
   await removeStaleGeneratedFiles(manifestPath, files)
   await ensureComponentProjectSkillsScript(projectRoot)
+  console.log('[component-project-helper] ensured update-component-skills script')
 
   const manifest = ComponentProjectGeneratedManifestSchema.parse({
     projectRoot,
@@ -62,6 +82,9 @@ export async function runComponentProjectPostinstall(
   })
 
   await fs.writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, 'utf8')
+  console.log(
+    `[component-project-helper] postinstall complete, manifest files: ${files.length}`,
+  )
 }
 
 async function main(): Promise<void> {

package/src/runtime/index.test.ts

@@ -0,0 +1,26 @@
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import { tmpdir } from 'node:os'
+import { afterEach, expect, test, vi } from 'vitest'
+
+import { resolveComponentProjectInstallRoot } from './index'
+
+afterEach(() => {
+  vi.unstubAllEnvs()
+  vi.restoreAllMocks()
+})
+
+test('resolves a video project template root before a parent monorepo root', async () => {
+  const workspaceRoot = await fs.mkdtemp(path.join(tmpdir(), 'component-project-helper-runtime-'))
+  const monorepoRoot = path.join(workspaceRoot, 'repo')
+  const videoProjectRoot = path.join(monorepoRoot, 'project-templates', 'video-project')
+
+  await fs.mkdir(path.join(monorepoRoot, 'src', 'components'), { recursive: true })
+  await fs.mkdir(path.join(videoProjectRoot, 'src', 'video', 'chapters'), { recursive: true })
+
+  vi.stubEnv('INIT_CWD', path.join(videoProjectRoot, 'src', 'video'))
+  vi.stubEnv('npm_config_local_prefix', '')
+  vi.spyOn(process, 'cwd').mockReturnValue(path.join(videoProjectRoot, 'src', 'video'))
+
+  expect(resolveComponentProjectInstallRoot()).toBe(videoProjectRoot)
+})

package/src/runtime/index.ts

@@ -3,7 +3,10 @@ import fs from 'node:fs'
 import process from 'node:process'
 
 function hasComponentProjectSourceDir(directory: string): boolean {
-  return fs.existsSync(path.join(directory, 'src', 'components'))
+  return (
+    fs.existsSync(path.join(directory, 'src', 'components')) ||
+    fs.existsSync(path.join(directory, 'src', 'video', 'chapters'))
+  )
 }
 
 function findComponentProjectInstallRoot(startDirectory: string): string | undefined {