@vibe-forge/workspace-assets 2.0.3 → 2.0.4-alpha.0

package/src/skills-cli-dependency-helpers.ts

@@ -0,0 +1,94 @@
+import { access, copyFile, lstat, mkdir, readdir } from 'node:fs/promises'
+import { dirname, resolve } from 'node:path'
+import process from 'node:process'
+
+import { withDirectoryInstallLock } from '@vibe-forge/utils/install-lock'
+import { resolveProjectSharedCachePath } from '@vibe-forge/utils/project-cache-path'
+import { toSkillSlug } from '@vibe-forge/utils/skills-cli'
+
+const toCacheSegment = (value: string) => (
+  value
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, '-')
+    .replace(/^-+|-+$/g, '') || 'default'
+)
+
+export const pathExists = async (targetPath: string) => {
+  try {
+    await access(targetPath)
+    return true
+  } catch {
+    return false
+  }
+}
+
+export const withInstallLock = async <T>(lockDir: string, callback: () => Promise<T>) => {
+  try {
+    return await withDirectoryInstallLock({ lockDir }, callback)
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    throw new Error(
+      message.replace('Timed out waiting for install lock', 'Timed out waiting for skill dependency install lock')
+    )
+  }
+}
+
+export 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
+}
+
+export const pickSearchResult = <T extends { skill: string }>(
+  results: T[],
+  name: string
+) => {
+  const slug = toSkillSlug(name)
+  return results.find(result => (
+    result.skill === name ||
+    toSkillSlug(result.skill) === slug
+  )) ?? results[0]
+}
+
+export const buildInstallDir = (params: {
+  cwd: string
+  registry?: string
+  skill: string
+  source: string
+  version?: string
+}) => {
+  const registry = params.registry ?? 'default'
+  return resolveProjectSharedCachePath(
+    params.cwd,
+    process.env,
+    'skill-dependencies',
+    'skills-cli',
+    toCacheSegment('skills'),
+    toCacheSegment('latest'),
+    toCacheSegment(registry),
+    ...params.source.split('/').map(toCacheSegment),
+    toCacheSegment(params.version ?? 'latest'),
+    toCacheSegment(params.skill)
+  )
+}

package/src/skills-cli-dependency.ts

