@vibe-forge/workspace-assets 1.0.0 → 2.0.1

package/src/configured-skills.ts

@@ -0,0 +1,99 @@
+import { access } from 'node:fs/promises'
+import process from 'node:process'
+
+import type { Config, ConfiguredSkillInstallConfig, SkillsCliConfig } from '@vibe-forge/types'
+import {
+  installProjectSkill,
+  normalizeProjectSkillInstall,
+  resolveConfiguredSkillInstalls as resolveDeclaredConfiguredSkillInstalls,
+  resolveProjectAiPath,
+  resolveSkillsCliRuntimeConfig
+} from '@vibe-forge/utils'
+import type { NormalizedProjectSkillInstall } from '@vibe-forge/utils'
+
+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 resolveConfiguredSkillInstalls = (configs: [Config?, Config?]) => (
+  [
+    ...resolveDeclaredConfiguredSkillInstalls(configs[0]?.skills),
+    ...resolveDeclaredConfiguredSkillInstalls(configs[1]?.skills)
+  ]
+    .map((item) => normalizeProjectSkillInstall(item as string | ConfiguredSkillInstallConfig))
+    .filter((item): item is NormalizedProjectSkillInstall => item != null)
+)
+
+const pathExists = async (targetPath: string) => {
+  try {
+    await access(targetPath)
+    return true
+  } catch {
+    return false
+  }
+}
+
+const ensureUniqueTargets = (skills: NormalizedProjectSkillInstall[]) => {
+  const seen = new Map<string, string>()
+
+  for (const skill of skills) {
+    const previous = seen.get(skill.targetDirName)
+    if (previous != null) {
+      throw new Error(
+        `Configured skills "${previous}" and "${skill.ref}" resolve to the same target "${skill.targetDirName}"`
+      )
+    }
+    seen.set(skill.targetDirName, skill.ref)
+  }
+}
+
+export const ensureConfiguredProjectSkills = async (params: {
+  configs: [Config?, Config?]
+  updateInstalledSkills?: boolean
+  workspaceFolder: string
+}) => {
+  const installs = resolveConfiguredSkillInstalls(params.configs)
+  if (installs.length === 0) {
+    return []
+  }
+
+  ensureUniqueTargets(installs)
+
+  const skillsCliConfig = resolveConfiguredSkillsCliConfig(params.configs)
+  const ensured: Array<{ dirName: string; skillPath: string }> = []
+
+  for (const skill of installs) {
+    const skillPath = resolveProjectAiPath(
+      params.workspaceFolder,
+      process.env,
+      'skills',
+      skill.targetDirName,
+      'SKILL.md'
+    )
+    if (params.updateInstalledSkills !== true && await pathExists(skillPath)) {
+      ensured.push({
+        dirName: skill.targetDirName,
+        skillPath
+      })
+      continue
+    }
+
+    ensured.push(
+      await installProjectSkill({
+        config: skillsCliConfig,
+        force: true,
+        registry: undefined,
+        skill,
+        workspaceFolder: params.workspaceFolder
+      })
+    )
+  }
+
+  return ensured
+}

package/src/home-bridge.ts

@@ -0,0 +1 @@
+export const HOME_BRIDGE_RESOLVED_BY = 'home-bridge'

package/src/index.ts

@@ -1,3 +1,6 @@
 export { buildAdapterAssetPlan } from './adapter-asset-plan'
+export { resolveWorkspaceAssetSource } from './asset-source'
 export { resolveWorkspaceAssetBundle } from './bundle'
+export { HOME_BRIDGE_RESOLVED_BY } from './home-bridge'
 export { resolvePromptAssetSelection } from './prompt-selection'
+export { findWorkspaceAsset, resolveConfiguredWorkspaceAssets } from './workspaces'

package/src/prompt-selection.ts

