@vibe-forge/workspace-assets 1.0.0 → 2.0.1

package/src/skill-dependencies.ts

@@ -0,0 +1,361 @@
+/* eslint-disable max-lines -- dependency normalization and graph expansion share the same local helpers */
+import { readFile } from 'node:fs/promises'
+
+import fm from 'front-matter'
+
+import { parseScopedReference, resolveSkillIdentifier } from '@vibe-forge/definition-core'
+import type { Config, Definition, Skill, WorkspaceAsset } from '@vibe-forge/types'
+import { resolveRelativePath } from '@vibe-forge/utils'
+
+import { HOME_BRIDGE_RESOLVED_BY } from './home-bridge'
+import { installSkillsCliDependency } from './skills-cli-dependency'
+
+type SkillAsset = Extract<WorkspaceAsset, { kind: 'skill' }>
+
+export interface NormalizedSkillDependency {
+  ref: string
+  name: string
+  source?: string
+}
+
+interface DependencyExpansionParams {
+  allAssets: WorkspaceAsset[]
+  configs: [Config?, Config?]
+  cwd: string
+  excludedIds?: Set<string>
+  selectedAssets: SkillAsset[]
+  skillAssets: SkillAsset[]
+}
+
+const asNonEmptyString = (value: unknown) => (
+  typeof value === 'string' && value.trim() !== '' ? value.trim() : undefined
+)
+
+const toSkillSlug = (value: string) => (
+  value
+    .trim()
+    .toLowerCase()
+    .replace(/[\s_]+/g, '-')
+    .replace(/[^a-z0-9-]/g, '')
+    .replace(/-+/g, '-')
+    .replace(/^-|-$/g, '')
+)
+
+const resolveUniqueSkillByName = (assets: SkillAsset[], name: string) => {
+  const nameSlug = toSkillSlug(name)
+  const matches = assets.filter(asset => asset.name === name || toSkillSlug(asset.name) === nameSlug)
+  if (matches.length === 0) return undefined
+
+  const unscopedMatches = matches.filter(asset => asset.scope == null)
+  if (unscopedMatches.length === 1) return unscopedMatches[0]
+
+  if (matches.length > 1) {
+    throw new Error(
+      `Ambiguous skill dependency ${name}. Candidates: ${matches.map(match => match.displayName).join(', ')}`
+    )
+  }
+
+  return matches[0]
+}
+
+const filterSearchableSkillAssets = (
+  assets: SkillAsset[],
+  options?: {
+    includeHomeBridge?: boolean
+  }
+) => (
+  options?.includeHomeBridge === false
+    ? assets.filter(asset => asset.resolvedBy !== HOME_BRIDGE_RESOLVED_BY)
+    : assets
+)
+
+const removeHomeBridgeSkillDuplicates = (
+  assets: WorkspaceAsset[],
+  displayName: string
+) => {
+  for (let index = assets.length - 1; index >= 0; index--) {
+    const asset = assets[index]
+    if (asset.kind !== 'skill') continue
+    if (asset.resolvedBy !== HOME_BRIDGE_RESOLVED_BY) continue
+    if (asset.displayName !== displayName) continue
+    assets.splice(index, 1)
+  }
+}
+
+const findSkillAssetByRef = (
+  assets: SkillAsset[],
+  ref: string,
+  currentInstancePath?: string,
+  options?: {
+    includeHomeBridge?: boolean
+  }
+) => {
+  const searchableAssets = filterSearchableSkillAssets(assets, options)
+  const scoped = parseScopedReference(ref, { pathSuffixes: ['.md', '.json', '.yaml', '.yml'] })
+  if (scoped != null) {
+    return searchableAssets.find(asset => asset.scope === scoped.scope && asset.name === scoped.name)
+  }
+
+  if (currentInstancePath != null) {
+    const local = searchableAssets.find(asset => asset.instancePath === currentInstancePath && asset.name === ref)
+    if (local != null) return local
+  }
+
+  return resolveUniqueSkillByName(searchableAssets, ref)
+}
+
+const resolveDisplayName = (name: string, scope?: string) => (
+  scope != null && scope.trim() !== '' ? `${scope}/${name}` : name
+)
+
+const parseFrontmatterSkill = async (path: string): Promise<Definition<Skill>> => {
+  const content = await readFile(path, 'utf-8')
+  const { body, attributes } = fm<Skill>(content)
+  return {
+    path,
+    body,
+    attributes
+  }
+}
+
+const createResolvedSkillAsset = (params: {
+  cwd: string
+  definition: Definition<Skill>
+}) => {
+  const name = resolveSkillIdentifier(params.definition.path, params.definition.attributes.name)
+  const displayName = resolveDisplayName(name)
+  return {
+    id: `skill:workspace:workspace:${displayName}:${resolveRelativePath(params.cwd, params.definition.path)}`,
+    kind: 'skill',
+    name,
+    displayName,
+    origin: 'workspace',
+    sourcePath: params.definition.path,
+    payload: {
+      definition: params.definition
+    }
+  } satisfies SkillAsset
+}
+
+const parseStringDependency = (value: string): NormalizedSkillDependency => {
+  const ref = value.trim()
+  const atIndex = ref.lastIndexOf('@')
+  if (atIndex > 0 && atIndex < ref.length - 1) {
+    return {
+      ref,
+      source: ref.slice(0, atIndex),
+      name: ref.slice(atIndex + 1)
+    }
+  }
+
+  const sourcePathSegments = ref.split('/').filter(segment => segment.trim() !== '')
+  if (
+    sourcePathSegments.length >= 3 &&
+    sourcePathSegments.every(segment => !segment.includes(' '))
+  ) {
+    return {
+      ref,
+      source: sourcePathSegments.slice(0, -1).join('/'),
+      name: sourcePathSegments[sourcePathSegments.length - 1]
+    }
+  }
+
+  return {
+    ref,
+    name: ref
+  }
+}
+
+export const normalizeSkillDependency = (value: unknown): NormalizedSkillDependency | undefined => {
+  const stringValue = asNonEmptyString(value)
+  if (stringValue != null) return parseStringDependency(stringValue)
+
+  if (value == null || typeof value !== 'object' || Array.isArray(value)) return undefined
+  const record = value as Record<string, unknown>
+  const name = asNonEmptyString(record.name)
+  if (name == null) return undefined
+
+  const source = asNonEmptyString(record.source)
+  return {
+    ref: source == null ? name : `${source}@${name}`,
+    name,
+    ...(source == null ? {} : { source })
+  }
+}
+
+export const normalizeSkillDependencies = (value: Skill['dependencies'] | undefined) => (
+  Array.isArray(value)
+    ? value
+      .map(normalizeSkillDependency)
+      .filter((dependency): dependency is NormalizedSkillDependency => dependency != null)
+    : []
+)
+
+export const findSkillDependencyAsset = (
+  assets: SkillAsset[],
+  dependency: NormalizedSkillDependency,
+  currentInstancePath?: string,
+  options?: {
+    includeHomeBridge?: boolean
+  }
+) => {
+  const candidateRefs = Array.from(
+    new Set([
+      dependency.ref,
+      dependency.name
+    ])
+  )
+
+  for (const ref of candidateRefs) {
+    const asset = findSkillAssetByRef(assets, ref, currentInstancePath, options)
+    if (asset != null) return asset
+  }
+
+  return undefined
+}
+
+export const expandSkillAssetDependencies = (
+  assets: SkillAsset[],
+  selectedAssets: SkillAsset[],
+  options: {
+    excludedIds?: Set<string>
+  } = {}
+) => {
+  const selected: SkillAsset[] = []
+  const seen = new Set<string>()
+
+  const addAsset = (asset: SkillAsset) => {
+    if (options.excludedIds?.has(asset.id)) return
+    if (seen.has(asset.id)) return
+    seen.add(asset.id)
+    selected.push(asset)
+
+    for (const dependency of normalizeSkillDependencies(asset.payload.definition.attributes.dependencies)) {
+      const dependencyAsset = findSkillDependencyAsset(assets, dependency, asset.instancePath)
+      if (dependencyAsset == null) {
+        throw new Error(`Failed to resolve skill dependency ${dependency.ref} declared by ${asset.displayName}`)
+      }
+      addAsset(dependencyAsset)
+    }
+  }
+
+  selectedAssets.forEach(addAsset)
+  return selected
+}
+
+export const expandSkillAssetDependenciesWithRemoteResolution = async (
+  params: DependencyExpansionParams
+) => {
+  const selected: SkillAsset[] = []
+  const seen = new Set<string>()
+  const fetchedDependencyRefs = new Set<string>()
+
+  const removeSupersededHomeBridgeSkill = (displayName: string) => {
+    removeHomeBridgeSkillDuplicates(params.allAssets, displayName)
+    removeHomeBridgeSkillDuplicates(params.skillAssets, displayName)
+    removeHomeBridgeSkillDuplicates(params.selectedAssets, displayName)
+    removeHomeBridgeSkillDuplicates(selected, displayName)
+  }
+
+  const installDependencyAsset = async (
+    dependency: NormalizedSkillDependency,
+    currentInstancePath?: string
+  ) => {
+    const fetchKey = dependency.ref
+    if (!fetchedDependencyRefs.has(fetchKey)) {
+      fetchedDependencyRefs.add(fetchKey)
+      const installed = await installSkillsCliDependency({
+        cwd: params.cwd,
+        configs: params.configs,
+        dependency
+      })
+      const definition = await parseFrontmatterSkill(installed.skillPath)
+      const dependencyAsset = createResolvedSkillAsset({
+        cwd: params.cwd,
+        definition
+      })
+      const existingAsset = findSkillDependencyAsset(
+        params.skillAssets,
+        dependency,
+        currentInstancePath,
+        { includeHomeBridge: false }
+      ) ??
+        params.skillAssets.find(existing => (
+          existing.resolvedBy !== HOME_BRIDGE_RESOLVED_BY &&
+          existing.displayName === dependencyAsset.displayName
+        ))
+      if (existingAsset != null) {
+        removeSupersededHomeBridgeSkill(existingAsset.displayName)
+        return existingAsset
+      }
+
+      removeSupersededHomeBridgeSkill(dependencyAsset.displayName)
+      params.allAssets.push(dependencyAsset)
+      params.skillAssets.push(dependencyAsset)
+      return dependencyAsset
+    }
+
+    // After the first fetch attempt, reuse whichever asset is now visible in the
+    // skill set: a newly installed registry skill, or a home-bridge fallback
+    // that was accepted by an earlier plain-name dependency resolution.
+    const resolvedAsset = findSkillDependencyAsset(params.skillAssets, dependency, currentInstancePath)
+    if (resolvedAsset != null && resolvedAsset.resolvedBy !== HOME_BRIDGE_RESOLVED_BY) {
+      removeSupersededHomeBridgeSkill(resolvedAsset.displayName)
+    }
+    return resolvedAsset
+  }
+
+  const addAsset = async (asset: SkillAsset): Promise<void> => {
+    if (params.excludedIds?.has(asset.id)) return
+    if (seen.has(asset.id)) return
+    seen.add(asset.id)
+    selected.push(asset)
+
+    for (const dependency of normalizeSkillDependencies(asset.payload.definition.attributes.dependencies)) {
+      const localOrBridgedDependency = findSkillDependencyAsset(
+        params.skillAssets,
+        dependency,
+        asset.instancePath
+      )
+      const directDependency = findSkillDependencyAsset(
+        params.skillAssets,
+        dependency,
+        asset.instancePath,
+        { includeHomeBridge: false }
+      )
+
+      if (directDependency != null) {
+        await addAsset(directDependency)
+        continue
+      }
+
+      // Keep registry-backed dependencies ahead of home-bridge skills. We only
+      // fall back to a bridged home skill for plain-name dependencies when the
+      // registry path is unavailable.
+      const dependencyAsset = await installDependencyAsset(dependency, asset.instancePath).catch((error: unknown) => {
+        if (
+          localOrBridgedDependency != null &&
+          dependency.source == null
+        ) {
+          return localOrBridgedDependency
+        }
+        throw error
+      }) ?? (
+        dependency.source == null
+          ? localOrBridgedDependency
+          : undefined
+      )
+
+      if (dependencyAsset == null) {
+        throw new Error(`Failed to resolve skill dependency ${dependency.ref} declared by ${asset.displayName}`)
+      }
+      await addAsset(dependencyAsset)
+    }
+  }
+
+  for (const asset of params.selectedAssets) {
+    await addAsset(asset)
+  }
+
+  return selected
+}

