KB Source Resolution

                  KB Source Resolution
                         |
                 --source provided?
                /                  \
              YES                   NO
               |                     |
          --offline?            In monorepo?
          /        \            /          \
        YES        NO        YES          NO
         |          |          |            |
    Validate    Parse      Use monorepo   Download
    is local    source     dataset        from GitHub
    path        type
                  |
          ┌──────┼──────┐
         Git   Remote  Local
          |      URL    path
        Clone    |       |
        repo   Download  Use
        to     from URL  directly
        temp

function isGitUrl(source: string): boolean {
  const base = source.replace(/#.*$/, '')
  return (
    /^git:\/\//.test(base) ||
    /^git@[\w.-]+:/.test(base) ||
    /^ssh:\/\/git@/.test(base) ||
    (/^https?:\/\//.test(base) && base.endsWith('.git'))
  )
}

function isUrl(source: string): boolean {
  return source.startsWith('http://') || source.startsWith('https://')
}

function isLocalPath(source: string): boolean {
  return (
    source.startsWith('/') ||          // Absolute Unix path
    source.startsWith('./') ||         // Relative path
    source.startsWith('../') ||        // Relative parent path
    /^[A-Za-z]:[/\\]/.test(source)    // Windows absolute path
  )
}

function isMonorepo(): boolean {
  const monorepoKbPath = path.resolve(process.cwd(), 'packages/knowledge-hub/dataset')
  return fs.existsSync(monorepoKbPath)
}

interface KbSource {
  type: 'url' | 'local' | 'monorepo' | 'github-release'
  location: string
  requiresDownload: boolean
}
 
async function resolveKbSource(options: {
  source?: string
  offline?: boolean
}): Promise<KbSource> {
  // Precedence 1: Explicit --source flag
  if (options.source) {
    if (isUrl(options.source)) {
      if (options.offline) {
        throw new Error('Cannot use --offline with remote URL')
      }
      return { type: 'url', location: options.source, requiresDownload: true }
    } else if (isLocalPath(options.source)) {
      const resolvedPath = path.resolve(options.source)
      if (!fs.existsSync(resolvedPath)) {
        throw new Error(`KB source path does not exist: ${resolvedPath}`)
      }
      return { type: 'local', location: resolvedPath, requiresDownload: false }
    } else {
      throw new Error(`Invalid source format: ${options.source}`)
    }
  }
 
  // Precedence 2: Monorepo default
  if (isMonorepo()) {
    return {
      type: 'monorepo',
      location: path.resolve('packages/knowledge-hub/dataset'),
      requiresDownload: false,
    }
  }
 
  // Precedence 3: GitHub release auto-download
  if (options.offline) {
    throw new Error('Cannot auto-download KB in offline mode')
  }
  return {
    type: 'github-release',
    location: await getLatestReleaseUrl(),
    requiresDownload: true,
  }
}