@vibe-forge/workspace-assets 2.0.1 → 2.0.3

package/src/skill-registry.ts

@@ -0,0 +1,345 @@
+/* eslint-disable max-lines -- registry install logic keeps URL resolution, locking, and cache writes together */
+import { access, mkdir, rename, rm, writeFile } from 'node:fs/promises'
+import { dirname, isAbsolute, relative, resolve, sep } from 'node:path'
+import process from 'node:process'
+import { setTimeout as delay } from 'node:timers/promises'
+
+import type { Config } from '@vibe-forge/types'
+import { resolveProjectSharedCachePath } from '@vibe-forge/utils/project-cache-path'
+
+import type { NormalizedSkillDependency } from './skill-dependencies'
+
+interface RegistryOptions {
+  enabled: boolean
+  searchBaseUrl: string
+  downloadBaseUrl: string
+}
+
+interface RegistrySearchSkill {
+  id?: string
+  name?: string
+  skillId?: string
+  source?: string
+}
+
+interface RegistryDownloadFile {
+  path?: string
+  contents?: string
+}
+
+interface RegistryDownloadResponse {
+  files?: RegistryDownloadFile[]
+}
+
+const DEFAULT_SKILL_REGISTRY_URL = 'https://skills.sh'
+const FETCH_TIMEOUT_MS = 10_000
+const INSTALL_LOCK_TIMEOUT_MS = 30_000
+const INSTALL_LOCK_RETRY_MS = 100
+
+const asNonEmptyString = (value: unknown) => (
+  typeof value === 'string' && value.trim() !== '' ? value.trim() : undefined
+)
+
+const normalizeBaseUrl = (value: string) => value.replace(/\/+$/, '')
+
+const toSkillSlug = (value: string) => (
+  value
+    .trim()
+    .toLowerCase()
+    .replace(/[\s_]+/g, '-')
+    .replace(/[^a-z0-9-]/g, '')
+    .replace(/-+/g, '-')
+    .replace(/^-|-$/g, '')
+)
+
+const toCacheSegment = (value: string) => (
+  value
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, '-')
+    .replace(/^-+|-+$/g, '') || 'registry'
+)
+
+const appendVersionQuery = (url: string, version?: string) => {
+  if (version == null || version.trim() === '') return url
+  const parsed = new URL(url)
+  parsed.searchParams.set('version', version.trim())
+  return parsed.toString()
+}
+
+const resolveConfiguredRegistry = (
+  projectConfig: Config | undefined,
+  userConfig: Config | undefined
+) => userConfig?.skills?.registry ?? projectConfig?.skills?.registry
+
+const resolveRegistryOptions = (params: {
+  configs: [Config?, Config?]
+  registry?: string
+}): RegistryOptions => {
+  const [projectConfig, userConfig] = params.configs
+  const configuredRegistry = params.registry ?? resolveConfiguredRegistry(projectConfig, userConfig)
+  const envSearchBaseUrl = asNonEmptyString(process.env.SKILLS_API_URL)
+  const envDownloadBaseUrl = asNonEmptyString(process.env.SKILLS_DOWNLOAD_URL)
+
+  if (typeof configuredRegistry === 'string' && configuredRegistry.trim() !== '') {
+    const baseUrl = normalizeBaseUrl(configuredRegistry.trim())
+    return {
+      enabled: true,
+      searchBaseUrl: baseUrl,
+      downloadBaseUrl: baseUrl
+    }
+  }
+
+  if (configuredRegistry != null && typeof configuredRegistry === 'object') {
+    const baseUrl = normalizeBaseUrl(
+      asNonEmptyString(configuredRegistry.url) ?? DEFAULT_SKILL_REGISTRY_URL
+    )
+    return {
+      enabled: configuredRegistry.enabled !== false,
+      searchBaseUrl: normalizeBaseUrl(asNonEmptyString(configuredRegistry.searchUrl) ?? baseUrl),
+      downloadBaseUrl: normalizeBaseUrl(asNonEmptyString(configuredRegistry.downloadUrl) ?? baseUrl)
+    }
+  }
+
+  const baseUrl = normalizeBaseUrl(envSearchBaseUrl ?? DEFAULT_SKILL_REGISTRY_URL)
+  return {
+    enabled: true,
+    searchBaseUrl: baseUrl,
+    downloadBaseUrl: normalizeBaseUrl(envDownloadBaseUrl ?? baseUrl)
+  }
+}
+
+const fetchJson = async <T>(url: string): Promise<T> => {
+  const response = await fetch(url, {
+    signal: AbortSignal.timeout(FETCH_TIMEOUT_MS)
+  })
+  if (!response.ok) {
+    throw new Error(`Request failed with status ${response.status}`)
+  }
+  return await response.json() as T
+}
+
+const parseSourceAndSlugFromId = (id: string | undefined) => {
+  if (id == null) return undefined
+  const segments = id.split('/').filter(Boolean)
+  if (segments.length < 3) return undefined
+  return {
+    source: `${segments[0]}/${segments[1]}`,
+    slug: segments.slice(2).join('/')
+  }
+}
+
+const pickSearchResult = (
+  skills: RegistrySearchSkill[],
+  name: string
+) => {
+  const slug = toSkillSlug(name)
+  return skills.find(skill => (
+    skill.skillId === slug ||
+    skill.name === name ||
+    toSkillSlug(skill.name ?? '') === slug ||
+    parseSourceAndSlugFromId(skill.id)?.slug === slug
+  )) ?? skills[0]
+}
+
+const resolveRegistrySkillTarget = async (
+  dependency: NormalizedSkillDependency,
+  registry: RegistryOptions
+) => {
+  if (dependency.source != null) {
+    return {
+      source: dependency.source,
+      slug: toSkillSlug(dependency.name)
+    }
+  }
+
+  const searchUrl = appendVersionQuery(
+    `${registry.searchBaseUrl}/api/search?q=${encodeURIComponent(dependency.name)}&limit=10`,
+    dependency.version
+  )
+  const searchResult = await fetchJson<{
+    skills?: RegistrySearchSkill[]
+  }>(searchUrl)
+  const skills = Array.isArray(searchResult.skills) ? searchResult.skills : []
+  const picked = pickSearchResult(skills, dependency.name)
+  if (picked == null) {
+    throw new Error(`Skill ${dependency.name} was not found in ${registry.searchBaseUrl}`)
+  }
+
+  const parsed = parseSourceAndSlugFromId(picked.id)
+  const source = asNonEmptyString(picked.source) ?? parsed?.source
+  const slug = asNonEmptyString(picked.skillId) ?? parsed?.slug ?? toSkillSlug(picked.name ?? dependency.name)
+  if (source == null || slug === '') {
+    throw new Error(`Registry search result for ${dependency.name} did not include a source and skill id`)
+  }
+
+  return {
+    source,
+    slug
+  }
+}
+
+const toSafeRelativePath = (filePath: string) => {
+  const normalized = filePath.replace(/\\/g, '/')
+  if (normalized.startsWith('/') || normalized.split('/').includes('..')) {
+    throw new Error(`Unsafe skill dependency file path ${filePath}`)
+  }
+  return normalized
+}
+
+const assertInside = (root: string, target: string) => {
+  const relativePath = relative(root, target)
+  if (
+    relativePath === '' ||
+    (
+      relativePath !== '..' &&
+      !relativePath.startsWith(`..${sep}`) &&
+      !isAbsolute(relativePath)
+    )
+  ) {
+    return
+  }
+  throw new Error(`Skill dependency file resolves outside ${root}`)
+}
+
+const pathExists = async (path: string) => {
+  try {
+    await access(path)
+    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 buildInstallDir = (params: {
+  cwd: string
+  registry: RegistryOptions
+  source: string
+  slug: string
+  version?: string
+}) => {
+  let registryKey = params.registry.downloadBaseUrl
+  try {
+    const parsed = new URL(params.registry.downloadBaseUrl)
+    registryKey = `${parsed.hostname}${parsed.pathname}`
+  } catch {
+  }
+
+  return resolveProjectSharedCachePath(
+    params.cwd,
+    process.env,
+    'skill-dependencies',
+    toCacheSegment(registryKey),
+    ...params.source.split('/').map(toCacheSegment),
+    toCacheSegment(params.slug),
+    ...(params.version == null ? [] : [toCacheSegment(params.version)])
+  )
+}
+
+export const installRegistrySkillDependency = async (params: {
+  cwd: string
+  configs: [Config?, Config?]
+  dependency: NormalizedSkillDependency
+}) => {
+  const registry = resolveRegistryOptions({
+    configs: params.configs,
+    registry: params.dependency.registry
+  })
+  if (!registry.enabled) {
+    throw new Error(`Skill dependency registry is disabled; cannot install ${params.dependency.ref}`)
+  }
+
+  const target = await resolveRegistrySkillTarget(params.dependency, registry)
+  const [owner, repo] = target.source.split('/')
+  if (owner == null || repo == null || owner === '' || repo === '') {
+    throw new Error(`Skill dependency source ${target.source} must use owner/repo format`)
+  }
+
+  const downloadUrl = appendVersionQuery(
+    `${registry.downloadBaseUrl}/api/download/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}/${
+      encodeURIComponent(target.slug)
+    }`,
+    params.dependency.version
+  )
+  const installDir = buildInstallDir({
+    cwd: params.cwd,
+    registry,
+    source: target.source,
+    slug: target.slug,
+    version: params.dependency.version
+  })
+  const skillPath = resolve(installDir, 'SKILL.md')
+
+  return await withInstallLock(`${installDir}.lock`, async () => {
+    if (await pathExists(skillPath)) {
+      return {
+        installDir,
+        skillPath
+      }
+    }
+
+    const response = await fetchJson<RegistryDownloadResponse>(downloadUrl)
+    const files = Array.isArray(response.files) ? response.files : []
+    if (files.length === 0) {
+      throw new Error(`Skill dependency ${params.dependency.ref} did not include any files`)
+    }
+
+    const tempDir = `${installDir}.tmp-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}`
+    await rm(tempDir, { recursive: true, force: true })
+    await mkdir(tempDir, { recursive: true })
+
+    try {
+      let hasSkillMd = false
+      for (const file of files) {
+        const filePath = asNonEmptyString(file.path)
+        if (filePath == null || typeof file.contents !== 'string') continue
+        const relativePath = toSafeRelativePath(filePath)
+        if (relativePath.toLowerCase() === 'skill.md') hasSkillMd = true
+
+        const targetPath = resolve(tempDir, relativePath)
+        assertInside(tempDir, targetPath)
+        await mkdir(dirname(targetPath), { recursive: true })
+        await writeFile(targetPath, file.contents, 'utf8')
+      }
+
+      if (!hasSkillMd) {
+        throw new Error(`Skill dependency ${params.dependency.ref} did not include SKILL.md`)
+      }
+
+      await rm(installDir, { recursive: true, force: true })
+      await rename(tempDir, installDir)
+    } catch (error) {
+      await rm(tempDir, { recursive: true, force: true })
+      throw error
+    }
+
+    return {
+      installDir,
+      skillPath
+    }
+  })
+}

package/src/task-tool-guidance.ts

@@ -0,0 +1,15 @@
+export const buildManagedTaskToolGuidance = (serverName: string) => {
+  return [
+    'Task tool guide:',
+    `- Use \`${serverName}.StartTasks\` to start a new child task when the work should run in a separate entity or workspace, or when it needs to continue independently from the current turn.`,
+    `- After starting a task, use \`${serverName}.GetTaskInfo\` with \`{ taskId }\` to inspect one task. It is also the right tool when a task seems stalled, failed, or might be waiting for input.`,
+    '- By default, `GetTaskInfo` returns the 10 most recent log entries in descending order, so newer entries appear earlier in the `logs` array. Pass `logLimit` to inspect a different number of recent logs, and set `logOrder` to `"asc"` when you want the selected log window in oldest-to-newest order.',
+    `- Use \`${serverName}.ListTasks\` with the same \`logLimit\` and \`logOrder\` fields when you need to find a taskId or inspect multiple tasks at once.`,
+    `- Use \`${serverName}.SendTaskMessage\` with \`{ taskId, message, mode }\` when you want to continue the same task without starting a replacement task.`,
+    '- Choose `mode: "direct"` when the task is `running` and the new instruction should be delivered immediately into the current task.',
+    '- Choose `mode: "steer"` when the task should finish its current run naturally first, and the follow-up should be queued for the same task afterward.',
+    `- Use \`${serverName}.SubmitTaskInput\` only when \`${serverName}.GetTaskInfo\` or \`${serverName}.ListTasks\` shows \`pendingInput\` or \`pendingInteraction\`, or the task status is \`waiting_input\`. Do not use it for ordinary follow-up instructions or queued steer turns.`,
+    '- If a task is `completed` or `failed`, start a new task instead of trying to continue the old one.',
+    '- When a task is still making progress, use `wait` between checks instead of repeatedly restarting it.'
+  ].join('\n')
+}

package/src/workspace-prompt.ts

@@ -1,11 +1,14 @@
 import type { WorkspaceDefinitionPayload } from '@vibe-forge/types'
 import { CANONICAL_VIBE_FORGE_MCP_SERVER_NAME, resolvePromptPath } from '@vibe-forge/utils'
 
+import { buildManagedTaskToolGuidance } from './task-tool-guidance'
+
 export const generateWorkspaceRoutePrompt = (
   cwd: string,
   workspaces: WorkspaceDefinitionPayload[]
 ) => {
   if (workspaces.length === 0) return ''
+  const taskToolGuidance = buildManagedTaskToolGuidance(CANONICAL_VIBE_FORGE_MCP_SERVER_NAME)
 
   const workspaceList = workspaces
     .map((workspace) => {
@@ -24,6 +27,7 @@ export const generateWorkspaceRoutePrompt = (
     `${workspaceList}\n` +
     `When a user request targets one of these workspaces, start a child task with \`${CANONICAL_VIBE_FORGE_MCP_SERVER_NAME}.StartTasks\` using \`type: "workspace"\` and \`name\` set to the workspace identifier. ` +
     'Do not directly edit files inside a registered workspace from the current session unless the user explicitly asks this session to work in that directory.\n' +
+    `${taskToolGuidance}\n` +
     '</system-prompt>\n'
   )
 }

package/__tests__/skill-dependencies-cli.spec.ts

@@ -1,175 +0,0 @@
-/* eslint-disable import/first -- hoisted vitest mocks must be declared before importing the bundle entrypoint */
-import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises'
-import os from 'node:os'
-import path, { join } from 'node:path'
-
-import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
-
-const mocks = vi.hoisted(() => ({
-  findSkillsCli: vi.fn(),
-  installSkillsCliRefToTemp: vi.fn(),
-  installSkillsCliSkillToTemp: vi.fn()
-}))
-
-vi.mock('@vibe-forge/utils/skills-cli', async () => {
-  const actual = await vi.importActual<typeof import('@vibe-forge/utils/skills-cli')>('@vibe-forge/utils/skills-cli')
-  return {
-    ...actual,
-    findSkillsCli: mocks.findSkillsCli,
-    installSkillsCliRefToTemp: mocks.installSkillsCliRefToTemp,
-    installSkillsCliSkillToTemp: mocks.installSkillsCliSkillToTemp
-  }
-})
-
-import { buildAdapterAssetPlan, resolveWorkspaceAssetBundle } from '#~/index.js'
-
-import { createWorkspace, writeDocument } from './test-helpers'
-
-describe('skills CLI dependency resolution', () => {
-  let installWorkspace: string
-
-  beforeEach(async () => {
-    installWorkspace = await mkdtemp(path.join(os.tmpdir(), 'vf-skills-cli-dependency-'))
-    vi.clearAllMocks()
-  })
-
-  afterEach(async () => {
-    await rm(installWorkspace, { recursive: true, force: true })
-  })
-
-  it('installs missing bare-name dependencies through skills CLI by default', async () => {
-    const workspace = await createWorkspace()
-    const installedSkillDir = join(installWorkspace, '.agents', 'skills', 'frontend-design')
-    await mkdir(installedSkillDir, { recursive: true })
-    await writeFile(
-      join(installedSkillDir, 'SKILL.md'),
-      '---\nname: frontend-design\ndescription: UI design guidance\n---\nUse strong visual hierarchy.\n'
-    )
-
-    mocks.findSkillsCli.mockResolvedValue([
-      {
-        installRef: 'anthropics/skills@frontend-design',
-        source: 'anthropics/skills',
-        skill: 'frontend-design'
-      }
-    ])
-    mocks.installSkillsCliRefToTemp.mockResolvedValue({
-      tempDir: installWorkspace,
-      installedSkill: {
-        dirName: 'frontend-design',
-        name: 'frontend-design',
-        sourcePath: installedSkillDir
-      }
-    })
-
-    await writeDocument(
-      join(workspace, '.ai/skills/app-builder/SKILL.md'),
-      [
-        '---',
-        'name: app-builder',
-        'description: Build apps',
-        'dependencies:',
-        '  - frontend-design',
-        '---',
-        'Build the app.'
-      ].join('\n')
-    )
-
-    const bundle = await resolveWorkspaceAssetBundle({
-      cwd: workspace,
-      configs: [undefined, undefined],
-      useDefaultVibeForgeMcpServer: false
-    })
-
-    await buildAdapterAssetPlan({
-      adapter: 'opencode',
-      bundle,
-      options: {
-        skills: {
-          include: ['app-builder']
-        }
-      }
-    })
-
-    const dependency = bundle.skills.find(asset => asset.name === 'frontend-design')
-    expect(bundle.skills.map(asset => asset.name).sort()).toEqual(['app-builder', 'frontend-design'])
-    expect(dependency?.sourcePath).toContain(
-      '/.ai/caches/skill-dependencies/skills-cli/skills/latest/default/anthropics/skills/frontend-design/'
-    )
-    expect(mocks.findSkillsCli).toHaveBeenCalledWith({
-      config: undefined,
-      query: 'frontend-design'
-    })
-    expect(mocks.installSkillsCliRefToTemp).toHaveBeenCalledWith({
-      config: undefined,
-      installRef: 'anthropics/skills@frontend-design'
-    })
-  })
-
-  it('merges top-level skillsCli config ahead of legacy skills.cli aliases', async () => {
-    const workspace = await createWorkspace()
-    const installedSkillDir = join(installWorkspace, '.agents', 'skills', 'frontend-design')
-    await mkdir(installedSkillDir, { recursive: true })
-    await writeFile(
-      join(installedSkillDir, 'SKILL.md'),
-      '---\nname: frontend-design\ndescription: UI design guidance\n---\nUse internal design system.\n'
-    )
-
-    mocks.installSkillsCliSkillToTemp.mockResolvedValue({
-      tempDir: installWorkspace,
-      installedSkill: {
-        dirName: 'frontend-design',
-        name: 'frontend-design',
-        sourcePath: installedSkillDir
-      }
-    })
-
-    await writeDocument(
-      join(workspace, '.ai/skills/app-builder/SKILL.md'),
-      [
-        '---',
-        'name: app-builder',
-        'description: Build apps',
-        'dependencies:',
-        '  - example-source/default/public@frontend-design',
-        '---',
-        'Build the app.'
-      ].join('\n')
-    )
-
-    const bundle = await resolveWorkspaceAssetBundle({
-      cwd: workspace,
-      configs: [{
-        skills: {
-          cli: {
-            package: 'legacy-skills'
-          }
-        },
-        skillsCli: {
-          package: '@byted/skills',
-          registry: 'https://registry.example.com'
-        }
-      }, undefined],
-      useDefaultVibeForgeMcpServer: false
-    })
-
-    await buildAdapterAssetPlan({
-      adapter: 'opencode',
-      bundle,
-      options: {
-        skills: {
-          include: ['app-builder']
-        }
-      }
-    })
-
-    expect(mocks.installSkillsCliSkillToTemp).toHaveBeenCalledWith({
-      config: {
-        package: '@byted/skills',
-        registry: 'https://registry.example.com'
-      },
-      skill: 'frontend-design',
-      source: 'example-source/default/public'
-    })
-  })
-})

package/src/configured-skills.ts

@@ -1,99 +0,0 @@
-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
-}