@foundation0/git 1.0.0 → 1.2.1

package/src/label-management.ts

@@ -0,0 +1,587 @@
+import type { GitServiceApi, GitServiceApiExecutionResult, GitServiceApiMethod } from './git-service-api'
+
+const LABEL_LIST_PAGE_SIZE = 100
+const MAX_LABEL_LIST_PAGES = 100
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value)
+
+const toTrimmedString = (value: unknown): string | null => {
+  if (typeof value !== 'string') {
+    return null
+  }
+  const trimmed = value.trim()
+  return trimmed.length > 0 ? trimmed : null
+}
+
+const toPositiveInteger = (value: unknown): number | null => {
+  const candidate = Number(value)
+  if (!Number.isFinite(candidate) || candidate <= 0 || Math.floor(candidate) !== candidate) {
+    return null
+  }
+  return candidate
+}
+
+const toBoolean = (value: unknown, fallback: boolean): boolean => {
+  if (typeof value === 'boolean') {
+    return value
+  }
+
+  if (typeof value === 'string') {
+    const normalized = value.trim().toLowerCase()
+    if (normalized === 'true' || normalized === '1' || normalized === 'yes') {
+      return true
+    }
+    if (normalized === 'false' || normalized === '0' || normalized === 'no') {
+      return false
+    }
+  }
+
+  return fallback
+}
+
+const toQueryRecord = (raw: unknown): Record<string, string | number | boolean> => {
+  if (!isRecord(raw)) {
+    return {}
+  }
+
+  const query: Record<string, string | number | boolean> = {}
+  for (const [key, value] of Object.entries(raw)) {
+    if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+      query[key] = value
+    }
+  }
+  return query
+}
+
+type ScopeArgs = {
+  owner?: string
+  repo?: string
+  options: Record<string, unknown>
+}
+
+type NamedScopeArgs = ScopeArgs & {
+  name: string
+}
+
+const normalizeScopeArgs = (
+  ownerOrOptions?: unknown,
+  repoOrOptions?: unknown,
+  maybeOptions?: unknown,
+): ScopeArgs => {
+  const options: Record<string, unknown> = {}
+  let owner: string | undefined
+  let repo: string | undefined
+
+  const absorb = (value: unknown): string | undefined => {
+    if (value === undefined || value === null) {
+      return undefined
+    }
+
+    if (isRecord(value)) {
+      Object.assign(options, value)
+      return undefined
+    }
+
+    const asText = String(value).trim()
+    return asText.length > 0 ? asText : undefined
+  }
+
+  owner = absorb(ownerOrOptions)
+  repo = absorb(repoOrOptions)
+
+  if (isRecord(maybeOptions)) {
+    Object.assign(options, maybeOptions)
+  }
+
+  return {
+    ...(owner ? { owner } : {}),
+    ...(repo ? { repo } : {}),
+    options,
+  }
+}
+
+const normalizeNamedScopeArgs = (
+  labelName: unknown,
+  ownerOrOptions?: unknown,
+  repoOrOptions?: unknown,
+  maybeOptions?: unknown,
+): NamedScopeArgs => {
+  const name = toTrimmedString(labelName)
+  if (!name) {
+    throw new Error('Label name is required.')
+  }
+
+  return {
+    name,
+    ...normalizeScopeArgs(ownerOrOptions, repoOrOptions, maybeOptions),
+  }
+}
+
+export interface GitLabelManagementDefaults {
+  defaultOwner?: string
+  defaultRepo?: string
+}
+
+const resolveOwnerRepo = (
+  scope: Pick<ScopeArgs, 'owner' | 'repo'>,
+  defaults: GitLabelManagementDefaults,
+): { owner: string; repo: string } => {
+  const owner = scope.owner ?? defaults.defaultOwner
+  const repo = scope.repo ?? defaults.defaultRepo
+
+  if (!owner || !repo) {
+    throw new Error(
+      'Owner/repo is required. Pass owner and repo args or set defaultOwner/defaultRepo when creating the API.',
+    )
+  }
+
+  return { owner, repo }
+}
+
+const resolveLabelNamespace = (api: GitServiceApi): GitServiceApi => {
+  const direct = (api as Record<string, unknown>).label
+  if (isRecord(direct)) {
+    return direct as GitServiceApi
+  }
+
+  const repoNamespace = (api as Record<string, unknown>).repo
+  if (isRecord(repoNamespace)) {
+    const repoLabel = (repoNamespace as Record<string, unknown>).label
+    if (isRecord(repoLabel)) {
+      return repoLabel as GitServiceApi
+    }
+  }
+
+  throw new Error('Git service API does not expose label namespace')
+}
+
+type LabelCrudFeature = 'list' | 'create' | 'edit' | 'delete'
+
+const resolveLabelMethod = (api: GitServiceApi, feature: LabelCrudFeature): GitServiceApiMethod => {
+  const labelNamespace = resolveLabelNamespace(api)
+  const method = (labelNamespace as Record<string, unknown>)[feature]
+  if (typeof method !== 'function') {
+    throw new Error(`Git service API does not expose label.${feature}`)
+  }
+  return method as GitServiceApiMethod
+}
+
+const executeLabelCall = async (
+  method: GitServiceApiMethod,
+  owner: string,
+  repo: string,
+  pathArgs: unknown[] = [],
+  options: Record<string, unknown> = {},
+): Promise<GitServiceApiExecutionResult<unknown>> => {
+  const invocationArgs: unknown[] = [owner, repo, ...pathArgs]
+  if (Object.keys(options).length > 0) {
+    invocationArgs.push(options)
+  }
+  return method(...invocationArgs) as Promise<GitServiceApiExecutionResult<unknown>>
+}
+
+const ensureOk = (result: GitServiceApiExecutionResult<unknown>, context: string): void => {
+  if (!result.ok) {
+    throw new Error(`${context}: status=${result.status} url=${result.request.url}`)
+  }
+}
+
+export interface GitRepositoryLabel {
+  id: number | null
+  name: string
+  color: string | null
+  description: string | null
+  exclusive: boolean | null
+  url: string | null
+  raw: Record<string, unknown>
+}
+
+const normalizeRepositoryLabel = (raw: unknown): GitRepositoryLabel | null => {
+  if (!isRecord(raw)) {
+    return null
+  }
+
+  const name = toTrimmedString(raw.name)
+  if (!name) {
+    return null
+  }
+
+  const id = toPositiveInteger(raw.id ?? raw.number ?? raw.ID)
+  const color = toTrimmedString(raw.color)
+  const description = toTrimmedString(raw.description)
+  const url = toTrimmedString(raw.url ?? raw.html_url)
+  const exclusive = typeof raw.exclusive === 'boolean'
+    ? raw.exclusive
+    : typeof raw.is_exclusive === 'boolean'
+      ? raw.is_exclusive
+      : null
+
+  return {
+    id,
+    name,
+    color,
+    description,
+    exclusive,
+    url,
+    raw: { ...raw },
+  }
+}
+
+const dedupeRepositoryLabels = (labels: GitRepositoryLabel[]): GitRepositoryLabel[] => {
+  const seen = new Set<string>()
+  const unique: GitRepositoryLabel[] = []
+
+  for (const label of labels) {
+    const key = label.id !== null ? `id:${label.id}` : `name:${label.name.toLowerCase()}`
+    if (seen.has(key)) {
+      continue
+    }
+    seen.add(key)
+    unique.push(label)
+  }
+
+  return unique
+}
+
+export const extractRepositoryLabels = (raw: unknown): GitRepositoryLabel[] => {
+  if (Array.isArray(raw)) {
+    const labels = raw
+      .map((entry) => normalizeRepositoryLabel(entry))
+      .filter((entry): entry is GitRepositoryLabel => entry !== null)
+    return dedupeRepositoryLabels(labels)
+  }
+
+  if (isRecord(raw)) {
+    if (Array.isArray(raw.labels)) {
+      return extractRepositoryLabels(raw.labels)
+    }
+
+    if (Array.isArray(raw.data)) {
+      return extractRepositoryLabels(raw.data)
+    }
+  }
+
+  return []
+}
+
+const withBody = <T>(
+  result: GitServiceApiExecutionResult<unknown>,
+  body: T,
+): GitServiceApiExecutionResult<T> => ({
+  ...result,
+  body,
+})
+
+type LabelListContext = {
+  labels: GitRepositoryLabel[]
+  context: GitServiceApiExecutionResult<unknown>
+}
+
+const listRepositoryLabels = async (
+  api: GitServiceApi,
+  owner: string,
+  repo: string,
+  options: {
+    query?: Record<string, string | number | boolean>
+    allPages?: boolean
+  } = {},
+): Promise<LabelListContext> => {
+  const listMethod = resolveLabelMethod(api, 'list')
+  const labels: GitRepositoryLabel[] = []
+  const query = options.query ?? {}
+  const allPages = options.allPages ?? true
+  const paginate = allPages && query.page === undefined && query.limit === undefined
+  let page = 1
+  let context: GitServiceApiExecutionResult<unknown> | null = null
+
+  while (page <= MAX_LABEL_LIST_PAGES) {
+    const queryForCall: Record<string, string | number | boolean> = { ...query }
+    if (paginate) {
+      queryForCall.limit = LABEL_LIST_PAGE_SIZE
+      queryForCall.page = page
+    }
+
+    const requestOptions = Object.keys(queryForCall).length > 0
+      ? { query: queryForCall }
+      : {}
+
+    const result = await executeLabelCall(listMethod, owner, repo, [], requestOptions)
+    ensureOk(result, `Failed to list labels for ${owner}/${repo}`)
+    context = result
+
+    const batch = extractRepositoryLabels(result.body)
+    labels.push(...batch)
+
+    if (!paginate || batch.length < LABEL_LIST_PAGE_SIZE) {
+      break
+    }
+
+    page += 1
+  }
+
+  if (paginate && page > MAX_LABEL_LIST_PAGES) {
+    throw new Error(`Label pagination exceeded ${MAX_LABEL_LIST_PAGES} pages for ${owner}/${repo}.`)
+  }
+
+  if (!context) {
+    throw new Error(`Label listing did not execute for ${owner}/${repo}.`)
+  }
+
+  return {
+    labels: dedupeRepositoryLabels(labels),
+    context,
+  }
+}
+
+type LabelLookupContext = LabelListContext & {
+  match: GitRepositoryLabel | null
+}
+
+const findRepositoryLabelByName = async (
+  api: GitServiceApi,
+  owner: string,
+  repo: string,
+  name: string,
+  options: {
+    caseSensitive?: boolean
+  } = {},
+): Promise<LabelLookupContext> => {
+  const listed = await listRepositoryLabels(api, owner, repo, { allPages: true })
+  const caseSensitive = options.caseSensitive ?? false
+  const target = caseSensitive ? name : name.toLowerCase()
+
+  const match = listed.labels.find((label) => {
+    const candidate = caseSensitive ? label.name : label.name.toLowerCase()
+    return candidate === target
+  }) ?? null
+
+  return {
+    ...listed,
+    match,
+  }
+}
+
+const buildLabelUpsertPayload = (
+  name: string,
+  options: Record<string, unknown>,
+  mode: 'create' | 'update',
+): Record<string, unknown> => {
+  const payload: Record<string, unknown> = {}
+
+  const data = options.data
+  if (isRecord(data)) {
+    Object.assign(payload, data)
+  }
+
+  if (options.color !== undefined) payload.color = options.color
+  if (options.description !== undefined) payload.description = options.description
+  if (options.exclusive !== undefined) payload.exclusive = options.exclusive
+  if (options.isArchived !== undefined) payload.is_archived = options.isArchived
+  if (options.is_archived !== undefined) payload.is_archived = options.is_archived
+
+  if (mode === 'create') {
+    payload.name = name
+    const color = toTrimmedString(payload.color)
+    if (!color) {
+      throw new Error(`Label "${name}" requires a non-empty "color" when creating.`)
+    }
+    payload.color = color
+  } else {
+    delete payload.name
+  }
+
+  return payload
+}
+
+type GitLabelListManagedBody = {
+  total: number
+  labels: GitRepositoryLabel[]
+}
+
+type GitLabelGetByNameBody = {
+  found: boolean
+  label: GitRepositoryLabel | null
+}
+
+type GitLabelUpsertBody = {
+  action: 'created' | 'updated' | 'unchanged'
+  label: GitRepositoryLabel
+}
+
+type GitLabelDeleteByNameBody = {
+  deleted: boolean
+  label: GitRepositoryLabel | null
+}
+
+export type GitLabelManagementApi = {
+  listManaged: GitServiceApiMethod
+  getByName: GitServiceApiMethod
+  upsert: GitServiceApiMethod
+  deleteByName: GitServiceApiMethod
+}
+
+export const createGitLabelManagementApi = (
+  api: GitServiceApi,
+  defaults: GitLabelManagementDefaults = {},
+): GitLabelManagementApi => {
+  return {
+    listManaged: async (
+      ownerOrOptions?: unknown,
+      repoOrOptions?: unknown,
+      maybeOptions?: unknown,
+    ): Promise<GitServiceApiExecutionResult<GitLabelListManagedBody>> => {
+      const scope = normalizeScopeArgs(ownerOrOptions, repoOrOptions, maybeOptions)
+      const { owner, repo } = resolveOwnerRepo(scope, defaults)
+      const allPages = toBoolean(scope.options.allPages, true)
+      const query = toQueryRecord(scope.options.query)
+
+      const listed = await listRepositoryLabels(api, owner, repo, { allPages, query })
+      return withBody(listed.context, {
+        total: listed.labels.length,
+        labels: listed.labels,
+      })
+    },
+
+    getByName: async (
+      labelName: unknown,
+      ownerOrOptions?: unknown,
+      repoOrOptions?: unknown,
+      maybeOptions?: unknown,
+    ): Promise<GitServiceApiExecutionResult<GitLabelGetByNameBody>> => {
+      const parsed = normalizeNamedScopeArgs(labelName, ownerOrOptions, repoOrOptions, maybeOptions)
+      const { owner, repo } = resolveOwnerRepo(parsed, defaults)
+      const caseSensitive = toBoolean(parsed.options.caseSensitive, false)
+
+      const lookup = await findRepositoryLabelByName(api, owner, repo, parsed.name, { caseSensitive })
+      return withBody(lookup.context, {
+        found: lookup.match !== null,
+        label: lookup.match,
+      })
+    },
+
+    upsert: async (
+      labelName: unknown,
+      ownerOrOptions?: unknown,
+      repoOrOptions?: unknown,
+      maybeOptions?: unknown,
+    ): Promise<GitServiceApiExecutionResult<GitLabelUpsertBody>> => {
+      const parsed = normalizeNamedScopeArgs(labelName, ownerOrOptions, repoOrOptions, maybeOptions)
+      const { owner, repo } = resolveOwnerRepo(parsed, defaults)
+      const caseSensitive = toBoolean(parsed.options.caseSensitive, false)
+
+      const lookup = await findRepositoryLabelByName(api, owner, repo, parsed.name, { caseSensitive })
+      if (lookup.match) {
+        const payload = buildLabelUpsertPayload(parsed.name, parsed.options, 'update')
+        if (Object.keys(payload).length === 0) {
+          return withBody(lookup.context, {
+            action: 'unchanged',
+            label: lookup.match,
+          })
+        }
+
+        if (lookup.match.id === null) {
+          throw new Error(`Label "${parsed.name}" does not expose an id and cannot be updated.`)
+        }
+
+        const editMethod = resolveLabelMethod(api, 'edit')
+        const result = await executeLabelCall(editMethod, owner, repo, [lookup.match.id], { data: payload })
+        ensureOk(result, `Failed to update label "${parsed.name}" in ${owner}/${repo}`)
+
+        const updated = normalizeRepositoryLabel(result.body)
+        if (!updated) {
+          throw new Error(`Update label response invalid for "${parsed.name}" in ${owner}/${repo}.`)
+        }
+
+        return withBody(result, {
+          action: 'updated',
+          label: updated,
+        })
+      }
+
+      const payload = buildLabelUpsertPayload(parsed.name, parsed.options, 'create')
+      const createMethod = resolveLabelMethod(api, 'create')
+      const result = await executeLabelCall(createMethod, owner, repo, [], { data: payload })
+      ensureOk(result, `Failed to create label "${parsed.name}" in ${owner}/${repo}`)
+
+      const created = normalizeRepositoryLabel(result.body)
+      if (!created) {
+        throw new Error(`Create label response invalid for "${parsed.name}" in ${owner}/${repo}.`)
+      }
+
+      return withBody(result, {
+        action: 'created',
+        label: created,
+      })
+    },
+
+    deleteByName: async (
+      labelName: unknown,
+      ownerOrOptions?: unknown,
+      repoOrOptions?: unknown,
+      maybeOptions?: unknown,
+    ): Promise<GitServiceApiExecutionResult<GitLabelDeleteByNameBody>> => {
+      const parsed = normalizeNamedScopeArgs(labelName, ownerOrOptions, repoOrOptions, maybeOptions)
+      const { owner, repo } = resolveOwnerRepo(parsed, defaults)
+      const strict = toBoolean(parsed.options.strict, false)
+      const caseSensitive = toBoolean(parsed.options.caseSensitive, false)
+
+      const lookup = await findRepositoryLabelByName(api, owner, repo, parsed.name, { caseSensitive })
+      if (!lookup.match) {
+        if (strict) {
+          throw new Error(`Label "${parsed.name}" was not found in ${owner}/${repo}.`)
+        }
+
+        return withBody(lookup.context, {
+          deleted: false,
+          label: null,
+        })
+      }
+
+      if (lookup.match.id === null) {
+        throw new Error(`Label "${parsed.name}" does not expose an id and cannot be deleted.`)
+      }
+
+      const deleteMethod = resolveLabelMethod(api, 'delete')
+      const result = await executeLabelCall(deleteMethod, owner, repo, [lookup.match.id])
+      ensureOk(result, `Failed to delete label "${parsed.name}" in ${owner}/${repo}`)
+
+      return withBody(result, {
+        deleted: true,
+        label: lookup.match,
+      })
+    },
+  }
+}
+
+const ensureNamespace = (root: GitServiceApi, path: string[]): GitServiceApi => {
+  let cursor: GitServiceApi = root
+  for (const segment of path) {
+    const current = cursor[segment]
+    if (!isRecord(current)) {
+      cursor[segment] = {}
+    }
+    cursor = cursor[segment] as GitServiceApi
+  }
+  return cursor
+}
+
+export const attachGitLabelManagementApi = (
+  api: GitServiceApi,
+  defaults: GitLabelManagementDefaults = {},
+): void => {
+  const methods = createGitLabelManagementApi(api, defaults)
+  const targets = [
+    ensureNamespace(api, ['label']),
+    ensureNamespace(api, ['repo', 'label']),
+  ]
+
+  for (const target of targets) {
+    for (const [name, method] of Object.entries(methods)) {
+      if (!(name in target)) {
+        target[name] = method
+      }
+    }
+  }
+}
+

