@foundation0/git 1.2.5 → 1.3.1

package/src/platform/gitea-adapter.ts

@@ -1,448 +1,460 @@
-import type { GitServiceFeature } from '../git-service-feature-spec.generated'
-import { buildGitApiMockResponse, type GitApiMockResponse } from '../spec-mock'
-import { getDefaultGiteaRule, getExactGiteaRule, type GiteaRouteRule } from './gitea-rules'
-
-type FlagValue = string | boolean | undefined
-
-const DEFAULT_HTTP_METHODS = new Set(['GET', 'POST', 'PUT', 'PATCH', 'DELETE'])
-const READ_OPERATION_ACTIONS = new Set([
-  'view',
-  'get',
-  'list',
-  'status',
-  'exists',
-  'search',
-  'stats',
-  'verify',
-  'check',
-])
-const DELETE_OPERATION_ACTIONS = new Set([
-  'delete',
-  'remove',
-  'unarchive',
-  'unstar',
-  'unwatch',
-  'unpin',
-  'unlink',
-  'unsubscribe',
-  'unfollow',
-  'deprovision',
-  'expire',
-])
-const PATCH_OPERATION_ACTIONS = new Set([
-  'edit',
-  'update',
-  'close',
-  'open',
-  'pin',
-  'reopen',
-  'rename',
-  'set',
-  'transfer',
-  'enable',
-  'disable',
-  'lock',
-  'unlock',
-  'set-default',
-  'follow',
-  'watch',
-  'subscribe',
-  'archive',
-  'merge',
-  'approve',
-])
-const POST_OPERATION_ACTIONS = new Set([
-  'create',
-  'add',
-  'run',
-  'dispatch',
-  'comment',
-  'fork',
-  'sync',
-  'set-upstream',
-  'upload',
-  'install',
-  'request',
-  'approve',
-  'create-team',
-  'apply',
-  'start',
-  'stop',
-  'rerun',
-  'reset',
-])
-
-const normalizeHttpMethod = (value?: string): string | undefined => {
-  if (!value || typeof value !== 'string') {
-    return undefined
-  }
-
-  const method = value.trim().toUpperCase()
-  return DEFAULT_HTTP_METHODS.has(method) ? method : undefined
-}
-
-const inferFallbackMethod = (featurePath: string[]): string => {
-  if (featurePath.length === 0) {
-    return 'GET'
-  }
-
-  const last = featurePath[featurePath.length - 1].toLowerCase()
-
-  if (READ_OPERATION_ACTIONS.has(last)) {
-    return 'GET'
-  }
-
-  if (DELETE_OPERATION_ACTIONS.has(last)) {
-    return 'DELETE'
-  }
-
-  if (PATCH_OPERATION_ACTIONS.has(last)) {
-    return 'PATCH'
-  }
-
-  if (POST_OPERATION_ACTIONS.has(last)) {
-    return 'POST'
-  }
-
-  if (featurePath.length === 1) {
-    return 'GET'
-  }
-
-  return 'POST'
-}
-
-export interface GitApiFeatureContext {
-  feature: GitServiceFeature
-  args?: string[]
-  flagValues?: Record<string, FlagValue>
-  method?: string
-}
-
-export interface GitApiFeatureMapping {
-  platform: 'GITEA'
-  featurePath: string[]
-  mappedPath: string[]
-  method: string
-  query: string[]
-  headers: string[]
-  apiBase: string
-  swaggerPath: string
-  mapped: boolean
-  apiVersion?: string
-  reason?: string
-}
-
-export interface GiteaSwagger {
-  paths?: Record<string, Record<string, unknown>>
-}
-
-export interface GiteaPlatformAdapterOptions {
-  giteaHost: string
-  giteaToken?: string
-  giteaSwaggerPath?: string
-  apiVersion?: string
-  swaggerSpec?: GiteaSwagger
-}
-
-export class GiteaPlatformAdapter {
-  private readonly apiBase: string
-  private readonly apiVersion?: string
-  private readonly token?: string
-  private readonly swaggerUrl: string
-  private readonly swaggerSpec?: GiteaSwagger
-
-  public constructor(options: GiteaPlatformAdapterOptions) {
-    this.apiBase = this.buildApiBase(options.giteaHost)
-    this.apiVersion = options.apiVersion
-    this.token = options.giteaToken
-    this.swaggerUrl = this.buildSwaggerUrl(options.giteaHost, options.giteaSwaggerPath)
-    this.swaggerSpec = options.swaggerSpec
-  }
-
-  public get platform() {
-    return 'GITEA' as const
-  }
-
-  public async mapFeature(context: GitApiFeatureContext): Promise<GitApiFeatureMapping> {
-    const args = context.args ?? []
-    const flagValues = context.flagValues ?? {}
-    const matchedRule = getExactGiteaRule(context.feature.path) ?? getDefaultGiteaRule(context.feature.path)
-
-    if (!matchedRule) {
-      return this.mapFallback(
-        context.feature.path,
-        args,
-        this.mapFlags(flagValues, context.feature.path),
-        context.method,
-      )
-    }
-
-    return this.mapRule(matchedRule, args, flagValues, context.method)
-  }
-
-  public async mapFeatureResponse(context: GitApiFeatureContext): Promise<GitApiMockResponse> {
-    const mapping = await this.mapFeature(context)
-    return buildGitApiMockResponse({
-      path: mapping.mappedPath,
-      method: mapping.method,
-      query: mapping.query,
-      headers: mapping.headers,
-      apiBase: mapping.apiBase,
-      apiVersion: mapping.apiVersion,
-    })
-  }
-
-  public async validateFeature(context: GitApiFeatureContext): Promise<GitApiFeatureMapping> {
-    const mapping = await this.mapFeature(context)
-    const spec = await this.fetchSwaggerSpec()
-    const pathKey = `/${mapping.mappedPath.join('/')}`
-    const methods = spec.paths?.[pathKey]
-
-    if (!methods) {
-      return {
-        ...mapping,
-        mapped: false,
-        reason: `Swagger endpoint not found: ${pathKey}`,
-      }
-    }
-
-    const hasMethod = Object.prototype.hasOwnProperty.call(methods, mapping.method.toLowerCase())
-
-    const reason = hasMethod ? undefined : `Swagger method mismatch for ${pathKey}: ${mapping.method}`
-
-    return {
-      ...mapping,
-      mapped: hasMethod,
-      reason,
-    }
-  }
-
-  public async fetchSwaggerSpec(): Promise<GiteaSwagger> {
-    if (this.swaggerSpec) {
-      return this.swaggerSpec
-    }
-
-    const response = await fetch(this.swaggerUrl, {
-      headers: this.token ? { Authorization: `token ${this.token}` } : undefined,
-    })
-
-    if (!response.ok) {
-      throw new Error(`Could not fetch swagger spec from ${this.swaggerUrl}: ${response.status}`)
-    }
-
-    const payload = (await response.json()) as GiteaSwagger
-    return payload
-  }
-
-  private mapRule(
-    rule: GiteaRouteRule,
-    args: string[] = [],
-    flagValues: Record<string, FlagValue> = {},
-    contextMethod?: string,
-  ): GitApiFeatureMapping {
-    const pathSegments = this.mapSwaggerPath(rule.swaggerPath, args, this.shouldUseContentsRoot(rule, args))
-    const query = this.mapFeatureQuery(rule, flagValues)
-    const headers = this.mapHeaders()
-    const method = normalizeHttpMethod(contextMethod) ?? rule.method
-
-    return {
-      platform: this.platform,
-      featurePath: rule.featurePath,
-      mappedPath: pathSegments,
-      method,
-      query,
-      headers,
-      apiBase: this.apiBase,
-      swaggerPath: rule.swaggerPath,
-      mapped: true,
-      apiVersion: this.apiVersion,
-      reason: rule.notes,
-    }
-  }
-
-  private mapFallback(
-    featurePath: string[],
-    args: string[],
-    flagValues: string[],
-    contextMethod?: string,
-  ): GitApiFeatureMapping {
-    const { owner, repo, tail } = this.extractOwnerRepoArgs(args)
-    const mappedPath = this.sanitizePath(['repos', owner, repo, ...featurePath, ...tail])
-    const headers = this.mapHeaders()
-    const method = normalizeHttpMethod(contextMethod) ?? inferFallbackMethod(featurePath)
-
-    return {
-      platform: this.platform,
-      featurePath,
-      mappedPath,
-      method,
-      query: flagValues,
-      headers,
-      apiBase: this.apiBase,
-      swaggerPath: `/${mappedPath.join('/')}`,
-      mapped: false,
-      apiVersion: this.apiVersion,
-      reason: `No direct mapping for feature: ${featurePath.join(' ')}`,
-    }
-  }
-
-  private mapFeatureQuery(rule: GiteaRouteRule, flagValues: Record<string, FlagValue>): string[] {
-    const query = [...(rule.staticQuery ?? [])]
-    query.push(...this.mapFlags(flagValues, rule.featurePath))
-    return query
-  }
-
-  private mapFlags(flagValues: Record<string, FlagValue>, featurePath: string[]): string[] {
-    const query: string[] = []
-
-    if (featurePath[0] === 'search') {
-      if (featurePath[1] === 'prs') {
-        query.push('type=pr')
-      }
-
-      if (featurePath[1] === 'issues') {
-        query.push('type=issue')
-      }
-    }
-
-    for (const [flagName, value] of Object.entries(flagValues)) {
-      if (value === undefined) {
-        continue
-      }
-
-      const normalized = this.normalizeFlagKey(flagName)
-      if (typeof value === 'boolean') {
-        query.push(`${normalized}=${value}`)
-        continue
-      }
-
-      query.push(`${normalized}=${value}`)
-    }
-
-    return query
-  }
-
-  private mapHeaders(): string[] {
-    const headers = ['Accept: application/json']
-    if (this.token) {
-      headers.push(`Authorization: token ${this.token}`)
-    }
-
-    return headers
-  }
-
-  private shouldUseContentsRoot(rule: GiteaRouteRule, args: string[]): boolean {
-    if (rule.swaggerPath !== '/repos/{owner}/{repo}/contents/{filepath}') {
-      return false
-    }
-
-    if (rule.featurePath[0] !== 'contents' || rule.featurePath[1] !== 'list') {
-      return false
-    }
-
-    const [, , filePath] = args
-    if (filePath === undefined || filePath === '') {
-      return true
-    }
-
-    return String(filePath).trim() === ''
-  }
-
-  private mapSwaggerPath(swaggerPath: string, args: string[] = [], trimContentsFilepath = false): string[] {
-    const values = this.normalizeSwaggerPathArgs(swaggerPath, args)
-    const parts = this.sanitizePath(swaggerPath.split('/'))
-    let fillIndex = 0
-
-    const mapped = parts.flatMap((segment) => {
-      if (!segment.startsWith('{') || !segment.endsWith('}')) {
-        return [segment]
-      }
-
-      const value = values[fillIndex]
-      fillIndex += 1
-
-      const isAutoFilledPlaceholder = /^\\{v\\d+\\}$/.test(value)
-
-      if (trimContentsFilepath && segment === '{filepath}' && (!value || value.trim() === '' || isAutoFilledPlaceholder)) {
-        return []
-      }
-
-      return [value ? value : segment]
-    })
-
-    return this.sanitizePath(mapped)
-  }
-
-  private normalizeSwaggerPathArgs(swaggerPath: string, args: string[]): string[] {
-    const values = [...args]
-    const segments = swaggerPath.split('/').filter((segment) => segment.startsWith('{') && segment.endsWith('}'))
-    const placeholderCount = segments.length
-
-    if (placeholderCount <= 1) {
-      return values
-    }
-
-    if (!values[0]) {
-      return values
-    }
-
-    if (values[0].includes('/') && placeholderCount >= 2) {
-      const split = values[0].split('/')
-      if (split.length >= 2 && split[0] && split[1]) {
-        values[0] = split[0]
-        values.splice(1, 0, split[1])
-      }
-    }
-
-    if (placeholderCount >= 2 && values.length >= 2) {
-      return values
-    }
-
-    while (values.length < placeholderCount) {
-      values.push(`{v${values.length}}`)
-    }
-
-    return values
-  }
-
-  private extractOwnerRepoArgs(args: string[]): { owner: string; repo: string; tail: string[] } {
-    if (!args.length) {
-      return { owner: '{owner}', repo: '{repo}', tail: [] }
-    }
-
-    if (args.length >= 2) {
-      return { owner: args[0], repo: args[1], tail: args.slice(2) }
-    }
-
-    const arg = args[0]
-    const split = arg.split('/')
-    if (split.length === 2 && split[0] && split[1]) {
-      return { owner: split[0], repo: split[1], tail: [] }
-    }
-
-    return { owner: '{owner}', repo: '{repo}', tail: args }
-  }
-
-  private buildApiBase(host: string): string {
-    const sanitizedHost = host.replace(/\/$/, '')
-    if (sanitizedHost.endsWith('/api/v1')) {
-      return sanitizedHost
-    }
-
-    return `${sanitizedHost}/api/v1`
-  }
-
-  private buildSwaggerUrl(host: string, path = '/swagger.v1.json'): string {
-    const base = this.buildApiBase(host).replace(/\/api\/v1$/, '')
-    const swaggerPath = path.startsWith('/') ? path : `/${path}`
-    return `${base}${swaggerPath}`
-  }
-
-  private sanitizePath(parts: string[]): string[] {
-    return parts.filter((part) => part.length > 0)
-  }
-
-  private normalizeFlagKey(flag: string): string {
-    return flag.replace(/^--/, '').trim()
-  }
-}
+import type { GitServiceFeature } from '../git-service-feature-spec.generated'
+import { buildGitApiMockResponse, type GitApiMockResponse } from '../spec-mock'
+import { getDefaultGiteaRule, getExactGiteaRule, type GiteaRouteRule } from './gitea-rules'
+
+type FlagValue = string | boolean | undefined
+
+const DEFAULT_HTTP_METHODS = new Set(['GET', 'POST', 'PUT', 'PATCH', 'DELETE'])
+const READ_OPERATION_ACTIONS = new Set([
+  'view',
+  'get',
+  'list',
+  'status',
+  'exists',
+  'search',
+  'stats',
+  'verify',
+  'check',
+])
+const DELETE_OPERATION_ACTIONS = new Set([
+  'delete',
+  'remove',
+  'unarchive',
+  'unstar',
+  'unwatch',
+  'unpin',
+  'unlink',
+  'unsubscribe',
+  'unfollow',
+  'deprovision',
+  'expire',
+])
+const PATCH_OPERATION_ACTIONS = new Set([
+  'edit',
+  'update',
+  'close',
+  'open',
+  'pin',
+  'reopen',
+  'rename',
+  'set',
+  'transfer',
+  'enable',
+  'disable',
+  'lock',
+  'unlock',
+  'set-default',
+  'follow',
+  'watch',
+  'subscribe',
+  'archive',
+  'merge',
+  'approve',
+])
+const POST_OPERATION_ACTIONS = new Set([
+  'create',
+  'add',
+  'run',
+  'dispatch',
+  'comment',
+  'fork',
+  'sync',
+  'set-upstream',
+  'upload',
+  'install',
+  'request',
+  'approve',
+  'create-team',
+  'apply',
+  'start',
+  'stop',
+  'rerun',
+  'reset',
+])
+
+const normalizeHttpMethod = (value?: string): string | undefined => {
+  if (!value || typeof value !== 'string') {
+    return undefined
+  }
+
+  const method = value.trim().toUpperCase()
+  return DEFAULT_HTTP_METHODS.has(method) ? method : undefined
+}
+
+const inferFallbackMethod = (featurePath: string[]): string => {
+  if (featurePath.length === 0) {
+    return 'GET'
+  }
+
+  const last = featurePath[featurePath.length - 1].toLowerCase()
+
+  if (READ_OPERATION_ACTIONS.has(last)) {
+    return 'GET'
+  }
+
+  if (DELETE_OPERATION_ACTIONS.has(last)) {
+    return 'DELETE'
+  }
+
+  if (PATCH_OPERATION_ACTIONS.has(last)) {
+    return 'PATCH'
+  }
+
+  if (POST_OPERATION_ACTIONS.has(last)) {
+    return 'POST'
+  }
+
+  if (featurePath.length === 1) {
+    return 'GET'
+  }
+
+  return 'POST'
+}
+
+export interface GitApiFeatureContext {
+  feature: GitServiceFeature
+  args?: string[]
+  flagValues?: Record<string, FlagValue>
+  method?: string
+}
+
+export interface GitApiFeatureMapping {
+  platform: 'GITEA'
+  featurePath: string[]
+  mappedPath: string[]
+  method: string
+  query: string[]
+  headers: string[]
+  apiBase: string
+  swaggerPath: string
+  mapped: boolean
+  apiVersion?: string
+  reason?: string
+}
+
+export interface GiteaSwagger {
+  paths?: Record<string, Record<string, unknown>>
+}
+
+export interface GiteaPlatformAdapterOptions {
+  giteaHost: string
+  giteaToken?: string
+  giteaSwaggerPath?: string
+  apiVersion?: string
+  swaggerSpec?: GiteaSwagger
+}
+
+export class GiteaPlatformAdapter {
+  private readonly apiBase: string
+  private readonly apiVersion?: string
+  private readonly token?: string
+  private readonly swaggerUrl: string
+  private readonly swaggerSpec?: GiteaSwagger
+
+  public constructor(options: GiteaPlatformAdapterOptions) {
+    this.apiBase = this.buildApiBase(options.giteaHost)
+    this.apiVersion = options.apiVersion
+    this.token = options.giteaToken
+    this.swaggerUrl = this.buildSwaggerUrl(options.giteaHost, options.giteaSwaggerPath)
+    this.swaggerSpec = options.swaggerSpec
+  }
+
+  public get platform() {
+    return 'GITEA' as const
+  }
+
+  public async mapFeature(context: GitApiFeatureContext): Promise<GitApiFeatureMapping> {
+    const args = context.args ?? []
+    const flagValues = context.flagValues ?? {}
+    const matchedRule = getExactGiteaRule(context.feature.path) ?? getDefaultGiteaRule(context.feature.path)
+
+    if (!matchedRule) {
+      return this.mapFallback(
+        context.feature.path,
+        args,
+        this.mapFlags(flagValues, context.feature.path),
+        context.method,
+      )
+    }
+
+    return this.mapRule(matchedRule, args, flagValues, context.method)
+  }
+
+  public async mapFeatureResponse(context: GitApiFeatureContext): Promise<GitApiMockResponse> {
+    const mapping = await this.mapFeature(context)
+    return buildGitApiMockResponse({
+      path: mapping.mappedPath,
+      method: mapping.method,
+      query: mapping.query,
+      headers: mapping.headers,
+      apiBase: mapping.apiBase,
+      apiVersion: mapping.apiVersion,
+    })
+  }
+
+  public async validateFeature(context: GitApiFeatureContext): Promise<GitApiFeatureMapping> {
+    const mapping = await this.mapFeature(context)
+    const spec = await this.fetchSwaggerSpec()
+    const pathKey = `/${mapping.mappedPath.join('/')}`
+    const methods = spec.paths?.[pathKey]
+
+    if (!methods) {
+      return {
+        ...mapping,
+        mapped: false,
+        reason: `Swagger endpoint not found: ${pathKey}`,
+      }
+    }
+
+    const hasMethod = Object.prototype.hasOwnProperty.call(methods, mapping.method.toLowerCase())
+
+    const reason = hasMethod ? undefined : `Swagger method mismatch for ${pathKey}: ${mapping.method}`
+
+    return {
+      ...mapping,
+      mapped: hasMethod,
+      reason,
+    }
+  }
+
+  public async fetchSwaggerSpec(): Promise<GiteaSwagger> {
+    if (this.swaggerSpec) {
+      return this.swaggerSpec
+    }
+
+    const response = await fetch(this.swaggerUrl, {
+      headers: this.token ? { Authorization: `token ${this.token}` } : undefined,
+    })
+
+    if (!response.ok) {
+      throw new Error(`Could not fetch swagger spec from ${this.swaggerUrl}: ${response.status}`)
+    }
+
+    const payload = (await response.json()) as GiteaSwagger
+    return payload
+  }
+
+  private mapRule(
+    rule: GiteaRouteRule,
+    args: string[] = [],
+    flagValues: Record<string, FlagValue> = {},
+    contextMethod?: string,
+  ): GitApiFeatureMapping {
+    const pathSegments = this.mapSwaggerPath(rule.swaggerPath, args, this.shouldUseContentsRoot(rule, args))
+    const query = this.mapFeatureQuery(rule, flagValues)
+    const headers = this.mapHeaders()
+    const method = normalizeHttpMethod(contextMethod) ?? rule.method
+
+    return {
+      platform: this.platform,
+      featurePath: rule.featurePath,
+      mappedPath: pathSegments,
+      method,
+      query,
+      headers,
+      apiBase: this.apiBase,
+      swaggerPath: rule.swaggerPath,
+      mapped: true,
+      apiVersion: this.apiVersion,
+      reason: rule.notes,
+    }
+  }
+
+  private mapFallback(
+    featurePath: string[],
+    args: string[],
+    flagValues: string[],
+    contextMethod?: string,
+  ): GitApiFeatureMapping {
+    const { owner, repo, tail } = this.extractOwnerRepoArgs(args)
+    const mappedPath = this.sanitizePath(['repos', owner, repo, ...featurePath, ...tail])
+    const headers = this.mapHeaders()
+    const method = normalizeHttpMethod(contextMethod) ?? inferFallbackMethod(featurePath)
+
+    return {
+      platform: this.platform,
+      featurePath,
+      mappedPath,
+      method,
+      query: flagValues,
+      headers,
+      apiBase: this.apiBase,
+      swaggerPath: `/${mappedPath.join('/')}`,
+      mapped: false,
+      apiVersion: this.apiVersion,
+      reason: `No direct mapping for feature: ${featurePath.join(' ')}`,
+    }
+  }
+
+  private mapFeatureQuery(rule: GiteaRouteRule, flagValues: Record<string, FlagValue>): string[] {
+    const query = [...(rule.staticQuery ?? [])]
+    query.push(...this.mapFlags(flagValues, rule.featurePath))
+    return query
+  }
+
+  private mapFlags(flagValues: Record<string, FlagValue>, featurePath: string[]): string[] {
+    const query: string[] = []
+
+    if (featurePath[0] === 'search') {
+      if (featurePath[1] === 'prs') {
+        query.push('type=pr')
+      }
+
+      if (featurePath[1] === 'issues') {
+        query.push('type=issue')
+      }
+    }
+
+    for (const [flagName, value] of Object.entries(flagValues)) {
+      if (value === undefined) {
+        continue
+      }
+
+      const normalized = this.normalizeFlagKey(flagName)
+      if (typeof value === 'boolean') {
+        query.push(`${normalized}=${value}`)
+        continue
+      }
+
+      query.push(`${normalized}=${value}`)
+    }
+
+    return query
+  }
+
+  private mapHeaders(): string[] {
+    const headers = ['Accept: application/json']
+    if (this.token) {
+      headers.push(`Authorization: token ${this.token}`)
+    }
+
+    return headers
+  }
+
+  private shouldUseContentsRoot(rule: GiteaRouteRule, args: string[]): boolean {
+    if (rule.swaggerPath !== '/repos/{owner}/{repo}/contents/{filepath}') {
+      return false
+    }
+
+    if (rule.featurePath[0] !== 'contents' || rule.featurePath[1] !== 'list') {
+      return false
+    }
+
+    const [, , filePath] = args
+    if (filePath === undefined || filePath === '') {
+      return true
+    }
+
+    return String(filePath).trim() === ''
+  }
+
+  private mapSwaggerPath(swaggerPath: string, args: string[] = [], trimContentsFilepath = false): string[] {
+    const values = this.normalizeSwaggerPathArgs(swaggerPath, args)
+    const parts = this.sanitizePath(swaggerPath.split('/'))
+    let fillIndex = 0
+
+    const mapped = parts.flatMap((segment) => {
+      if (!segment.startsWith('{') || !segment.endsWith('}')) {
+        return [segment]
+      }
+
+      const value = values[fillIndex]
+      fillIndex += 1
+
+      const isAutoFilledPlaceholder = /^\\{v\\d+\\}$/.test(value)
+
+      if (trimContentsFilepath && segment === '{filepath}' && (!value || value.trim() === '' || isAutoFilledPlaceholder)) {
+        return []
+      }
+
+      return [value ? value : segment]
+    })
+
+    return this.sanitizePath(mapped)
+  }
+
+  private normalizeSwaggerPathArgs(swaggerPath: string, args: string[]): string[] {
+    const values = [...args]
+    const segments = swaggerPath.split('/').filter((segment) => segment.startsWith('{') && segment.endsWith('}'))
+    const placeholderCount = segments.length
+
+    if (placeholderCount <= 1) {
+      return values
+    }
+
+    if (!values[0]) {
+      return values
+    }
+
+    const isRepoScoped =
+      segments.length >= 2 &&
+      segments[0] === '{owner}' &&
+      segments[1] === '{repo}'
+
+    if (values[0].includes('/') && placeholderCount >= 2) {
+      const split = values[0].split('/')
+      if (split.length >= 2 && split[0] && split[1]) {
+        values[0] = split[0]
+        values.splice(1, 0, split[1])
+      }
+    }
+
+    // For repo-scoped commands, allow passing the "rest" of the arguments (number/id/path) without
+    // explicitly providing owner/repo. The git-service layer can hydrate {owner}/{repo} from defaults.
+    //
+    // Example: swaggerPath "/repos/{owner}/{repo}/pulls/{number}" with args ["123"] should map to:
+    //   owner="{owner}" repo="{repo}" number="123"
+    //
+    // We achieve this by left-padding args with empty strings so mapSwaggerPath leaves placeholders intact.
+    if (isRepoScoped && placeholderCount > 2 && values.length === 1 && !values[0].includes('/')) {
+      values.unshift('', '')
+    }
+
+    if (placeholderCount >= 2 && values.length >= 2) {
+      return values
+    }
+
+    return values
+  }
+
+  private extractOwnerRepoArgs(args: string[]): { owner: string; repo: string; tail: string[] } {
+    if (!args.length) {
+      return { owner: '{owner}', repo: '{repo}', tail: [] }
+    }
+
+    if (args.length >= 2) {
+      return { owner: args[0], repo: args[1], tail: args.slice(2) }
+    }
+
+    const arg = args[0]
+    const split = arg.split('/')
+    if (split.length === 2 && split[0] && split[1]) {
+      return { owner: split[0], repo: split[1], tail: [] }
+    }
+
+    return { owner: '{owner}', repo: '{repo}', tail: args }
+  }
+
+  private buildApiBase(host: string): string {
+    const sanitizedHost = host.replace(/\/$/, '')
+    if (sanitizedHost.endsWith('/api/v1')) {
+      return sanitizedHost
+    }
+
+    return `${sanitizedHost}/api/v1`
+  }
+
+  private buildSwaggerUrl(host: string, path = '/swagger.v1.json'): string {
+    const base = this.buildApiBase(host).replace(/\/api\/v1$/, '')
+    const swaggerPath = path.startsWith('/') ? path : `/${path}`
+    return `${base}${swaggerPath}`
+  }
+
+  private sanitizePath(parts: string[]): string[] {
+    return parts.filter((part) => part.length > 0)
+  }
+
+  private normalizeFlagKey(flag: string): string {
+    return flag.replace(/^--/, '').trim()
+  }
+}