package/src/skills-cli-dependency.ts

@@ -0,0 +1,208 @@
+import { access, copyFile, lstat, mkdir, readdir, rename, rm } from 'node:fs/promises'
+import { dirname, resolve } from 'node:path'
+import process from 'node:process'
+import { setTimeout as delay } from 'node:timers/promises'
+
+import type { Config, SkillsCliConfig } from '@vibe-forge/types'
+import { resolveSkillsCliRuntimeConfig } from '@vibe-forge/utils'
+import { resolveProjectSharedCachePath } from '@vibe-forge/utils/project-cache-path'
+import {
+  findSkillsCli,
+  installSkillsCliRefToTemp,
+  installSkillsCliSkillToTemp,
+  resolveSkillsCliRegistry,
+  toSkillSlug
+} from '@vibe-forge/utils/skills-cli'
+
+import type { NormalizedSkillDependency } from './skill-dependencies'
+
+const INSTALL_LOCK_TIMEOUT_MS = 30_000
+const INSTALL_LOCK_RETRY_MS = 100
+
+const toCacheSegment = (value: string) => (
+  value
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, '-')
+    .replace(/^-+|-+$/g, '') || 'default'
+)
+
+const pathExists = async (targetPath: string) => {
+  try {
+    await access(targetPath)
+    return true
+  } catch {
+    return false
+  }
+}
+
+const withInstallLock = async <T>(lockDir: string, callback: () => Promise<T>) => {
+  const start = Date.now()
+  await mkdir(dirname(lockDir), { recursive: true })
+
+  while (true) {
+    try {
+      await mkdir(lockDir)
+      break
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error
+      if (Date.now() - start > INSTALL_LOCK_TIMEOUT_MS) {
+        throw new Error(`Timed out waiting for skill dependency install lock ${lockDir}`)
+      }
+      await delay(INSTALL_LOCK_RETRY_MS)
+    }
+  }
+
+  try {
+    return await callback()
+  } finally {
+    await rm(lockDir, { recursive: true, force: true })
+  }
+}
+
+const copyRegularFiles = async (sourceDir: string, targetDir: string) => {
+  let fileCount = 0
+  const entries = await readdir(sourceDir, { withFileTypes: true })
+
+  await mkdir(targetDir, { recursive: true })
+
+  for (const entry of entries) {
+    const sourcePath = resolve(sourceDir, entry.name)
+    const targetPath = resolve(targetDir, entry.name)
+    const stat = await lstat(sourcePath)
+
+    if (stat.isDirectory()) {
+      fileCount += await copyRegularFiles(sourcePath, targetPath)
+      continue
+    }
+
+    if (!stat.isFile()) continue
+
+    await mkdir(dirname(targetPath), { recursive: true })
+    await copyFile(sourcePath, targetPath)
+    fileCount += 1
+  }
+
+  return fileCount
+}
+
+const pickSearchResult = (results: Awaited<ReturnType<typeof findSkillsCli>>, name: string) => {
+  const slug = toSkillSlug(name)
+  return results.find(result => (
+    result.skill === name ||
+    toSkillSlug(result.skill) === slug
+  )) ?? results[0]
+}
+
+const resolveConfiguredSkillsCliConfig = (configs: [Config?, Config?]) => {
+  const [projectConfig, userConfig] = configs
+  const merged = {
+    ...(resolveSkillsCliRuntimeConfig(projectConfig) ?? {}),
+    ...(resolveSkillsCliRuntimeConfig(userConfig) ?? {})
+  } satisfies SkillsCliConfig
+
+  return Object.keys(merged).length === 0 ? undefined : merged
+}
+
+const buildInstallDir = (params: {
+  config?: SkillsCliConfig
+  cwd: string
+  skill: string
+  source: string
+}) => {
+  const registry = resolveSkillsCliRegistry({
+    config: params.config
+  }) ?? 'default'
+  return resolveProjectSharedCachePath(
+    params.cwd,
+    process.env,
+    'skill-dependencies',
+    'skills-cli',
+    toCacheSegment(params.config?.package ?? 'skills'),
+    toCacheSegment(params.config?.version ?? 'latest'),
+    toCacheSegment(registry),
+    ...params.source.split('/').map(toCacheSegment),
+    toCacheSegment(params.skill)
+  )
+}
+
+export const installSkillsCliDependency = async (params: {
+  cwd: string
+  configs: [Config?, Config?]
+  dependency: NormalizedSkillDependency
+}) => {
+  const config = resolveConfiguredSkillsCliConfig(params.configs)
+  const resolvedTarget = params.dependency.source != null
+    ? {
+      skill: params.dependency.name,
+      source: params.dependency.source
+    }
+    : await (async () => {
+      const searchResults = await findSkillsCli({
+        config,
+        query: params.dependency.name
+      })
+      const selected = pickSearchResult(searchResults, params.dependency.name)
+      if (selected == null) {
+        throw new Error(`Skill ${params.dependency.name} was not found by the skills CLI search.`)
+      }
+
+      return {
+        installRef: selected.installRef,
+        skill: selected.skill,
+        source: selected.source
+      }
+    })()
+
+  const installDir = buildInstallDir({
+    config,
+    cwd: params.cwd,
+    skill: resolvedTarget.skill,
+    source: resolvedTarget.source
+  })
+  const skillPath = resolve(installDir, 'SKILL.md')
+
+  return await withInstallLock(`${installDir}.lock`, async () => {
+    if (await pathExists(skillPath)) {
+      return {
+        installDir,
+        skillPath
+      }
+    }
+
+    const tempInstallDir = `${installDir}.tmp-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}`
+    await rm(tempInstallDir, { recursive: true, force: true })
+    await mkdir(tempInstallDir, { recursive: true })
+
+    const installResult = 'installRef' in resolvedTarget
+      ? await installSkillsCliRefToTemp({
+        config,
+        installRef: resolvedTarget.installRef
+      })
+      : await installSkillsCliSkillToTemp({
+        config,
+        skill: resolvedTarget.skill,
+        source: resolvedTarget.source
+      })
+
+    try {
+      await copyRegularFiles(installResult.installedSkill.sourcePath, tempInstallDir)
+      if (!await pathExists(resolve(tempInstallDir, 'SKILL.md'))) {
+        throw new Error(`Skill dependency ${params.dependency.ref} did not include SKILL.md`)
+      }
+
+      await rm(installDir, { recursive: true, force: true })
+      await rename(tempInstallDir, installDir)
+    } catch (error) {
+      await rm(tempInstallDir, { recursive: true, force: true })
+      throw error
+    } finally {
+      await rm(installResult.tempDir, { recursive: true, force: true })
+    }
+
+    return {
+      installDir,
+      skillPath
+    }
+  })
+}