package/src/platform/config.ts

@@ -0,0 +1,60 @@
+export type PlatformName = 'GITEA' | 'GITHUB'
+
+export interface GitPlatformConfig {
+  platform: PlatformName
+  giteaHost: string
+  giteaToken?: string
+  giteaApiVersion?: string
+  giteaSwaggerPath?: string
+}
+
+const DEFAULT_GITEA_HOST = 'https://gitea.example.com'
+const DEFAULT_PLATFORM: PlatformName = 'GITEA'
+const DEFAULT_GITEA_SWAGGER_PATH = '/swagger.v1.json'
+
+const normalizePlatform = (value?: string): PlatformName => {
+  const platform = (value ?? '').toUpperCase()
+  if (platform === 'GITEA') {
+    return 'GITEA'
+  }
+
+  if (platform === 'GITHUB') {
+    return 'GITHUB'
+  }
+
+  return DEFAULT_PLATFORM
+}
+
+export const getGitPlatformConfig = (overrides: Partial<GitPlatformConfig> = {}): GitPlatformConfig => {
+  const platform = normalizePlatform(
+    overrides.platform ??
+      process.env.PLATFORM ??
+      process.env.GIT_PLATFORM,
+  )
+
+  const giteaHost =
+    overrides.giteaHost ??
+    process.env.GITEA_HOST ??
+    DEFAULT_GITEA_HOST
+
+  const giteaToken =
+    overrides.giteaToken ??
+    process.env.GITEA_TOKEN
+
+  const giteaApiVersion =
+    overrides.giteaApiVersion ??
+    process.env.GITEA_API_VERSION
+
+  const giteaSwaggerPath =
+    overrides.giteaSwaggerPath ??
+    process.env.GITEA_SWAGGER_PATH ??
+    DEFAULT_GITEA_SWAGGER_PATH
+
+  return {
+    platform,
+    giteaHost,
+    giteaToken,
+    giteaApiVersion,
+    giteaSwaggerPath,
+  }
+}

