@foundation0/api 1.1.1 → 1.1.2

package/projects.ts

@@ -160,6 +160,73 @@ export type ProjectWriteGitTaskResult = {
   issue: ProjectGitTaskRecord
 }
 
+type ProjectSearchTargetSection = 'docs' | 'spec'
+
+type ProjectSearchOptions = {
+  projectName?: string
+  owner?: string
+  repo?: string
+  ref?: string
+  branch?: string
+  sha?: string
+  source?: 'local' | 'gitea' | 'auto'
+  remote?: boolean
+  processRoot?: string
+  cacheDir?: string
+  refresh?: boolean
+  args?: unknown[]
+}
+
+type RgLikeSearchQuery = {
+  patterns: string[]
+  paths: string[]
+  lineNumber: boolean
+  withFilename: boolean
+  noFilename: boolean
+  ignoreCase: boolean
+  caseSensitive: boolean
+  smartCase: boolean
+  fixedStrings: boolean
+  wordRegexp: boolean
+  maxCount: number | null
+  countOnly: boolean
+  filesWithMatches: boolean
+  filesWithoutMatch: boolean
+  onlyMatching: boolean
+  includeHidden: boolean
+  globs: string[]
+}
+
+type RgLikeCompiledPattern = {
+  test: RegExp
+  global: RegExp
+}
+
+type RgLikeSearchExecutionResult = {
+  filesSearched: number
+  filesMatched: number
+  matchedLines: number
+  matchedSegments: number
+  outputLines: string[]
+}
+
+export type ProjectSearchResult = {
+  projectName: string
+  owner: string | null
+  repo: string | null
+  section: ProjectSearchTargetSection
+  ref: string | null
+  source: 'gitea' | 'local'
+  cacheDir: string
+  cacheRefreshed: boolean
+  args: string[]
+  filesSearched: number
+  filesMatched: number
+  matchedLines: number
+  matchedSegments: number
+  output: string
+}
+
 const CLI_NAME = 'example'
 const VERSION_RE = 'v?\\d+(?:\\.\\d+){2,}'
 const VERSION_RE_CORE = `(?:${VERSION_RE})`
@@ -185,6 +252,8 @@ const DEFAULT_TRACKS_CANDIDATES = [
   path.join('spec', '07_roadmap', 'tracks.md'),
 ] as const
 const PROJECTS_DIRECTORY = 'projects'
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value)
 
 type ProjectDocsCandidateKind = 'active' | 'plain' | 'versioned'
 
@@ -271,6 +340,1126 @@ export async function readProjectDoc(
   return content
 }
 