package/src/workspace-config.ts

@@ -0,0 +1,132 @@
+import { stat } from 'node:fs/promises'
+
+import type { Config, WorkspaceConfigEntry } from '@vibe-forge/types'
+import { glob } from 'fast-glob'
+
+const DEFAULT_WORKSPACE_IGNORES = [
+  '**/.git/**',
+  '**/.ai/**',
+  '**/node_modules/**'
+]
+
+export interface NormalizedWorkspaceEntry {
+  enabled?: boolean
+  name?: string
+  description?: string
+  path?: string
+  include?: string[]
+  exclude?: string[]
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> => (
+  value != null && typeof value === 'object' && !Array.isArray(value)
+)
+
+const toStringList = (value: unknown): string[] => {
+  if (typeof value === 'string' && value.trim() !== '') {
+    return [value.trim()]
+  }
+  if (!Array.isArray(value)) return []
+
+  return value
+    .filter((item): item is string => typeof item === 'string' && item.trim() !== '')
+    .map(item => item.trim())
+}
+
+const normalizeWorkspaceEntry = (
+  id: string,
+  value: string | WorkspaceConfigEntry
+): NormalizedWorkspaceEntry | undefined => {
+  if (typeof value === 'string') {
+    return { path: value }
+  }
+
+  if (!isRecord(value)) return undefined
+  const enabled = typeof value.enabled === 'boolean' ? value.enabled : undefined
+  if (enabled === false) return { enabled: false }
+
+  return {
+    enabled,
+    name: typeof value.name === 'string' && value.name.trim() !== '' ? value.name.trim() : id,
+    description: typeof value.description === 'string' && value.description.trim() !== ''
+      ? value.description.trim()
+      : undefined,
+    path: typeof value.path === 'string' && value.path.trim() !== '' ? value.path.trim() : undefined,
+    include: [
+      ...toStringList(value.include),
+      ...toStringList(value.glob),
+      ...toStringList(value.globs)
+    ],
+    exclude: toStringList(value.exclude)
+  }
+}
+
+export const normalizeWorkspaceConfig = (config: Config['workspaces'] | undefined) => {
+  if (config == null) {
+    return {
+      include: [] as string[],
+      exclude: [] as string[],
+      entries: {} as Record<string, NormalizedWorkspaceEntry>
+    }
+  }
+
+  if (typeof config === 'string' || Array.isArray(config)) {
+    return {
+      include: toStringList(config),
+      exclude: [] as string[],
+      entries: {} as Record<string, NormalizedWorkspaceEntry>
+    }
+  }
+
+  if (!isRecord(config)) {
+    return {
+      include: [] as string[],
+      exclude: [] as string[],
+      entries: {} as Record<string, NormalizedWorkspaceEntry>
+    }
+  }
+
+  const entries = Object.fromEntries(
+    Object.entries(config.entries ?? {})
+      .map(([id, value]) => [id, normalizeWorkspaceEntry(id, value)])
+      .filter((entry): entry is [string, NormalizedWorkspaceEntry] => entry[1] != null)
+  )
+
+  return {
+    include: [
+      ...toStringList(config.include),
+      ...toStringList(config.glob),
+      ...toStringList(config.globs)
+    ],
+    exclude: toStringList(config.exclude),
+    entries
+  }
+}
+
+export const isDirectory = async (path: string) => {
+  try {
+    return (await stat(path)).isDirectory()
+  } catch {
+    return false
+  }
+}
+
+export const scanWorkspacePatterns = async (
+  cwd: string,
+  patterns: string[],
+  exclude: string[]
+) => {
+  if (patterns.length === 0) return []
+
+  return await glob(patterns, {
+    cwd,
+    absolute: true,
+    onlyDirectories: true,
+    unique: true,
+    followSymbolicLinks: true,
+    ignore: [
+      ...DEFAULT_WORKSPACE_IGNORES,
+      ...exclude
+    ]
+  })
+}