package/.codex.example/config.toml

@@ -1,10 +0,0 @@
-[mcp_servers.git]
-command = "npx"
-args = ["-y", "-p", "@foundation0/git", "f0-git-mcp", "--tools-prefix", "git"]
-enabled = true
-startup_timeout_ms = 20_000
-env = {
-  GITEA_HOST = "https://gitea.example.com",
-  GITEA_USER = "your-user",
-  GITEA_TOKEN = "your-token"
-}

package/.env.example

@@ -1,10 +0,0 @@
-# Copy to ".env" and fill in values. Do not commit ".env".
-
-# Gitea MCP server (packages/git/mcp)
-GITEA_HOST=https://gitea.example.com
-GITEA_TOKEN=
-
-# Optional defaults for tests / dev
-GITEA_TEST_OWNER=example-org
-GITEA_TEST_REPO=example-repo
-

package/packages/fs/README.md

@@ -1,47 +0,0 @@
-# @workspace/fs
-
-`@workspace/fs` provides a Git-backed filesystem API implemented on top of `@foundation0/git` and an optional FUSE mount entrypoint.
-
-## API shape
-
-The package exposes promise-based drop-in helpers that mirror common `node:fs` methods:
-
-- `readFile`, `writeFile`, `appendFile`, `mkdir`, `readdir`, `rename`, `copyFile`, `unlink`, `rm`, `rmdir`, `stat`, `lstat`, `exists`, `access`
-- `promises` and default instance exports (`createGitFs`, `defaultGitFs`)
-- sync methods are intentionally not implemented and raise `ENOSYS`
-
-All paths are interpreted as `owner/repo/...`.
-
-If `defaultOwner` and `defaultRepo` are configured, one-segment paths map into that repo directly:
-
-- `README.md` -> `<defaultOwner>/<defaultRepo>/README.md`
-- `docs/guide.md` -> `<defaultOwner>/<defaultRepo>/docs/guide.md`
-
-### Usage
-
-```ts
-import { readFile, writeFile, readdir, promises } from '@workspace/fs'
-
-await writeFile('example-org/example-repo/README.md', 'hello world')
-const content = await readFile('example-org/example-repo/README.md', { encoding: 'utf8' })
-const entries = await readdir('example-org/example-repo')
-await promises.readFile('example-org/example-repo/README.md')
-```
-
-### Mount
-
-If `fuse-bindings` is installed, run:
-
-```bash
-bun run ./src/cli.ts --mount ./mnt --default-owner example-org --default-repo example-repo
-```
-
-Windows mount support options:
-
-- `--backend dokan` - load `node-fuse-bindings` (uses Dokany as the driver layer on Windows).
-- `--backend winfsp` - try `node-fuse-bindings` first, then `fuse-bindings`.
-- `--backend auto` (default) - on Windows, tries `dokan` then fallback to `fuse-bindings`; on non-Windows, uses `fuse-bindings`.
-
-When using Dokan/WinFsp backends, make sure the native libraries are installed and discoverable for native addon compilation.
-
-Note: these native mount backends currently do not resolve under Bun runtime on Windows in this environment (ABI 24/`bun`). If you need mount on Windows, run the CLI with Node.js instead of Bun, or use WSL.