@@ -1,10 +1,13 @@
+/* eslint-disable max-lines -- prompt asset selection coordinates routing, overlays, and dependency expansion */
 import type {
   Definition,
+  Entity,
   Filter,
   PluginOverlayConfig,
   Rule,
   RuleReference,
   SkillSelection,
+  Spec,
   WorkspaceAsset,
   WorkspaceAssetBundle,
   WorkspaceMcpSelection,
@@ -23,14 +26,17 @@ import {
 import {
   definitionWithResolvedName,
   pickDocumentAsset,
+  resolveEntityInheritance,
   resolveExcludedSkillRefs,
   resolveIncludedSkillRefs,
   resolveNamedAssets,
   resolvePluginOverlay,
   resolveRuleSelection,
-  resolveSelectedSkillAssets,
+  resolveSelectedSkillAssetsWithDependencies,
   toDocumentDefinitions
 } from './selection-internal'
+import { expandSkillAssetDependenciesWithRemoteResolution } from './skill-dependencies'
+import { generateWorkspaceRoutePrompt } from './workspace-prompt'
 
 export async function resolvePromptAssetSelection(params: {
   bundle: WorkspaceAssetBundle
@@ -57,6 +63,8 @@ export async function resolvePromptAssetSelection(params: {
   let targetToolsFilter: Filter | undefined
   let targetMcpServersFilter: Filter | undefined
   let targetInstancePath: string | undefined
+  let targetAssetIds: string[] = []
+  let targetDefinition: Definition<Entity | Spec> | undefined
 
   if (params.type && params.name) {
     const baseTarget = params.type === 'spec'
@@ -77,18 +85,30 @@ export async function resolvePromptAssetSelection(params: {
     }
 
     pinnedTargetAsset = baseTarget
-    targetBody = baseTarget.payload.definition.body
-    targetToolsFilter = baseTarget.payload.definition.attributes.tools
-    targetMcpServersFilter = baseTarget.payload.definition.attributes.mcpServers
+    if (params.type === 'entity') {
+      const resolvedEntity = resolveEntityInheritance(
+        effectiveBundle,
+        baseTarget as Extract<WorkspaceAsset, { kind: 'entity' }>
+      )
+      targetDefinition = resolvedEntity.definition
+      targetAssetIds = resolvedEntity.assetIds
+    } else {
+      targetDefinition = baseTarget.payload.definition
+      targetAssetIds = [baseTarget.id]
+    }
+    targetBody = targetDefinition.body
+    targetToolsFilter = targetDefinition.attributes.tools
+    targetMcpServersFilter = targetDefinition.attributes.mcpServers
     targetInstancePath = baseTarget.instancePath
     options.assetBundle = effectiveBundle
   }
 
-  const selectedSkillAssets = resolveSelectedSkillAssets(effectiveBundle.skills, params.input?.skills)
+  const selectedSkillAssets = await resolveSelectedSkillAssetsWithDependencies(effectiveBundle, params.input?.skills)
   const useNativeProjectSkills = supportsNativeProjectSkills(params.adapter)
   const promptAssetIds = new Set<string>([
     ...effectiveBundle.rules.map(asset => asset.id),
     ...effectiveBundle.specs.map(asset => asset.id),
+    ...effectiveBundle.workspaces.map(asset => asset.id),
     ...(useNativeProjectSkills ? [] : selectedSkillAssets.map(asset => asset.id)),
     ...(params.type !== 'entity' ? effectiveBundle.entities.map(asset => asset.id) : [])
   ])
@@ -101,8 +121,8 @@ export async function resolvePromptAssetSelection(params: {
   const targetSkillsAssets: Array<Extract<WorkspaceAsset, { kind: 'skill' }>> = []
 
   if (pinnedTargetAsset != null) {
-    promptAssetIds.add(pinnedTargetAsset.id)
-    const attributes = pinnedTargetAsset.payload.definition.attributes
+    targetAssetIds.forEach(assetId => promptAssetIds.add(assetId))
+    const attributes = targetDefinition?.attributes ?? pinnedTargetAsset.payload.definition.attributes
 
     if (attributes.rules != null) {
       const selection = await resolveRuleSelection(
@@ -144,12 +164,18 @@ export async function resolvePromptAssetSelection(params: {
       resolveNamedAssets(effectiveBundle.skills, excludedRefs, targetInstancePath).map(asset => asset.id)
     )
 
-    includedAssets
-      .filter(asset => !excludedIds.has(asset.id))
-      .forEach((asset) => {
-        targetSkillsAssets.push(asset)
-        promptAssetIds.add(asset.id)
-      })
+    const expandedTargetSkills = await expandSkillAssetDependenciesWithRemoteResolution({
+      allAssets: effectiveBundle.assets,
+      configs: effectiveBundle.configs ?? [undefined, undefined],
+      cwd: effectiveBundle.cwd,
+      excludedIds,
+      selectedAssets: includedAssets,
+      skillAssets: effectiveBundle.skills
+    })
+    expandedTargetSkills.forEach((asset) => {
+      targetSkillsAssets.push(asset)
+      promptAssetIds.add(asset.id)
+    })
   }
 
   const rules = Array.from(ruleDefinitions.values())
@@ -162,11 +188,13 @@ export async function resolvePromptAssetSelection(params: {
     : []
   const skills = toDocumentDefinitions(selectedSkillAssets)
   const specs = toDocumentDefinitions(effectiveBundle.specs)
+  const workspaces = effectiveBundle.workspaces.map(asset => asset.payload)
 
   options.systemPrompt = [
     generateRulesPrompt(effectiveBundle.cwd, rules),
     generateSkillsPrompt(effectiveBundle.cwd, targetSkills),
     generateEntitiesRoutePrompt(entities),
+    generateWorkspaceRoutePrompt(effectiveBundle.cwd, workspaces),
     useNativeProjectSkills ? '' : generateSkillsRoutePrompt(effectiveBundle.cwd, routedSkills),
     generateSpecRoutePrompt(specs, { active: params.type === 'spec' }),
     targetBody
@@ -174,12 +202,8 @@ export async function resolvePromptAssetSelection(params: {
     .filter(section => section !== '')
     .join('\n\n')
 
-  if (targetToolsFilter != null) {
-    options.tools = targetToolsFilter
-  }
-  if (targetMcpServersFilter != null) {
-    options.mcpServers = targetMcpServersFilter
-  }
+  if (targetToolsFilter != null) options.tools = targetToolsFilter
+  if (targetMcpServersFilter != null) options.mcpServers = targetMcpServersFilter
   options.promptAssetIds = Array.from(promptAssetIds)
 
   return [
@@ -189,6 +213,7 @@ export async function resolvePromptAssetSelection(params: {
       entities,
       skills,
       specs,
+      workspaces,
       targetBody,
       promptAssetIds: Array.from(promptAssetIds)
     },

package/src/selection-internal.ts

@@ -1,5 +1,9 @@
 import type {
   Definition,
+  Entity,
+  EntityInheritance,
+  EntityInheritanceMode,
+  Filter,
   PluginConfig,
   PluginOverlayConfig,
   Rule,
@@ -22,6 +26,7 @@ import {
   isRemoteRuleReference,
   parseScopedReference
 } from '@vibe-forge/definition-core'
+import { expandSkillAssetDependencies, expandSkillAssetDependenciesWithRemoteResolution } from './skill-dependencies'
 
 type DocumentAssetKind = Extract<WorkspaceAssetKind, 'rule' | 'spec' | 'entity' | 'skill'>
 type DocumentAsset<TDefinition> = Extract<WorkspaceAsset, { kind: DocumentAssetKind }> & {
@@ -29,8 +34,28 @@ type DocumentAsset<TDefinition> = Extract<WorkspaceAsset, { kind: DocumentAssetK
     definition: TDefinition & { path: string }
   }
 }
+type EntityAsset = Extract<WorkspaceAsset, { kind: 'entity' }>
+type EntityInheritanceField = Exclude<keyof EntityInheritance, 'default'>
 
 const ASSET_REFERENCE_PATH_SUFFIXES = ['.md', '.json', '.yaml', '.yml']
+const ENTITY_INHERITANCE_FIELDS = ['prompt', 'tags', 'rules', 'skills', 'tools', 'mcpServers'] as const
+const ENTITY_INHERITANCE_MODES = new Set<EntityInheritanceMode>(['append', 'prepend', 'merge', 'replace', 'none'])
+const DEFAULT_CHILD_ENTITY_INHERITANCE: Record<EntityInheritanceField, EntityInheritanceMode> = {
+  prompt: 'append',
+  tags: 'merge',
+  rules: 'merge',
+  skills: 'merge',
+  tools: 'replace',
+  mcpServers: 'replace'
+}
+const PARENT_ENTITY_INHERITANCE: Record<EntityInheritanceField, EntityInheritanceMode> = {
+  prompt: 'append',
+  tags: 'merge',
+  rules: 'merge',
+  skills: 'merge',
+  tools: 'replace',
+  mcpServers: 'replace'
+}
 
 export const definitionWithResolvedName = <TDefinition>(
   definition: Definition<TDefinition>,
@@ -122,6 +147,293 @@ export const resolveNamedAssets = <TAsset extends Extract<WorkspaceAsset, { kind
   return selected
 }
 
+const normalizeEntityExtends = (value: Entity['extends']) => {
+  if (typeof value === 'string') return value.trim() !== '' ? [value.trim()] : []
+  if (!Array.isArray(value)) return []
+
+  return value
+    .map(ref => ref.trim())
+    .filter(Boolean)
+}
+
+const parseEntityInheritanceMode = (
+  value: unknown,
+  label: string
+): EntityInheritanceMode | undefined => {
+  if (value == null) return undefined
+  if (typeof value !== 'string' || !ENTITY_INHERITANCE_MODES.has(value as EntityInheritanceMode)) {
+    throw new Error(`Invalid entity inherit mode for ${label}: ${String(value)}`)
+  }
+  return value as EntityInheritanceMode
+}
+
+const resolveEntityInheritanceModes = (
+  value: Entity['inherit'],
+  defaults: Record<EntityInheritanceField, EntityInheritanceMode>
+) => {
+  const modes = { ...defaults }
+  if (value == null) return modes
+
+  if (typeof value === 'string') {
+    const defaultMode = parseEntityInheritanceMode(value, 'inherit')
+    for (const field of ENTITY_INHERITANCE_FIELDS) {
+      modes[field] = defaultMode ?? modes[field]
+    }
+    return modes
+  }
+
+  const defaultMode = parseEntityInheritanceMode(value.default, 'inherit.default')
+  for (const field of ENTITY_INHERITANCE_FIELDS) {
+    modes[field] = parseEntityInheritanceMode(value[field], `inherit.${field}`) ?? defaultMode ?? modes[field]
+  }
+  return modes
+}
+
+const toUniqueStrings = (values: string[]) => Array.from(new Set(values))
+
+const toUniqueValues = <TValue>(values: TValue[], keyOf: (value: TValue) => string) => {
+  const seen = new Set<string>()
+  const result: TValue[] = []
+
+  for (const value of values) {
+    const key = keyOf(value)
+    if (seen.has(key)) continue
+    seen.add(key)
+    result.push(value)
+  }
+
+  return result
+}
+
+const keyRuleReference = (rule: RuleReference) => (
+  typeof rule === 'string' ? `string:${rule}` : `object:${JSON.stringify(rule)}`
+)
+
+const qualifyEntityReference = (
+  asset: EntityAsset,
+  ref: string
+) => {
+  const value = ref.trim()
+  if (value === '' || asset.scope == null) return value
+  if (parseScopedReference(value, { pathSuffixes: ASSET_REFERENCE_PATH_SUFFIXES }) != null) return value
+  if (
+    isPathLikeReference(value, {
+      pathSuffixes: ASSET_REFERENCE_PATH_SUFFIXES,
+      allowGlob: true
+    })
+  ) {
+    return value
+  }
+
+  return `${asset.scope}/${value}`
+}
+
+const qualifyEntityRuleReferences = (
+  asset: EntityAsset,
+  rules: Entity['rules']
+) => rules?.map(rule => typeof rule === 'string' ? qualifyEntityReference(asset, rule) : rule)
+
+const qualifyEntitySkillSelection = (
+  asset: EntityAsset,
+  selection: Entity['skills']
+): Entity['skills'] => {
+  if (selection == null) return undefined
+  if (Array.isArray(selection)) return selection.map(ref => qualifyEntityReference(asset, ref))
+
+  return {
+    ...selection,
+    list: selection.list.map(ref => qualifyEntityReference(asset, ref))
+  }
+}
+
+const qualifyEntityInternalReferences = (
+  asset: EntityAsset,
+  definition: Definition<Entity>
+): Definition<Entity> => ({
+  ...definition,
+  attributes: {
+    ...definition.attributes,
+    rules: qualifyEntityRuleReferences(asset, definition.attributes.rules),
+    skills: qualifyEntitySkillSelection(asset, definition.attributes.skills)
+  }
+})
+
+const selectInheritedValue = <TValue>(
+  parent: TValue | undefined,
+  child: TValue | undefined,
+  mode: EntityInheritanceMode,
+  merge: (left: TValue, right: TValue) => TValue
+) => {
+  if (mode === 'none') return child
+  if (mode === 'replace') return child ?? parent
+  if (parent == null) return child
+  if (child == null) return parent
+  return mode === 'prepend' ? merge(child, parent) : merge(parent, child)
+}
+
+const mergeEntityBody = (
+  parent: string,
+  child: string,
+  mode: EntityInheritanceMode
+) => {
+  if (mode === 'none' || mode === 'replace') return child
+
+  const values = mode === 'prepend' ? [child, parent] : [parent, child]
+  return values
+    .map(value => value.trim())
+    .filter(Boolean)
+    .join('\n\n')
+}
+
+const getSkillIncludeRefs = (selection: Entity['skills']) => {
+  if (Array.isArray(selection)) return selection
+  return selection?.type === 'include' ? selection.list : undefined
+}
+
+const mergeSkillSelections = (
+  parent: Entity['skills'],
+  child: Entity['skills']
+): Entity['skills'] => {
+  const parentRefs = getSkillIncludeRefs(parent)
+  const childRefs = getSkillIncludeRefs(child)
+  if (parentRefs != null && childRefs != null) return toUniqueStrings([...parentRefs, ...childRefs])
+
+  return child ?? parent
+}
+
+const mergeFilters = (
+  parent: Filter,
+  child: Filter
+): Filter => {
+  const include = toUniqueStrings([
+    ...(parent.include ?? []),
+    ...(child.include ?? [])
+  ])
+  const exclude = toUniqueStrings([
+    ...(parent.exclude ?? []),
+    ...(child.exclude ?? [])
+  ])
+
+  return {
+    ...(include.length > 0 ? { include } : {}),
+    ...(exclude.length > 0 ? { exclude } : {})
+  }
+}
+
+const mergeEntityDefinitions = (
+  parent: Definition<Entity>,
+  child: Definition<Entity>,
+  modes: Record<EntityInheritanceField, EntityInheritanceMode>
+): Definition<Entity> => ({
+  ...child,
+  body: mergeEntityBody(parent.body, child.body, modes.prompt),
+  attributes: {
+    ...parent.attributes,
+    ...child.attributes,
+    name: child.attributes.name,
+    description: child.attributes.description ?? parent.attributes.description,
+    always: child.attributes.always ?? parent.attributes.always,
+    tags: selectInheritedValue(
+      parent.attributes.tags,
+      child.attributes.tags,
+      modes.tags,
+      (left, right) => toUniqueStrings([...left, ...right])
+    ),
+    rules: selectInheritedValue(
+      parent.attributes.rules,
+      child.attributes.rules,
+      modes.rules,
+      (left, right) => toUniqueValues([...left, ...right], keyRuleReference)
+    ),
+    skills: selectInheritedValue(parent.attributes.skills, child.attributes.skills, modes.skills, mergeSkillSelections),
+    tools: selectInheritedValue(parent.attributes.tools, child.attributes.tools, modes.tools, mergeFilters),
+    mcpServers: selectInheritedValue(
+      parent.attributes.mcpServers,
+      child.attributes.mcpServers,
+      modes.mcpServers,
+      mergeFilters
+    ),
+    plugins: child.attributes.plugins
+  }
+})
+
+const uniqueAssetIds = (values: string[]) => toUniqueValues(values, value => value)
+
+const formatEntityCycle = (stack: EntityAsset[], asset: EntityAsset) => (
+  [...stack.slice(stack.findIndex(item => item.id === asset.id)), asset]
+    .map(item => item.displayName)
+    .join(' -> ')
+)
+
+const createAvailableEntitiesMessage = (entities: EntityAsset[]) => (
+  entities
+    .map(asset => asset.displayName)
+    .sort((left, right) => left.localeCompare(right))
+    .join(', ')
+)
+
+export const resolveEntityInheritance = (
+  bundle: WorkspaceAssetBundle,
+  asset: EntityAsset
+): {
+  assetIds: string[]
+  definition: Definition<Entity>
+} => {
+  const resolveAsset = (
+    current: EntityAsset,
+    stack: EntityAsset[]
+  ): {
+    assetIds: string[]
+    definition: Definition<Entity>
+  } => {
+    if (stack.some(item => item.id === current.id)) {
+      throw new Error(`Circular entity inheritance detected: ${formatEntityCycle(stack, current)}`)
+    }
+
+    const currentDefinition = definitionWithResolvedName(
+      current.payload.definition,
+      current.displayName,
+      current.instancePath
+    )
+    const qualifiedCurrentDefinition = qualifyEntityInternalReferences(current, currentDefinition)
+    const parentRefs = normalizeEntityExtends(qualifiedCurrentDefinition.attributes.extends)
+    if (parentRefs.length === 0) {
+      return {
+        assetIds: [current.id],
+        definition: qualifiedCurrentDefinition
+      }
+    }
+
+    let inheritedBase: Definition<Entity> | undefined
+    const inheritedAssetIds: string[] = []
+    for (const ref of parentRefs) {
+      const parentAsset = findNamedAsset(bundle.entities, ref, current.instancePath)
+      if (parentAsset == null) {
+        throw new Error(
+          `Failed to resolve entity ${ref}. Available entities: ${createAvailableEntitiesMessage(bundle.entities)}`
+        )
+      }
+
+      const parent = resolveAsset(parentAsset, [...stack, current])
+      inheritedAssetIds.push(...parent.assetIds)
+      inheritedBase = inheritedBase == null
+        ? parent.definition
+        : mergeEntityDefinitions(inheritedBase, parent.definition, PARENT_ENTITY_INHERITANCE)
+    }
+
+    return {
+      assetIds: uniqueAssetIds([...inheritedAssetIds, current.id]),
+      definition: mergeEntityDefinitions(
+        inheritedBase ?? qualifiedCurrentDefinition,
+        qualifiedCurrentDefinition,
+        resolveEntityInheritanceModes(qualifiedCurrentDefinition.attributes.inherit, DEFAULT_CHILD_ENTITY_INHERITANCE)
+      )
+    }
+  }
+
+  return resolveAsset(asset, [])
+}
+
 const resolvePathMatchedRules = async (
   bundle: WorkspaceAssetBundle,
   ref: string
@@ -211,7 +523,29 @@ export const resolveSelectedSkillAssets = (
   const excluded = new Set(
     resolveNamedAssets(assets, selection.exclude).map(asset => asset.id)
   )
-  return included.filter(asset => !excluded.has(asset.id))
+  return expandSkillAssetDependencies(assets, included, {
+    excludedIds: excluded
+  })
+}
+
+export const resolveSelectedSkillAssetsWithDependencies = async (
+  bundle: WorkspaceAssetBundle,
+  selection?: WorkspaceSkillSelection
+): Promise<Array<Extract<WorkspaceAsset, { kind: 'skill' }>>> => {
+  const included = selection?.include != null && selection.include.length > 0
+    ? resolveNamedAssets(bundle.skills, selection.include)
+    : bundle.skills
+  const excluded = new Set(
+    resolveNamedAssets(bundle.skills, selection?.exclude).map(asset => asset.id)
+  )
+  return await expandSkillAssetDependenciesWithRemoteResolution({
+    allAssets: bundle.assets,
+    configs: bundle.configs ?? [undefined, undefined],
+    cwd: bundle.cwd,
+    excludedIds: excluded,
+    selectedAssets: included,
+    skillAssets: bundle.skills
+  })
 }
 
 export const resolveSelectedMcpNames = (