@vibe-forge/workspace-assets 0.8.0 → 0.8.4

package/__tests__/prompt-selection.spec.ts

@@ -0,0 +1,388 @@
+import { join } from 'node:path'
+
+import { describe, expect, it } from 'vitest'
+
+import { resolvePromptAssetSelection, resolveWorkspaceAssetBundle } from '#~/index.js'
+
+import { createWorkspace, installPluginPackage, writeDocument } from './test-helpers'
+
+describe('resolvePromptAssetSelection', () => {
+  it('embeds only alwaysApply rules and keeps optional rules as summaries', async () => {
+    const workspace = await createWorkspace()
+
+    await writeDocument(
+      join(workspace, '.ai/rules/base.md'),
+      [
+        '---',
+        'alwaysApply: true',
+        'description: 基础约束',
+        '---',
+        '始终检查公共边界。'
+      ].join('\n')
+    )
+    await writeDocument(
+      join(workspace, '.ai/rules/optional.md'),
+      [
+        '---',
+        'alwaysApply: false',
+        'description: 按需参考规则',
+        '---',
+        '只有在特定场景才需要展开。'
+      ].join('\n')
+    )
+
+    const bundle = await resolveWorkspaceAssetBundle({
+      cwd: workspace,
+      useDefaultVibeForgeMcpServer: false
+    })
+    const [, options] = await resolvePromptAssetSelection({
+      bundle,
+      type: undefined
+    })
+
+    expect(options.systemPrompt).toContain('# base')
+    expect(options.systemPrompt).toContain('> 始终检查公共边界。')
+    expect(options.systemPrompt).toContain('# optional')
+    expect(options.systemPrompt).toContain('> 适用场景：按需参考规则')
+    expect(options.systemPrompt).toContain('> 规则文件路径：.ai/rules/optional.md')
+    expect(options.systemPrompt).toContain('> 仅在任务满足上述场景时，再阅读该规则文件。')
+    expect(options.systemPrompt).not.toContain('> 只有在特定场景才需要展开。')
+  })
+
+  it('selects local assets by short name and scoped plugin assets explicitly', async () => {
+    const workspace = await createWorkspace()
+
+    await installPluginPackage(workspace, '@vibe-forge/plugin-demo', {
+      'package.json': JSON.stringify(
+        {
+          name: '@vibe-forge/plugin-demo',
+          version: '1.0.0'
+        },
+        null,
+        2
+      ),
+      'specs/release/index.md': '---\ndescription: 插件发布流程\n---\n执行插件发布'
+    })
+    await writeDocument(
+      join(workspace, '.ai/specs/release.md'),
+      '---\ndescription: 项目发布流程\n---\n执行项目发布'
+    )
+
+    const bundle = await resolveWorkspaceAssetBundle({
+      cwd: workspace,
+      configs: [{
+        plugins: [
+          { id: 'demo', scope: 'demo' }
+        ]
+      }, undefined],
+      useDefaultVibeForgeMcpServer: false
+    })
+    const [localData, localOptions] = await resolvePromptAssetSelection({
+      bundle,
+      type: 'spec',
+      name: 'release'
+    })
+    const [pluginData, pluginOptions] = await resolvePromptAssetSelection({
+      bundle,
+      type: 'spec',
+      name: 'demo/release'
+    })
+    const localSpecId = bundle.specs.find(asset => asset.origin === 'workspace' && asset.name === 'release')?.id
+    const pluginSpecId = bundle.specs.find(asset => asset.origin === 'plugin' && asset.displayName === 'demo/release')
+      ?.id
+
+    expect(localData.targetBody).toContain('执行项目发布')
+    expect(localData.targetBody).not.toContain('执行插件发布')
+    expect(localOptions.systemPrompt).toContain('项目发布流程')
+    expect(localOptions.systemPrompt).toContain('demo/release')
+    expect(localOptions.promptAssetIds).toEqual(expect.arrayContaining([localSpecId]))
+
+    expect(pluginData.targetBody).toContain('执行插件发布')
+    expect(pluginOptions.systemPrompt).toContain('插件发布流程')
+    expect(pluginOptions.promptAssetIds).toEqual(expect.arrayContaining([pluginSpecId]))
+  })
+
+  it('formats rules as markdown headings and blockquotes', async () => {
+    const workspace = await createWorkspace()
+
+    await writeDocument(
+      join(workspace, '.ai/rules/required.md'),
+      [
+        '---',
+        'description: 必须执行的规则',
+        'alwaysApply: true',
+        '---',
+        '# 标题',
+        '',
+        '正文第一行',
+        '正文第二行'
+      ].join('\n')
+    )
+    await writeDocument(
+      join(workspace, '.ai/rules/summary-only.md'),
+      [
+        '---',
+        'description: 只展示摘要',
+        'alwaysApply: false',
+        '---',
+        '不应该出现在引用正文里'
+      ].join('\n')
+    )
+
+    const bundle = await resolveWorkspaceAssetBundle({
+      cwd: workspace,
+      configs: [undefined, undefined],
+      useDefaultVibeForgeMcpServer: false
+    })
+    const [, resolvedOptions] = await resolvePromptAssetSelection({
+      bundle,
+      type: undefined
+    })
+
+    expect(resolvedOptions.systemPrompt).toContain('# required')
+    expect(resolvedOptions.systemPrompt).toContain('> # 标题')
+    expect(resolvedOptions.systemPrompt).toContain('> 正文第一行')
+    expect(resolvedOptions.systemPrompt).toContain('> 正文第二行')
+    expect(resolvedOptions.systemPrompt).toContain('# summary-only')
+    expect(resolvedOptions.systemPrompt).toContain('> 适用场景：只展示摘要')
+    expect(resolvedOptions.systemPrompt).toContain('> 规则文件路径：.ai/rules/summary-only.md')
+    expect(resolvedOptions.systemPrompt).not.toContain('> 不应该出现在引用正文里')
+    expect(resolvedOptions.systemPrompt).not.toContain('--------------------')
+  })
+
+  it('keeps skills as route-only guidance unless the target spec references them', async () => {
+    const workspace = await createWorkspace()
+
+    await writeDocument(
+      join(workspace, '.ai/skills/research/SKILL.md'),
+      [
+        '---',
+        'description: 检索项目信息',
+        '---',
+        '先读 README.md'
+      ].join('\n')
+    )
+    await writeDocument(
+      join(workspace, '.ai/skills/review/SKILL.md'),
+      [
+        '---',
+        'description: 评审代码改动',
+        '---',
+        '检查回归风险'
+      ].join('\n')
+    )
+    await writeDocument(
+      join(workspace, '.ai/specs/release/index.md'),
+      [
+        '---',
+        'description: 发布流程',
+        'skills:',
+        '  - research',
+        '---',
+        '执行发布'
+      ].join('\n')
+    )
+
+    const bundle = await resolveWorkspaceAssetBundle({
+      cwd: workspace,
+      useDefaultVibeForgeMcpServer: false
+    })
+    const [data, options] = await resolvePromptAssetSelection({
+      bundle,
+      type: 'spec',
+      name: 'release'
+    })
+
+    expect(data.targetSkills.map(skill => skill.resolvedName ?? skill.attributes.name)).toEqual(['research'])
+    expect(options.systemPrompt).toContain('项目已加载如下技能模块')
+    expect(options.systemPrompt).toContain('# research')
+    expect(options.systemPrompt).toContain('> 技能文件路径：.ai/skills/research/SKILL.md')
+    expect(options.systemPrompt).toContain('<skill-content>')
+    expect(options.systemPrompt).toContain('先读 README.md')
+    expect(options.systemPrompt).toContain('# review')
+    expect(options.systemPrompt).toContain('> 技能文件路径：.ai/skills/review/SKILL.md')
+    expect(options.systemPrompt).toContain('> 默认无需预先加载正文；仅在任务明确需要该技能时，再读取对应技能文件。')
+    expect(options.systemPrompt).not.toContain('<skill-content>\n检查回归风险\n</skill-content>')
+  })
+
+  it('keeps skills as route-only guidance in normal mode', async () => {
+    const workspace = await createWorkspace()
+
+    await writeDocument(
+      join(workspace, '.ai/skills/research/SKILL.md'),
+      [
+        '---',
+        'description: 检索项目信息',
+        '---',
+        '先读 README.md'
+      ].join('\n')
+    )
+
+    const bundle = await resolveWorkspaceAssetBundle({
+      cwd: workspace,
+      useDefaultVibeForgeMcpServer: false
+    })
+    const [data, options] = await resolvePromptAssetSelection({
+      bundle,
+      type: undefined
+    })
+
+    expect(data.targetSkills).toEqual([])
+    expect(options.systemPrompt).not.toContain('项目已加载如下技能模块')
+    expect(options.systemPrompt).toContain('<skills>')
+    expect(options.systemPrompt).toContain('# research')
+    expect(options.systemPrompt).toContain('> 技能文件路径：.ai/skills/research/SKILL.md')
+    expect(options.systemPrompt).toContain('> 默认无需预先加载正文；仅在任务明确需要该技能时，再读取对应技能文件。')
+    expect(options.systemPrompt).not.toContain('<skill-content>')
+    expect(options.systemPrompt).not.toContain('先读 README.md')
+  })
+
+  it('keeps spec route guidance without default identity in normal mode', async () => {
+    const workspace = await createWorkspace()
+
+    await writeDocument(
+      join(workspace, '.ai/specs/release/index.md'),
+      [
+        '---',
+        'description: 发布流程',
+        '---',
+        '执行发布'
+      ].join('\n')
+    )
+
+    const bundle = await resolveWorkspaceAssetBundle({
+      cwd: workspace,
+      useDefaultVibeForgeMcpServer: false
+    })
+    const [, options] = await resolvePromptAssetSelection({
+      bundle,
+      type: undefined
+    })
+
+    expect(options.systemPrompt).toContain('项目存在如下工作流程')
+    expect(options.systemPrompt).toContain('流程名称：release')
+    expect(options.systemPrompt).not.toContain('项目推进管理大师')
+  })
+
+  it('injects spec identity guidance when a spec is actively selected', async () => {
+    const workspace = await createWorkspace()
+
+    await writeDocument(
+      join(workspace, '.ai/specs/release/index.md'),
+      [
+        '---',
+        'description: 发布流程',
+        '---',
+        '执行发布'
+      ].join('\n')
+    )
+
+    const bundle = await resolveWorkspaceAssetBundle({
+      cwd: workspace,
+      useDefaultVibeForgeMcpServer: false
+    })
+    const [, options] = await resolvePromptAssetSelection({
+      bundle,
+      type: 'spec',
+      name: 'release'
+    })
+
+    expect(options.systemPrompt).toContain('项目推进管理大师')
+    expect(options.systemPrompt).toContain('永远不要单独完成代码开发工作')
+    expect(options.systemPrompt).toContain('流程名称：release')
+  })
+
+  it('embeds referenced skills for entity mode and removes them from route guidance', async () => {
+    const workspace = await createWorkspace()
+
+    await writeDocument(
+      join(workspace, '.ai/skills/research/SKILL.md'),
+      [
+        '---',
+        'description: 检索项目信息',
+        '---',
+        '先读 README.md'
+      ].join('\n')
+    )
+    await writeDocument(
+      join(workspace, '.ai/skills/review/SKILL.md'),
+      [
+        '---',
+        'description: 评审代码改动',
+        '---',
+        '检查回归风险'
+      ].join('\n')
+    )
+    await writeDocument(
+      join(workspace, '.ai/entities/reviewer/README.md'),
+      [
+        '---',
+        'description: 代码评审实体',
+        'skills:',
+        '  - review',
+        '---',
+        '负责代码评审'
+      ].join('\n')
+    )
+
+    const bundle = await resolveWorkspaceAssetBundle({
+      cwd: workspace,
+      useDefaultVibeForgeMcpServer: false
+    })
+    const [data, options] = await resolvePromptAssetSelection({
+      bundle,
+      type: 'entity',
+      name: 'reviewer'
+    })
+
+    expect(data.targetSkills.map(skill => skill.resolvedName ?? skill.attributes.name)).toEqual(['review'])
+    expect(options.systemPrompt).toContain('项目已加载如下技能模块')
+    expect(options.systemPrompt).toContain('# review')
+    expect(options.systemPrompt).toContain('<skill-content>')
+    expect(options.systemPrompt).toContain('检查回归风险')
+    expect(options.systemPrompt).not.toContain('<skills>\n# review')
+    expect(options.systemPrompt).toContain('<skills>')
+    expect(options.systemPrompt).toContain('# research')
+    expect(options.systemPrompt).toContain('> 技能文件路径：.ai/skills/research/SKILL.md')
+    expect(options.systemPrompt).not.toContain('<skill-content>\n先读 README.md\n</skill-content>')
+  })
+
+  it('does not preload all skills when the target entity omits skill references', async () => {
+    const workspace = await createWorkspace()
+
+    await writeDocument(
+      join(workspace, '.ai/skills/research/SKILL.md'),
+      [
+        '---',
+        'description: 检索项目信息',
+        '---',
+        '先读 README.md'
+      ].join('\n')
+    )
+    await writeDocument(
+      join(workspace, '.ai/entities/reviewer/README.md'),
+      [
+        '---',
+        'description: 代码评审实体',
+        '---',
+        '负责代码评审'
+      ].join('\n')
+    )
+
+    const bundle = await resolveWorkspaceAssetBundle({
+      cwd: workspace,
+      useDefaultVibeForgeMcpServer: false
+    })
+    const [data, options] = await resolvePromptAssetSelection({
+      bundle,
+      type: 'entity',
+      name: 'reviewer'
+    })
+
+    expect(data.targetSkills).toEqual([])
+    expect(options.systemPrompt).not.toContain('项目已加载如下技能模块')
+    expect(options.systemPrompt).toContain('# research')
+    expect(options.systemPrompt).toContain('> 技能文件路径：.ai/skills/research/SKILL.md')
+    expect(options.systemPrompt).not.toContain('先读 README.md')
+  })
+})