+export async function searchDocs(projectName: string, ...rawArgs: unknown[]): Promise<ProjectSearchResult> {
+  return searchProjectSection(projectName, 'docs', rawArgs)
+}
+
+export async function searchSpecs(projectName: string, ...rawArgs: unknown[]): Promise<ProjectSearchResult> {
+  return searchProjectSection(projectName, 'spec', rawArgs)
+}
+
+async function searchProjectSection(
+  projectNameInput: unknown,
+  section: ProjectSearchTargetSection,
+  rawArgs: unknown[]
+): Promise<ProjectSearchResult> {
+  const seedOptions = isRecord(projectNameInput) ? projectNameInput : {}
+  const { rgArgs, options } = parseProjectSearchInvocationWithSeed(rawArgs, seedOptions)
+  const processRoot = parseStringOption(options.processRoot) ?? process.cwd()
+  const positionalProjectName = typeof projectNameInput === 'string' ? projectNameInput.trim() : ''
+  const optionProjectName = parseStringOption(options.projectName) ?? ''
+  const sourcePreference = parseSearchSourceOption(options.source, options.remote)
+
+  if (!positionalProjectName && !optionProjectName) {
+    throw new Error('Missing project name. Pass it as first arg or options.projectName.')
+  }
+
+  let projectName = positionalProjectName || optionProjectName
+  let projectRoot: string | null = null
+
+  if (positionalProjectName && optionProjectName && positionalProjectName !== optionProjectName) {
+    const resolvedPositional = tryResolveProjectRoot(positionalProjectName, processRoot)
+    const resolvedOption = tryResolveProjectRoot(optionProjectName, processRoot)
+
+    if (!resolvedPositional && resolvedOption) {
+      projectName = optionProjectName
+      projectRoot = resolvedOption
+    } else if (resolvedPositional && !resolvedOption) {
+      projectName = positionalProjectName
+      projectRoot = resolvedPositional
+    } else if (!resolvedPositional && !resolvedOption) {
+      throw new Error(
+        `Could not resolve project-name from positional "${positionalProjectName}" or options.projectName "${optionProjectName}".`,
+      )
+    } else {
+      throw new Error(
+        `Conflicting project names: positional "${positionalProjectName}" and options.projectName "${optionProjectName}". Use one.`,
+      )
+    }
+  }
+
+  if (!projectRoot) {
+    projectRoot = resolveProjectRoot(projectName, processRoot)
+  }
+
+  const ownerFromOptions = parseStringOption(options.owner)
+  const repoFromOptions = parseStringOption(options.repo)
+  const resolvedIdentity = (!ownerFromOptions || !repoFromOptions)
+    ? tryResolveGitIdentityFromProject(projectRoot)
+    : null
+  const owner = ownerFromOptions ?? resolvedIdentity?.owner ?? null
+  const repo = repoFromOptions ?? resolvedIdentity?.repo ?? null
+  const ref = parseStringOption(options.ref) ?? parseStringOption(options.branch) ?? parseStringOption(options.sha) ?? null
+
+  const cacheRoot = resolveProjectSearchCacheRoot({
+    processRoot,
+    projectName,
+    owner: owner ?? 'unknown-owner',
+    repo: repo ?? 'unknown-repo',
+    section,
+    ref,
+    cacheDir: parseStringOption(options.cacheDir),
+  })
+
+  const cacheSync = await syncProjectSearchCache({
+    owner,
+    repo,
+    projectRoot,
+    section,
+    ref,
+    cacheRoot,
+    sourcePreference,
+    refresh: parseBooleanOption(options.refresh),
+  })
+
+  const query = parseRgLikeQueryArgs(rgArgs)
+  const searchResult = await executeRgLikeSearch(cacheRoot, query)
+
+  return {
+    projectName,
+    owner,
+    repo,
+    section,
+    ref,
+    source: cacheSync.source,
+    cacheDir: cacheRoot,
+    cacheRefreshed: cacheSync.refreshed,
+    args: rgArgs,
+    filesSearched: searchResult.filesSearched,
+    filesMatched: searchResult.filesMatched,
+    matchedLines: searchResult.matchedLines,
+    matchedSegments: searchResult.matchedSegments,
+    output: searchResult.outputLines.join('\n'),
+  }
+}
+
+function parseProjectSearchInvocation(rawArgs: unknown[]): { rgArgs: string[]; options: ProjectSearchOptions } {
+  return parseProjectSearchInvocationWithSeed(rawArgs, {})
+}
+
+function parseProjectSearchInvocationWithSeed(
+  rawArgs: unknown[],
+  seedOptions: Record<string, unknown>,
+): { rgArgs: string[]; options: ProjectSearchOptions } {
+  const options: Record<string, unknown> = { ...seedOptions }
+  let rgArgs: string[] = []
+
+  if (rawArgs.length > 0) {
+    const maybeOptions = rawArgs[rawArgs.length - 1]
+    if (isRecord(maybeOptions)) {
+      rgArgs = rawArgs.slice(0, -1).map((value) => String(value))
+      for (const [key, value] of Object.entries(maybeOptions)) {
+        options[key] = value
+      }
+    } else {
+      rgArgs = rawArgs.map((value) => String(value))
+    }
+  }
+
+  if (rgArgs.length === 0 && Array.isArray(options.args)) {
+    rgArgs = options.args.map((value) => String(value))
+  }
+
+  return {
+    rgArgs,
+    options: options as ProjectSearchOptions,
+  }
+}
+
+function parseStringOption(value: unknown): string | null {
+  if (typeof value !== 'string') {
+    return null
+  }
+  const trimmed = value.trim()
+  return trimmed.length > 0 ? trimmed : null
+}
+
+function parseBooleanOption(value: unknown): boolean {
+  return value === true || value === 1 || value === '1' || value === 'true' || value === 'yes' || value === 'on'
+}
+
+function tryResolveProjectRoot(projectName: string, processRoot: string): string | null {
+  try {
+    return resolveProjectRoot(projectName, processRoot)
+  } catch {
+    return null
+  }
+}
+
+function tryResolveGitIdentityFromProject(projectRoot: string): { owner: string; repo: string } | null {
+  try {
+    return resolveGitIdentityFromProject(projectRoot)
+  } catch {
+    return null
+  }
+}
+
+function resolveProjectSearchCacheRoot(input: {
+  processRoot: string
+  projectName: string
+  owner: string
+  repo: string
+  section: ProjectSearchTargetSection
+  ref: string | null
+  cacheDir: string | null
+}): string {
+  if (input.cacheDir) {
+    return path.resolve(input.cacheDir)
+  }
+
+  const refToken = input.ref ?? 'HEAD'
+  const refHash = crypto.createHash('sha256').update(refToken).digest('hex').slice(0, 12)
+  const ownerToken = input.owner.replace(/[^a-zA-Z0-9_.-]+/g, '_')
+  const repoToken = input.repo.replace(/[^a-zA-Z0-9_.-]+/g, '_')
+  const projectToken = input.projectName.replace(/[^a-zA-Z0-9_.-]+/g, '_')
+
+  return path.join(
+    input.processRoot,
+    '.cache',
+    'project-search',
+    projectToken,
+    ownerToken,
+    repoToken,
+    input.section,
+    refHash,
+  )
+}
+
+async function syncProjectSearchCache(input: {
+  owner: string | null
+  repo: string | null
+  projectRoot: string
+  section: ProjectSearchTargetSection
+  ref: string | null
+  cacheRoot: string
+  sourcePreference: 'local' | 'gitea' | 'auto'
+  refresh: boolean
+}): Promise<{ refreshed: boolean; source: 'gitea' | 'local' }> {
+  const manifestPath = path.join(input.cacheRoot, '.search-cache.json')
+  const localSectionRoot = path.join(input.projectRoot, input.section)
+  const localAvailable = existsDir(localSectionRoot)
+
+  if (!input.refresh && existsFile(manifestPath)) {
+    const existingSource = (await readCacheSource(manifestPath)) ?? 'local'
+
+    // Prefer local if available unless the caller explicitly forces remote.
+    if (existingSource === 'gitea' && input.sourcePreference !== 'gitea' && localAvailable) {
+      // fall through and refresh to local
+    } else if (existingSource === 'local' && input.sourcePreference === 'gitea') {
+      // fall through and refresh to remote
+    } else {
+      return { refreshed: false, source: existingSource }
+    }
+  }
+
+  await fs.rm(input.cacheRoot, { recursive: true, force: true })
+  await fs.mkdir(input.cacheRoot, { recursive: true })
+
+  const canUseRemote = Boolean(input.owner && input.repo) && canResolveGiteaHost()
+  const shouldUseRemote = (() => {
+    if (input.sourcePreference === 'gitea') return true
+    if (input.sourcePreference === 'local') return false
+    // auto: local-first, remote only if local isn't available
+    return !localAvailable
+  })()
+
+  if (shouldUseRemote) {
+    if (!canUseRemote) {
+      const missing = [
+        !input.owner ? 'owner' : null,
+        !input.repo ? 'repo' : null,
+        !canResolveGiteaHost() ? 'GITEA_HOST' : null,
+      ].filter((value): value is string => Boolean(value))
+      throw new Error(`Remote search requested but missing: ${missing.join(', ')}`)
+    }
+
+    const git = createGitServiceApi({
+      config: {
+        platform: 'GITEA',
+        giteaHost: resolveGiteaHost(),
+        giteaToken: process.env.GITEA_TOKEN,
+      },
+      defaultOwner: input.owner ?? undefined,
+      defaultRepo: input.repo ?? undefined,
+    })
+
+    const listContents = resolveRepoContentsApiMethod(git, 'list')
+    const viewContents = resolveRepoContentsApiMethod(git, 'view')
+
+    const remoteFiles = await collectRepoSectionFiles(listContents, input.owner as string, input.repo as string, input.section, input.ref)
+    for (const remotePath of remoteFiles) {
+      const relative = stripSectionPrefix(remotePath, input.section)
+      if (!relative) {
+        continue
+      }
+      const content = await loadRepoFileContent(viewContents, input.owner as string, input.repo as string, remotePath, input.ref)
+      const outPath = path.join(input.cacheRoot, relative)
+      await fs.mkdir(path.dirname(outPath), { recursive: true })
+      await fs.writeFile(outPath, content, 'utf8')
+    }
+
+    await fs.writeFile(
+      manifestPath,
+      JSON.stringify(
+        {
+          source: 'gitea',
+          owner: input.owner,
+          repo: input.repo,
+          section: input.section,
+          ref: input.ref,
+          fileCount: remoteFiles.length,
+          updatedAt: new Date().toISOString(),
+        },
+        null,
+        2,
+      ) + '\n',
+      'utf8',
+    )
+
+    return { refreshed: true, source: 'gitea' }
+  }
+
+  if (!localAvailable) {
+    throw new Error(`Section directory not found in project: ${localSectionRoot}`)
+  }
+
+  const copied = await copyProjectSectionToCache(localSectionRoot, input.cacheRoot)
+
+  await fs.writeFile(
+    manifestPath,
+    JSON.stringify(
+      {
+        source: 'local',
+        owner: input.owner,
+        repo: input.repo,
+        section: input.section,
+        ref: input.ref,
+        fileCount: copied,
+        updatedAt: new Date().toISOString(),
+      },
+      null,
+      2,
+    ) + '\n',
+    'utf8',
+  )
+
+  return { refreshed: true, source: 'local' }
+}
+
+function parseSearchSourceOption(value: unknown, remoteFlag: unknown): 'local' | 'gitea' | 'auto' {
+  if (parseBooleanOption(remoteFlag)) {
+    return 'gitea'
+  }
+  const normalized = parseStringOption(value)?.toLowerCase()
+  if (!normalized) return 'auto'
+  if (normalized === 'local') return 'local'
+  if (normalized === 'gitea' || normalized === 'remote') return 'gitea'
+  if (normalized === 'auto') return 'auto'
+  throw new Error(`Invalid search source: ${normalized}. Expected "local", "gitea", or "auto".`)
+}
+
+function canResolveGiteaHost(): boolean {
+  return Boolean(process.env.GITEA_HOST ?? process.env.EXAMPLE_GITEA_HOST)
+}
+
+async function readCacheSource(manifestPath: string): Promise<'gitea' | 'local' | null> {
+  try {
+    const raw = await fs.readFile(manifestPath, 'utf8')
+    const parsed = JSON.parse(raw)
+    const source = (parsed as any)?.source
+    if (source === 'gitea' || source === 'local') {
+      return source
+    }
+    return null
+  } catch {
+    return null
+  }
+}
+
+async function copyProjectSectionToCache(sectionRoot: string, cacheRoot: string): Promise<number> {
+  let copied = 0
+  const queue: Array<{ from: string; rel: string }> = [{ from: sectionRoot, rel: '' }]
+
+  while (queue.length > 0) {
+    const current = queue.shift()
+    if (!current) {
+      continue
+    }
+
+    const entries = await fs.readdir(current.from, { withFileTypes: true })
+    for (const entry of entries) {
+      if (entry.name.toLowerCase() === PROJECT_ARCHIVE_DIR_NAME) {
+        continue
+      }
+
+      const fromPath = path.join(current.from, entry.name)
+      const relPath = current.rel ? `${current.rel}/${entry.name}` : entry.name
+      const outPath = path.join(cacheRoot, relPath)
+
+      if (entry.isDirectory()) {
+        queue.push({ from: fromPath, rel: relPath })
+        continue
+      }
+
+      if (!entry.isFile() && !entry.isSymbolicLink()) {
+        continue
+      }
+
+      const content = await readTextIfExists(fromPath)
+      if (content === null) {
+        continue
+      }
+      await fs.mkdir(path.dirname(outPath), { recursive: true })
+      await fs.writeFile(outPath, content, 'utf8')
+      copied += 1
+    }
+  }
+
+  return copied
+}
+
+function resolveRepoContentsApiMethod(api: GitServiceApi, action: 'list' | 'view'): GitServiceApiMethod {
+  const repoNamespace = api.repo
+  if (!repoNamespace || typeof repoNamespace !== 'object') {
+    throw new Error('Git service API does not expose repo namespace')
+  }
+
+  const contentsNamespace = (repoNamespace as Record<string, unknown>).contents
+  if (!contentsNamespace || typeof contentsNamespace !== 'object') {
+    throw new Error('Git service API does not expose repo.contents namespace')
+  }
+
+  const method = (contentsNamespace as Record<string, unknown>)[action]
+  if (typeof method !== 'function') {
+    throw new Error(`Git service API does not expose repo.contents.${action}`)
+  }
+
+  return method as GitServiceApiMethod
+}
+
+function buildRepoContentsQueryOptions(ref: string | null): Record<string, unknown> | null {
+  if (!ref) {
+    return null
+  }
+
+  return {
+    query: {
+      ref,
+    },
+  }
+}
+
+async function collectRepoSectionFiles(
+  listContents: GitServiceApiMethod,
+  owner: string,
+  repo: string,
+  section: ProjectSearchTargetSection,
+  ref: string | null,
+): Promise<string[]> {
+  const discovered = new Set<string>()
+  const queue: string[] = [section]
+  const queryOptions = buildRepoContentsQueryOptions(ref)
+
+  while (queue.length > 0) {
+    const current = queue.shift()
+    if (!current) {
+      continue
+    }
+
+    const args: unknown[] = [owner, repo, current]
+    if (queryOptions) {
+      args.push(queryOptions)
+    }
+
+    const result = await listContents(...args)
+    if (!result.ok) {
+      throw new Error(
+        `Failed to list repo contents at ${current} (${owner}/${repo}). status=${result.status}`,
+      )
+    }
+
+    const entries = normalizeRepoContentsEntries(result.body, current)
+    for (const entry of entries) {
+      if (entry.type === 'dir') {
+        queue.push(entry.path)
+        continue
+      }
+
+      if (entry.type === 'file') {
+        discovered.add(entry.path)
+      }
+    }
+  }
+
+  return Array.from(discovered).sort((left, right) => left.localeCompare(right))
+}
+
+function normalizeRepoContentsEntries(
+  body: unknown,
+  currentPath: string,
+): Array<{ path: string; type: 'file' | 'dir' | 'other' }> {
+  const entries = Array.isArray(body) ? body : [body]
+  const normalized: Array<{ path: string; type: 'file' | 'dir' | 'other' }> = []
+
+  for (const entry of entries) {
+    if (!isRecord(entry)) {
+      continue
+    }
+
+    const rawType = typeof entry.type === 'string' ? entry.type.toLowerCase() : 'other'
+    const type = rawType === 'dir' || rawType === 'file' ? rawType : 'other'
+    const explicitPath = typeof entry.path === 'string' && entry.path.trim().length > 0
+      ? entry.path.trim().replace(/\\/g, '/')
+      : null
+    const explicitName = typeof entry.name === 'string' && entry.name.trim().length > 0
+      ? entry.name.trim()
+      : null
+    const resolvedPath = explicitPath
+      ?? (explicitName ? `${currentPath.replace(/\\/g, '/')}/${explicitName}` : null)
+
+    if (!resolvedPath) {
+      continue
+    }
+
+    normalized.push({
+      path: resolvedPath,
+      type,
+    })
+  }
+
+  return normalized
+}
+
+function stripSectionPrefix(remotePath: string, section: ProjectSearchTargetSection): string {
+  const normalized = remotePath.replace(/\\/g, '/')
+  if (normalized === section) {
+    return ''
+  }
+  if (normalized.startsWith(`${section}/`)) {
+    return normalized.slice(section.length + 1)
+  }
+  return ''
+}
+
+async function loadRepoFileContent(
+  viewContents: GitServiceApiMethod,
+  owner: string,
+  repo: string,
+  remotePath: string,
+  ref: string | null,
+): Promise<string> {
+  const args: unknown[] = [owner, repo, remotePath]
+  const queryOptions = buildRepoContentsQueryOptions(ref)
+  if (queryOptions) {
+    args.push(queryOptions)
+  }
+
+  const result = await viewContents(...args)
+  if (!result.ok) {
+    throw new Error(
+      `Failed to read repo file ${remotePath} (${owner}/${repo}). status=${result.status}`,
+    )
+  }
+
+  const content = extractRepoFileContent(result.body)
+  if (content === null) {
+    throw new Error(`Repo response for ${remotePath} did not contain textual file content.`)
+  }
+
+  return content
+}
+
+function extractRepoFileContent(body: unknown): string | null {
+  if (!isRecord(body)) {
+    return null
+  }
+
+  if (typeof body.content !== 'string') {
+    return null
+  }
+
+  const raw = body.content
+  const encoding = typeof body.encoding === 'string' ? body.encoding.toLowerCase() : ''
+
+  if (encoding === 'base64') {
+    try {
+      return Buffer.from(raw.replace(/\s+/g, ''), 'base64').toString('utf8')
+    } catch {
+      return null
+    }
+  }
+
+  return raw
+}
+
+function parseRgLikeQueryArgs(args: string[]): RgLikeSearchQuery {
+  const query: RgLikeSearchQuery = {
+    patterns: [],
+    paths: [],
+    lineNumber: true,
+    withFilename: false,
+    noFilename: false,
+    ignoreCase: false,
+    caseSensitive: false,
+    smartCase: false,
+    fixedStrings: false,
+    wordRegexp: false,
+    maxCount: null,
+    countOnly: false,
+    filesWithMatches: false,
+    filesWithoutMatch: false,
+    onlyMatching: false,
+    includeHidden: false,
+    globs: [],
+  }
+
+  const positionals: string[] = []
+  let stopOptionParsing = false
+
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i]
+    if (!stopOptionParsing && arg === '--') {
+      stopOptionParsing = true
+      continue
+    }
+
+    if (!stopOptionParsing && arg.startsWith('--')) {
+      const consumed = parseRgLikeLongOption(arg, args[i + 1], query)
+      if (consumed) {
+        i += 1
+      }
+      continue
+    }
+
+    if (!stopOptionParsing && arg.startsWith('-') && arg !== '-') {
+      const consumed = parseRgLikeShortOption(arg, args[i + 1], query)
+      if (consumed) {
+        i += 1
+      }
+      continue
+    }
+
+    positionals.push(arg)
+  }
+
+  if (query.patterns.length === 0) {
+    const positionalPattern = positionals.shift()
+    if (!positionalPattern) {
+      throw new Error('Missing search pattern. Usage mirrors rg: PATTERN [PATH ...]')
+    }
+    query.patterns.push(positionalPattern)
+  }
+
+  query.paths = positionals.length > 0 ? positionals : ['.']
+
+  if (query.filesWithMatches && query.filesWithoutMatch) {
+    throw new Error('Cannot combine --files-with-matches and --files-without-match.')
+  }
+
+  return query
+}
+
+function parseRgLikeLongOption(option: string, next: string | undefined, query: RgLikeSearchQuery): boolean {
+  const equalsIndex = option.indexOf('=')
+  const name = equalsIndex >= 0 ? option.slice(0, equalsIndex) : option
+  const inlineValue = equalsIndex >= 0 ? option.slice(equalsIndex + 1) : null
+
+  const readValue = (): string => {
+    const value = inlineValue ?? next
+    if (value === undefined || value === null || value.length === 0) {
+      throw new Error(`Missing value for ${name}`)
+    }
+    return value
+  }
+
+  switch (name) {
+    case '--ignore-case':
+      query.ignoreCase = true
+      return false
+    case '--case-sensitive':
+      query.caseSensitive = true
+      return false
+    case '--smart-case':
+      query.smartCase = true
+      return false
+    case '--fixed-strings':
+      query.fixedStrings = true
+      return false
+    case '--word-regexp':
+      query.wordRegexp = true
+      return false
+    case '--line-number':
+      query.lineNumber = true
+      return false
+    case '--with-filename':
+      query.withFilename = true
+      return false
+    case '--no-filename':
+      query.noFilename = true
+      return false
+    case '--count':
+      query.countOnly = true
+      return false
+    case '--files-with-matches':
+      query.filesWithMatches = true
+      return false
+    case '--files-without-match':
+      query.filesWithoutMatch = true
+      return false
+    case '--only-matching':
+      query.onlyMatching = true
+      return false
+    case '--hidden':
+      query.includeHidden = true
+      return false
+    case '--no-ignore':
+      return false
+    case '--glob': {
+      query.globs.push(readValue())
+      return inlineValue === null
+    }
+    case '--regexp': {
+      query.patterns.push(readValue())
+      return inlineValue === null
+    }
+    case '--max-count': {
+      const value = readValue()
+      const parsed = Number.parseInt(value, 10)
+      if (!Number.isFinite(parsed) || parsed < 0) {
+        throw new Error(`Invalid value for --max-count: ${value}`)
+      }
+      query.maxCount = parsed
+      return inlineValue === null
+    }
+    default:
+      throw new Error(`Unsupported rg option: ${name}`)
+  }
+}
+
+function parseRgLikeShortOption(option: string, next: string | undefined, query: RgLikeSearchQuery): boolean {
+  const cluster = option.slice(1)
+  if (!cluster) {
+    return false
+  }
+
+  const valueFlags = new Set(['m', 'g', 'e'])
+  let consumedNext = false
+
+  for (let i = 0; i < cluster.length; i += 1) {
+    const token = cluster[i]
+
+    if (valueFlags.has(token)) {
+      const inline = cluster.slice(i + 1)
+      const value = inline.length > 0 ? inline : next
+      if (!value) {
+        throw new Error(`Missing value for -${token}`)
+      }
+
+      if (token === 'm') {
+        const parsed = Number.parseInt(value, 10)
+        if (!Number.isFinite(parsed) || parsed < 0) {
+          throw new Error(`Invalid value for -m: ${value}`)
+        }
+        query.maxCount = parsed
+      } else if (token === 'g') {
+        query.globs.push(value)
+      } else if (token === 'e') {
+        query.patterns.push(value)
+      }
+
+      consumedNext = inline.length === 0
+      break
+    }
+
+    switch (token) {
+      case 'i':
+        query.ignoreCase = true
+        break
+      case 's':
+        query.caseSensitive = true
+        break
+      case 'S':
+        query.smartCase = true
+        break
+      case 'F':
+        query.fixedStrings = true
+        break
+      case 'w':
+        query.wordRegexp = true
+        break
+      case 'n':
+        query.lineNumber = true
+        break
+      case 'H':
+        query.withFilename = true
+        break
+      case 'h':
+        query.noFilename = true
+        break
+      case 'c':
+        query.countOnly = true
+        break
+      case 'l':
+        query.filesWithMatches = true
+        break
+      case 'L':
+        query.filesWithoutMatch = true
+        break
+      case 'o':
+        query.onlyMatching = true
+        break
+      default:
+        throw new Error(`Unsupported rg option: -${token}`)
+    }
+  }
+
+  return consumedNext
+}
+
+async function executeRgLikeSearch(
+  cacheRoot: string,
+  query: RgLikeSearchQuery,
+): Promise<RgLikeSearchExecutionResult> {
+  const files = await collectSearchFiles(cacheRoot, query)
+  const compiledPatterns = compileRgLikePatterns(query)
+  const outputLines: string[] = []
+  const multipleFiles = query.withFilename || files.length > 1
+
+  let filesMatched = 0
+  let matchedLines = 0
+  let matchedSegments = 0
+
+  for (const filePath of files) {
+    const relativePath = path.relative(cacheRoot, filePath).replace(/\\/g, '/')
+    const content = await fs.readFile(filePath, 'utf8')
+    const normalized = content.replace(/\r/g, '')
+    const lines = normalized.split('\n')
+    if (lines.length > 0 && lines[lines.length - 1] === '') {
+      lines.pop()
+    }
+
+    let fileMatchedLines = 0
+    let fileMatchedSegments = 0
+    const fileLineOutputs: string[] = []
+
+    for (let index = 0; index < lines.length; index += 1) {
+      const lineText = lines[index] ?? ''
+      const matches = matchLineWithPatterns(lineText, compiledPatterns)
+      if (matches.length === 0) {
+        continue
+      }
+
+      fileMatchedLines += 1
+      fileMatchedSegments += matches.length
+
+      if (!query.countOnly && !query.filesWithMatches && !query.filesWithoutMatch) {
+        if (query.onlyMatching) {
+          for (const matchText of matches) {
+            fileLineOutputs.push(formatSearchOutputLine({
+              filePath: relativePath,
+              includeFilePath: multipleFiles && !query.noFilename,
+              lineNumber: index + 1,
+              includeLineNumber: query.lineNumber,
+              text: matchText,
+            }))
+          }
+        } else {
+          fileLineOutputs.push(formatSearchOutputLine({
+            filePath: relativePath,
+            includeFilePath: multipleFiles && !query.noFilename,
+            lineNumber: index + 1,
+            includeLineNumber: query.lineNumber,
+            text: lineText,
+          }))
+        }
+      }
+
+      if (query.maxCount !== null && fileMatchedLines >= query.maxCount) {
+        break
+      }
+    }
+
+    matchedLines += fileMatchedLines
+    matchedSegments += fileMatchedSegments
+
+    if (query.filesWithoutMatch) {
+      if (fileMatchedLines === 0) {
+        outputLines.push(relativePath)
+      }
+      continue
+    }
+
+    if (fileMatchedLines > 0) {
+      filesMatched += 1
+    }
+
+    if (query.filesWithMatches) {
+      if (fileMatchedLines > 0) {
+        outputLines.push(relativePath)
+      }
+      continue
+    }
+
+    if (query.countOnly) {
+      const includeFilePath = multipleFiles && !query.noFilename
+      outputLines.push(includeFilePath ? `${relativePath}:${fileMatchedLines}` : String(fileMatchedLines))
+      continue
+    }
+
+    outputLines.push(...fileLineOutputs)
+  }
+
+  return {
+    filesSearched: files.length,
+    filesMatched,
+    matchedLines,
+    matchedSegments,
+    outputLines,
+  }
+}
+
+function formatSearchOutputLine(input: {
+  filePath: string
+  includeFilePath: boolean
+  lineNumber: number
+  includeLineNumber: boolean
+  text: string
+}): string {
+  const prefixParts: string[] = []
+  if (input.includeFilePath) {
+    prefixParts.push(input.filePath)
+  }
+  if (input.includeLineNumber) {
+    prefixParts.push(String(input.lineNumber))
+  }
+  if (prefixParts.length === 0) {
+    return input.text
+  }
+  return `${prefixParts.join(':')}:${input.text}`
+}
+
+function matchLineWithPatterns(line: string, patterns: RgLikeCompiledPattern[]): string[] {
+  const collected: string[] = []
+
+  for (const pattern of patterns) {
+    if (!pattern.test.test(line)) {
+      continue
+    }
+
+    pattern.global.lastIndex = 0
+    let match: RegExpExecArray | null = null
+    while ((match = pattern.global.exec(line)) !== null) {
+      collected.push(match[0] ?? '')
+      if ((match[0] ?? '').length === 0) {
+        pattern.global.lastIndex += 1
+      }
+    }
+  }
+
+  return collected
+}
+
+function compileRgLikePatterns(query: RgLikeSearchQuery): RgLikeCompiledPattern[] {
+  return query.patterns.map((pattern) => {
+    const source = query.fixedStrings ? escapeRegExp(pattern) : pattern
+    const wrappedSource = query.wordRegexp ? `\\b(?:${source})\\b` : source
+    const flags = resolveRgLikePatternFlags(pattern, query)
+
+    try {
+      return {
+        test: new RegExp(wrappedSource, flags),
+        global: new RegExp(wrappedSource, `${flags}g`),
+      }
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error)
+      throw new Error(`Invalid search pattern "${pattern}": ${message}`)
+    }
+  })
+}
+
+function resolveRgLikePatternFlags(pattern: string, query: RgLikeSearchQuery): string {
+  if (query.caseSensitive) {
+    return ''
+  }
+  if (query.ignoreCase) {
+    return 'i'
+  }
+  if (query.smartCase) {
+    return /[A-Z]/.test(pattern) ? '' : 'i'
+  }
+  return ''
+}
+
+type CompiledSearchGlob = {
+  raw: string
+  negate: boolean
+  regex: RegExp
+  basenameOnly: boolean
+}
+
+async function collectSearchFiles(cacheRoot: string, query: RgLikeSearchQuery): Promise<string[]> {
+  const compiledGlobs = compileSearchGlobs(query.globs)
+  const files = new Set<string>()
+
+  for (const requested of query.paths) {
+    const normalized = requested === '.' ? '' : requested.replace(/\\/g, '/')
+    const candidate = path.resolve(cacheRoot, normalized)
+    if (!isSubPath(cacheRoot, candidate)) {
+      throw new Error(`Path escapes cache root: ${requested}`)
+    }
+
+    let stats: fsSync.Stats
+    try {
+      stats = await fs.stat(candidate)
+    } catch {
+      throw new Error(`Path not found in cached section: ${requested}`)
+    }
+
+    if (stats.isDirectory()) {
+      await collectFilesFromDirectory(cacheRoot, candidate, query.includeHidden, compiledGlobs, files)
+      continue
+    }
+
+    if (stats.isFile() && shouldIncludeFile(cacheRoot, candidate, query.includeHidden, compiledGlobs)) {
+      files.add(candidate)
+    }
+  }
+
+  return Array.from(files).sort((left, right) => left.localeCompare(right))
+}
+
+async function collectFilesFromDirectory(
+  cacheRoot: string,
+  directory: string,
+  includeHidden: boolean,
+  globs: CompiledSearchGlob[],
+  files: Set<string>,
+): Promise<void> {
+  const entries = await fs.readdir(directory, { withFileTypes: true })
+
+  for (const entry of entries) {
+    if (entry.name === PROJECT_ARCHIVE_DIR_NAME) {
+      continue
+    }
+
+    if (!includeHidden && entry.name.startsWith('.')) {
+      continue
+    }
+
+    const absolute = path.join(directory, entry.name)
+    if (entry.isDirectory()) {
+      await collectFilesFromDirectory(cacheRoot, absolute, includeHidden, globs, files)
+      continue
+    }
+
+    if (entry.isFile() && shouldIncludeFile(cacheRoot, absolute, includeHidden, globs)) {
+      files.add(absolute)
+    }
+  }
+}
+
+function shouldIncludeFile(
+  cacheRoot: string,
+  filePath: string,
+  includeHidden: boolean,
+  globs: CompiledSearchGlob[],
+): boolean {
+  const relative = path.relative(cacheRoot, filePath).replace(/\\/g, '/')
+  if (!includeHidden && relative.split('/').some((segment) => segment.startsWith('.'))) {
+    return false
+  }
+
+  return matchesSearchGlobs(relative, globs)
+}
+
+function compileSearchGlobs(globs: string[]): CompiledSearchGlob[] {
+  return globs
+    .map((raw) => raw.trim())
+    .filter((raw) => raw.length > 0)
+    .map((raw) => {
+      const negate = raw.startsWith('!')
+      const normalized = (negate ? raw.slice(1) : raw).replace(/\\/g, '/')
+      const basenameOnly = !normalized.includes('/')
+
+      return {
+        raw,
+        negate,
+        regex: globToRegExp(normalized),
+        basenameOnly,
+      }
+    })
+}
+
+function matchesSearchGlobs(relativePath: string, globs: CompiledSearchGlob[]): boolean {
+  if (globs.length === 0) {
+    return true
+  }
+
+  const includeGlobs = globs.filter((glob) => !glob.negate)
+  const excludeGlobs = globs.filter((glob) => glob.negate)
+  const fileName = relativePath.split('/').pop() ?? relativePath
+
+  const matchesGlob = (glob: CompiledSearchGlob): boolean => {
+    if (glob.basenameOnly) {
+      return glob.regex.test(fileName)
+    }
+    return glob.regex.test(relativePath)
+  }
+
+  if (includeGlobs.length > 0 && !includeGlobs.some((glob) => matchesGlob(glob))) {
+    return false
+  }
+
+  if (excludeGlobs.some((glob) => matchesGlob(glob))) {
+    return false
+  }
+
+  return true
+}
+
+function globToRegExp(glob: string): RegExp {
+  let index = 0
+  let source = '^'
+
+  while (index < glob.length) {
+    const char = glob[index]
+
+    if (char === '*') {
+      const next = glob[index + 1]
+      if (next === '*') {
+        source += '.*'
+        index += 2
+        continue
+      }
+      source += '[^/]*'
+      index += 1
+      continue
+    }
+
+    if (char === '?') {
+      source += '[^/]'
+      index += 1
+      continue
+    }
+
+    source += escapeRegExp(char)
+    index += 1
+  }
+
+  source += '$'
+  return new RegExp(source)
+}
+
 type ProjectVersionedFileSpec = {
   parts: string[]
   base: string