@@ -0,0 +1,104 @@
+import { mkdir, rename, rm } from 'node:fs/promises'
+import { resolve } from 'node:path'
+import process from 'node:process'
+
+import type { Config } from '@vibe-forge/types'
+import { findSkillsCli, installSkillsCliRefToTemp, installSkillsCliSkillToTemp } from '@vibe-forge/utils/skills-cli'
+
+import type { NormalizedSkillDependency } from './skill-dependencies'
+import {
+  buildInstallDir,
+  copyRegularFiles,
+  pathExists,
+  pickSearchResult,
+  withInstallLock
+} from './skills-cli-dependency-helpers'
+
+export const installSkillsCliDependency = async (params: {
+  cwd: string
+  configs: [Config?, Config?]
+  dependency: NormalizedSkillDependency
+}) => {
+  const resolvedTarget = params.dependency.source != null
+    ? {
+      skill: params.dependency.name,
+      source: params.dependency.source
+    }
+    : await (async () => {
+      const searchResults = await findSkillsCli({
+        registry: params.dependency.registry,
+        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({
+    cwd: params.cwd,
+    registry: params.dependency.registry,
+    skill: resolvedTarget.skill,
+    source: resolvedTarget.source,
+    version: params.dependency.version
+  })
+  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
+      ? params.dependency.version == null
+        ? await installSkillsCliRefToTemp({
+          installRef: resolvedTarget.installRef,
+          registry: params.dependency.registry
+        })
+        : await installSkillsCliSkillToTemp({
+          registry: params.dependency.registry,
+          skill: resolvedTarget.skill,
+          source: resolvedTarget.source,
+          version: params.dependency.version
+        })
+      : await installSkillsCliSkillToTemp({
+        registry: params.dependency.registry,
+        skill: resolvedTarget.skill,
+        source: resolvedTarget.source,
+        version: params.dependency.version
+      })
+
+    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/task-tool-guidance.ts

@@ -5,10 +5,8 @@ export const buildManagedTaskToolGuidance = (serverName: string) => {
     `- 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.`,
+    `- Use \`${serverName}.SendTaskMessage\` with \`{ taskId, message }\` only when a task status is \`running\` and you need to give it another instruction without starting a replacement task.`,
+    `- 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.`,
     '- 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/__tests__/skill-dependencies.spec.ts

@@ -1,80 +0,0 @@
-import { join } from 'node:path'
-
-import { afterEach, describe, expect, it, vi } from 'vitest'
-
-import { buildAdapterAssetPlan, resolveWorkspaceAssetBundle } from '#~/index.js'
-import { normalizeSkillDependency } from '#~/skill-dependencies.js'
-
-import { createWorkspace, writeDocument } from './test-helpers'
-
-afterEach(() => {
-  vi.unstubAllGlobals()
-})
-
-describe('skill dependency normalization', () => {
-  it('parses legacy non-structured registry strings', () => {
-    expect(
-      normalizeSkillDependency('https://bnpm.byted.org@skills.byted.org/lynx/skills@lynx-devtool@1.0.3')
-    ).toEqual({
-      ref: 'https://bnpm.byted.org@skills.byted.org/lynx/skills@lynx-devtool@1.0.3',
-      name: 'lynx-devtool',
-      source: 'lynx/skills',
-      registry: 'https://skills.byted.org',
-      version: '1.0.3',
-      packageRegistry: 'https://bnpm.byted.org'
-    })
-  })
-
-  it('installs legacy non-structured registry dependencies through the skill registry API', async () => {
-    const workspace = await createWorkspace()
-    const fetchMock = vi.fn(async (url: string) => {
-      if (url === 'https://skills.byted.org/api/download/lynx/skills/lynx-devtool?version=1.0.3') {
-        return new Response(JSON.stringify({
-          files: [{
-            path: 'SKILL.md',
-            contents: '---\nname: lynx-devtool\ndescription: Lynx device debugging\n---\nUse devtool.\n'
-          }]
-        }))
-      }
-      return new Response('not found', { status: 404 })
-    })
-    vi.stubGlobal('fetch', fetchMock)
-
-    await writeDocument(
-      join(workspace, '.ai/skills/debug-lynx/SKILL.md'),
-      [
-        '---',
-        'name: debug-lynx',
-        'description: Debug Lynx on device',
-        'dependencies:',
-        '  - https://bnpm.byted.org@skills.byted.org/lynx/skills@lynx-devtool@1.0.3',
-        '---',
-        'Run the full debugging workflow.'
-      ].join('\n')
-    )
-
-    const bundle = await resolveWorkspaceAssetBundle({
-      cwd: workspace,
-      configs: [undefined, undefined],
-      useDefaultVibeForgeMcpServer: false
-    })
-
-    await buildAdapterAssetPlan({
-      adapter: 'opencode',
-      bundle,
-      options: {
-        skills: {
-          include: ['debug-lynx']
-        }
-      }
-    })
-
-    expect(fetchMock).toHaveBeenCalledWith(
-      'https://skills.byted.org/api/download/lynx/skills/lynx-devtool?version=1.0.3',
-      expect.any(Object)
-    )
-    expect(bundle.skills.find(asset => asset.name === 'lynx-devtool')?.sourcePath).toContain(
-      '/.ai/caches/skill-dependencies/skills.byted.org/lynx/skills/lynx-devtool/1.0.3/'
-    )
-  })
-})

package/src/skill-registry.ts

@@ -1,345 +0,0 @@
-/* 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
-    }
-  })
-}