package/__tests__/snapshot.ts

@@ -0,0 +1,276 @@
+import process from 'node:process'
+
+import type {
+  AdapterAssetPlan,
+  AssetDiagnostic,
+  Definition,
+  Entity,
+  Filter,
+  PromptAssetResolution,
+  Rule,
+  Skill,
+  Spec,
+  WorkspaceAsset,
+  WorkspaceAssetBundle,
+  WorkspaceAssetKind
+} from '@vibe-forge/types'
+import { resolveDocumentName, resolveSpecIdentifier } from '@vibe-forge/utils'
+
+const sortStrings = (values: string[]) => [...values].sort((left, right) => left.localeCompare(right))
+
+const sanitizeValue = (
+  value: string,
+  cwd: string
+) => (
+  value
+    .replaceAll(`/private${cwd}`, '<workspace>')
+    .replaceAll(cwd, '<workspace>')
+    .replaceAll(`/private${process.execPath}`, '<node-path>')
+    .replaceAll(process.execPath, '<node-path>')
+)
+
+const normalizeValue = (
+  value: unknown,
+  cwd: string
+): unknown => {
+  if (typeof value === 'string') {
+    return sanitizeValue(value, cwd)
+  }
+
+  if (Array.isArray(value)) {
+    return value.map(item => normalizeValue(item, cwd))
+  }
+
+  if (value != null && typeof value === 'object') {
+    return Object.fromEntries(
+      Object.entries(value)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, entry]) => [key, normalizeValue(entry, cwd)])
+    )
+  }
+
+  return value
+}
+
+const sortFilter = (filter: Filter | undefined) => {
+  if (filter == null) return undefined
+  return {
+    include: filter.include == null ? undefined : sortStrings(filter.include),
+    exclude: filter.exclude == null ? undefined : sortStrings(filter.exclude)
+  }
+}
+
+const resolveDefinitionIdentifier = (
+  kind: Extract<WorkspaceAssetKind, 'rule' | 'spec' | 'entity' | 'skill'>,
+  definition: Definition<Rule | Spec | Entity | Skill>
+) => {
+  if (kind === 'spec') {
+    return resolveSpecIdentifier(definition.path, definition.attributes.name)
+  }
+
+  if (kind === 'entity') {
+    return resolveDocumentName(definition.path, definition.attributes.name, ['readme.md', 'index.json'])
+  }
+
+  if (kind === 'skill') {
+    return resolveDocumentName(definition.path, definition.attributes.name, ['skill.md'])
+  }
+
+  return resolveDocumentName(definition.path, definition.attributes.name)
+}
+
+const summarizeDefinition = (
+  kind: Extract<WorkspaceAssetKind, 'rule' | 'spec' | 'entity' | 'skill'>,
+  definition: Definition<Rule | Spec | Entity | Skill>,
+  cwd: string
+) => ({
+  identifier: resolveDefinitionIdentifier(kind, definition),
+  path: sanitizeValue(definition.path, cwd),
+  attributes: normalizeValue(definition.attributes, cwd),
+  body: definition.body.trim()
+})
+
+const buildSnapshotAssetId = (
+  asset: WorkspaceAsset,
+  cwd: string
+) => (
+  `${asset.kind}:${asset.origin}:${asset.instancePath ?? 'workspace'}:${asset.displayName}:${sanitizeValue(asset.sourcePath, cwd)}`
+)
+
+const summarizeBaseAsset = (
+  asset: WorkspaceAsset,
+  cwd: string,
+  assetIdMap?: Map<string, string>
+) => ({
+  id: assetIdMap?.get(asset.id) ?? buildSnapshotAssetId(asset, cwd),
+  kind: asset.kind,
+  name: asset.name,
+  displayName: asset.displayName,
+  origin: asset.origin,
+  scope: asset.scope,
+  sourcePath: sanitizeValue(asset.sourcePath, cwd),
+  instancePath: asset.instancePath,
+  packageId: asset.packageId,
+  resolvedBy: asset.resolvedBy,
+  taskOverlaySource: asset.taskOverlaySource
+})
+
+const summarizeDocumentAsset = (
+  asset: Extract<WorkspaceAsset, { kind: 'rule' | 'spec' | 'entity' | 'skill' }>,
+  cwd: string,
+  assetIdMap?: Map<string, string>
+) => ({
+  ...summarizeBaseAsset(asset, cwd, assetIdMap),
+  definition: summarizeDefinition(asset.kind, asset.payload.definition, cwd)
+})
+
+const summarizeMcpServer = (
+  asset: Extract<WorkspaceAsset, { kind: 'mcpServer' }>,
+  cwd: string,
+  assetIdMap?: Map<string, string>
+) => ({
+  ...summarizeBaseAsset(asset, cwd, assetIdMap),
+  config: normalizeValue(asset.payload.config, cwd)
+})
+
+const summarizeHookPlugin = (
+  asset: Extract<WorkspaceAsset, { kind: 'hookPlugin' }>,
+  cwd: string,
+  assetIdMap?: Map<string, string>
+) => ({
+  ...summarizeBaseAsset(asset, cwd, assetIdMap),
+  packageName: asset.payload.packageName,
+  config: normalizeValue(asset.payload.config, cwd)
+})
+
+const summarizeOpenCodeOverlayAsset = (
+  asset: Extract<WorkspaceAsset, { kind: 'agent' | 'command' | 'mode' | 'nativePlugin' }>,
+  cwd: string,
+  assetIdMap?: Map<string, string>
+) => ({
+  ...summarizeBaseAsset(asset, cwd, assetIdMap),
+  entryName: asset.payload.entryName,
+  targetSubpath: asset.payload.targetSubpath
+})
+
+const summarizeDiagnostics = (
+  diagnostics: AssetDiagnostic[],
+  assetIdMap: Map<string, string>
+) => (
+  [...diagnostics]
+    .sort((left, right) => {
+      const assetIdDiff = left.assetId.localeCompare(right.assetId)
+      if (assetIdDiff !== 0) return assetIdDiff
+      return left.status.localeCompare(right.status)
+    })
+    .map(diagnostic => ({
+      assetId: assetIdMap.get(diagnostic.assetId) ?? diagnostic.assetId,
+      adapter: diagnostic.adapter,
+      status: diagnostic.status,
+      reason: diagnostic.reason,
+      scope: diagnostic.scope,
+      packageId: diagnostic.packageId
+    }))
+)
+
+const summarizePlan = (
+  plan: AdapterAssetPlan,
+  cwd: string,
+  assetIdMap: Map<string, string>
+) => ({
+  adapter: plan.adapter,
+  mcpServers: normalizeValue(plan.mcpServers, cwd),
+  overlays: [...plan.overlays]
+    .sort((left, right) => left.assetId.localeCompare(right.assetId))
+    .map(entry => ({
+      assetId: assetIdMap.get(entry.assetId) ?? entry.assetId,
+      kind: entry.kind,
+      sourcePath: sanitizeValue(entry.sourcePath, cwd),
+      targetPath: entry.targetPath
+    })),
+  diagnostics: summarizeDiagnostics(plan.diagnostics, assetIdMap)
+})
+
+const summarizeSelection = (
+  resolution: PromptAssetResolution,
+  options: {
+    systemPrompt?: string
+    tools?: Filter
+    mcpServers?: Filter
+    promptAssetIds?: string[]
+  },
+  cwd: string,
+  assetIdMap: Map<string, string>
+) => ({
+  resolution: {
+    rules: resolution.rules.map(rule => summarizeDefinition('rule', rule, cwd)),
+    targetSkills: resolution.targetSkills.map(skill => summarizeDefinition('skill', skill, cwd)),
+    entities: resolution.entities.map(entity => summarizeDefinition('entity', entity, cwd)),
+    skills: resolution.skills.map(skill => summarizeDefinition('skill', skill, cwd)),
+    specs: resolution.specs.map(spec => summarizeDefinition('spec', spec, cwd)),
+    targetBody: resolution.targetBody.trim(),
+    promptAssetIds: sortStrings(resolution.promptAssetIds.map(assetId => assetIdMap.get(assetId) ?? assetId))
+  },
+  options: {
+    systemPrompt: options.systemPrompt?.trim(),
+    tools: sortFilter(options.tools),
+    mcpServers: sortFilter(options.mcpServers),
+    promptAssetIds: options.promptAssetIds == null
+      ? undefined
+      : sortStrings(options.promptAssetIds.map(assetId => assetIdMap.get(assetId) ?? assetId))
+  }
+})
+
+export const serializeWorkspaceAssetsSnapshot = (params: {
+  cwd: string
+  bundle: WorkspaceAssetBundle
+  selection: {
+    resolution: PromptAssetResolution
+    options: {
+      systemPrompt?: string
+      tools?: Filter
+      mcpServers?: Filter
+      promptAssetIds?: string[]
+    }
+  }
+  plans: AdapterAssetPlan[]
+}) => {
+  const { bundle, cwd } = params
+  const assetIdMap = new Map(bundle.assets.map(asset => [asset.id, buildSnapshotAssetId(asset, cwd)]))
+
+  const snapshot = {
+    bundle: {
+      cwd: '<workspace>',
+      pluginConfigs: normalizeValue(bundle.pluginConfigs, cwd),
+      pluginInstances: normalizeValue(bundle.pluginInstances, cwd),
+      defaultIncludeMcpServers: sortStrings(bundle.defaultIncludeMcpServers),
+      defaultExcludeMcpServers: sortStrings(bundle.defaultExcludeMcpServers),
+      rules: bundle.rules.map(rule => summarizeDocumentAsset(rule, cwd, assetIdMap)),
+      specs: bundle.specs.map(spec => summarizeDocumentAsset(spec, cwd, assetIdMap)),
+      entities: bundle.entities.map(entity => summarizeDocumentAsset(entity, cwd, assetIdMap)),
+      skills: bundle.skills.map(skill => summarizeDocumentAsset(skill, cwd, assetIdMap)),
+      mcpServers: Object.values(bundle.mcpServers)
+        .sort((left, right) => left.payload.name.localeCompare(right.payload.name))
+        .map(server => summarizeMcpServer(server, cwd, assetIdMap)),
+      hookPlugins: bundle.hookPlugins
+        .sort((left, right) => left.id.localeCompare(right.id))
+        .map(plugin => summarizeHookPlugin(plugin, cwd, assetIdMap)),
+      opencodeOverlayAssets: bundle.opencodeOverlayAssets
+        .sort((left, right) => left.id.localeCompare(right.id))
+        .map(asset => summarizeOpenCodeOverlayAsset(asset, cwd, assetIdMap))
+    },
+    selection: summarizeSelection(
+      params.selection.resolution,
+      params.selection.options,
+      cwd,
+      assetIdMap
+    ),
+    plans: Object.fromEntries(
+      [...params.plans]
+        .sort((left, right) => left.adapter.localeCompare(right.adapter))
+        .map(plan => [plan.adapter, summarizePlan(plan, cwd, assetIdMap)])
+    )
+  }
+
+  return `${JSON.stringify(snapshot, null, 2)}\n`
+}

package/__tests__/test-helpers.ts

@@ -0,0 +1,33 @@
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { dirname, join } from 'node:path'
+
+import { afterEach } from 'vitest'
+
+const tempDirs: string[] = []
+
+export const createWorkspace = async () => {
+  const dir = await mkdtemp(join(tmpdir(), 'workspace-assets-'))
+  tempDirs.push(dir)
+  return dir
+}
+
+export const writeDocument = async (filePath: string, content: string) => {
+  await mkdir(dirname(filePath), { recursive: true })
+  await writeFile(filePath, content)
+}
+
+export const installPluginPackage = async (
+  workspace: string,
+  packageName: string,
+  files: Record<string, string>
+) => {
+  const packageDir = join(workspace, 'node_modules', ...packageName.split('/'))
+  await Promise.all(Object.entries(files).map(async ([relativePath, content]) => {
+    await writeDocument(join(packageDir, relativePath), content)
+  }))
+}
+
+afterEach(async () => {
+  await Promise.all(tempDirs.splice(0).map(dir => rm(dir, { recursive: true, force: true })))
+})