@foundation0/git 1.0.0 → 1.2.0

package/packages/fs/src/git-fs.ts

@@ -1,705 +0,0 @@
-import { randomUUID } from 'node:crypto'
-import {
-  type GitServiceApi,
-  type GitServiceApiExecutionResult,
-  type GitServiceApiFactoryOptions,
-  type GitServiceApiMethod,
-  createGitServiceApi,
-} from '@foundation0/git'
-
-type GitFsQuery = Record<string, string | number | boolean>
-type WriteData = string | Uint8Array | ArrayBuffer
-type FileKind = 'file' | 'directory'
-
-export type GitFsOptions = Omit<GitServiceApiFactoryOptions, 'defaultOwner' | 'defaultRepo' | 'config'> & {
-  api?: GitServiceApi
-  config?: GitServiceApiFactoryOptions['config']
-  defaultOwner?: string
-  defaultRepo?: string
-  defaultCommitMessage?: string
-}
-
-type ReadFileOptions = {
-  encoding?: BufferEncoding
-  ref?: string
-}
-
-type WriteFileOptions = {
-  encoding?: BufferEncoding | 'base64'
-  message?: string
-  branch?: string
-  author?: unknown
-  committer?: unknown
-  flag?: string
-  overwrite?: boolean
-}
-
-type ReaddirOptions = {
-  withFileTypes?: boolean
-  ref?: string
-}
-
-type RmOptions = {
-  recursive?: boolean
-  force?: boolean
-}
-
-type GitFsError = NodeJS.ErrnoException
-
-export interface GitFsDirentLike {
-  name: string
-  isFile: () => boolean
-  isDirectory: () => boolean
-  isSymbolicLink: () => boolean
-  isBlockDevice: () => boolean
-  isCharacterDevice: () => boolean
-  isFIFO: () => boolean
-  isSocket: () => boolean
-  isUnknown: () => boolean
-}
-
-export interface GitFsStats {
-  isFile: () => boolean
-  isDirectory: () => boolean
-  isSymbolicLink: () => boolean
-  isFIFO: () => boolean
-  isCharacterDevice: () => boolean
-  isBlockDevice: () => boolean
-  isSocket: () => boolean
-  isUnknown: () => boolean
-  dev: number
-  ino: number
-  mode: number
-  nlink: number
-  uid: number
-  gid: number
-  rdev: number
-  size: number
-  blksize: number
-  blocks: number
-  atimeMs: number
-  mtimeMs: number
-  ctimeMs: number
-  birthtimeMs: number
-  atime: Date
-  mtime: Date
-  ctime: Date
-  birthtime: Date
-}
-
-interface ParsedPath {
-  owner: string
-  repo: string
-  repoPath: string
-}
-
-interface GitContentEntry {
-  name: string
-  path: string
-  type?: 'file' | 'dir' | string
-  sha?: string
-  size?: number
-  content?: string
-  encoding?: string
-}
-
-const createFsError = (code: string, message: string): GitFsError => {
-  const error = new Error(message) as GitFsError
-  error.code = code
-  return error
-}
-
-const normalizePath = (value: string): string => value.replace(/\\/g, '/').trim()
-
-const toSegments = (value: string): string[] =>
-  normalizePath(value)
-    .split('/')
-    .map((part) => part.trim())
-    .filter(Boolean)
-
-const normalizeRepoPath = (repoPath: string): string => repoPath.replace(/^\/+|\/+$/g, '')
-
-const parsePath = (
-  value: string,
-  defaults: { defaultOwner?: string; defaultRepo?: string },
-): ParsedPath => {
-  const parts = toSegments(value)
-
-  if (parts.length === 0) {
-    if (!defaults.defaultOwner || !defaults.defaultRepo) {
-      throw createFsError('ENOENT', `Path requires a repository root or default owner/repo: ${value}`)
-    }
-
-    return {
-      owner: defaults.defaultOwner,
-      repo: defaults.defaultRepo,
-      repoPath: '',
-    }
-  }
-
-  if (parts.length === 1) {
-    if (!defaults.defaultOwner || !defaults.defaultRepo) {
-      throw createFsError('ENOENT', `Path requires owner/repo prefix: ${value}`)
-    }
-
-    return {
-      owner: defaults.defaultOwner,
-      repo: defaults.defaultRepo,
-      repoPath: normalizeRepoPath(parts[0]),
-    }
-  }
-
-  return {
-    owner: parts[0],
-    repo: parts[1],
-    repoPath: normalizeRepoPath(parts.slice(2).join('/')),
-  }
-}
-
-const isRecord = (value: unknown): value is Record<string, unknown> =>
-  typeof value === 'object' && value !== null
-
-const parseEntries = (body: unknown): GitContentEntry[] => {
-  if (!Array.isArray(body)) {
-    return []
-  }
-
-  return body
-    .map((entry): GitContentEntry | null => {
-      if (!isRecord(entry)) {
-        return null
-      }
-
-      const name = typeof entry.name === 'string' ? entry.name : undefined
-      if (!name) {
-        return null
-      }
-
-      return {
-        name,
-        path: typeof entry.path === 'string' ? entry.path : name,
-        type: typeof entry.type === 'string' ? entry.type : undefined,
-        sha: typeof entry.sha === 'string' ? entry.sha : undefined,
-        size: typeof entry.size === 'number' ? entry.size : undefined,
-        content: typeof entry.content === 'string' ? entry.content : undefined,
-        encoding: typeof entry.encoding === 'string' ? entry.encoding : undefined,
-      }
-    })
-    .filter((entry): entry is GitContentEntry => entry !== null)
-}
-
-const parseFileEntry = (body: unknown): GitContentEntry | null => {
-  if (!isRecord(body)) {
-    return null
-  }
-
-  const name = typeof body.name === 'string'
-    ? body.name
-    : typeof body.path === 'string'
-      ? body.path
-      : ''
-  if (!name) {
-    return null
-  }
-
-  return {
-    name,
-    path: typeof body.path === 'string' ? body.path : name,
-    type: typeof body.type === 'string' ? body.type : undefined,
-    sha: typeof body.sha === 'string' ? body.sha : undefined,
-    size: typeof body.size === 'number' ? body.size : undefined,
-    content: typeof body.content === 'string' ? body.content : undefined,
-    encoding: typeof body.encoding === 'string' ? body.encoding : undefined,
-  }
-}
-
-const makeStats = (kind: FileKind, entry?: GitContentEntry): GitFsStats => {
-  const isDir = kind === 'directory'
-  const size = isDir ? 0 : (entry?.size ?? 0)
-  const timestamp = Date.now()
-
-  return {
-    dev: 0,
-    ino: 0,
-    mode: isDir ? 0o040755 : 0o100644,
-    nlink: isDir ? 2 : 1,
-    uid: 0,
-    gid: 0,
-    rdev: 0,
-    size,
-    blksize: 4096,
-    blocks: Math.max(1, Math.ceil(size / 4096)),
-    atimeMs: timestamp,
-    mtimeMs: timestamp,
-    ctimeMs: timestamp,
-    birthtimeMs: timestamp,
-    atime: new Date(timestamp),
-    mtime: new Date(timestamp),
-    ctime: new Date(timestamp),
-    birthtime: new Date(timestamp),
-    isFile: () => !isDir,
-    isDirectory: () => isDir,
-    isSymbolicLink: () => false,
-    isFIFO: () => false,
-    isCharacterDevice: () => false,
-    isBlockDevice: () => false,
-    isSocket: () => false,
-    isUnknown: () => false,
-  }
-}
-
-const makeDirent = (entry: GitContentEntry): GitFsDirentLike => {
-  const isDir = entry.type === 'dir'
-  return {
-    name: entry.name,
-    isFile: () => !isDir,
-    isDirectory: () => isDir,
-    isSymbolicLink: () => false,
-    isBlockDevice: () => false,
-    isCharacterDevice: () => false,
-    isFIFO: () => false,
-    isSocket: () => false,
-    isUnknown: () => false,
-  }
-}
-
-const responseToError = (status: number, action: string, path: string): GitFsError => {
-  if (status === 404) {
-    return createFsError('ENOENT', `${action}: no such path ${path}`)
-  }
-
-  if (status === 401 || status === 403) {
-    return createFsError('EACCES', `${action}: access denied for ${path}`)
-  }
-
-  if (status === 409) {
-    return createFsError('EEXIST', `${action}: conflict ${path}`)
-  }
-
-  if (status >= 500) {
-    return createFsError('EIO', `${action}: remote API failed for ${path} (${status})`)
-  }
-
-  return createFsError('EIO', `${action}: remote API error for ${path} (${status})`)
-}
-
-const toGitPath = (path: ParsedPath): string => `${path.owner}/${path.repo}/${path.repoPath}`
-
-const encodeForGit = (value: WriteData, encoding: BufferEncoding | 'base64' | undefined): string => {
-  if (typeof value === 'string') {
-    return Buffer.from(value, encoding === 'base64' ? 'base64' : encoding ?? 'utf8').toString('base64')
-  }
-
-  if (value instanceof ArrayBuffer) {
-    return Buffer.from(value).toString('base64')
-  }
-
-  return Buffer.from(value).toString('base64')
-}
-
-const decodeFromGit = (entry: GitContentEntry): Buffer => {
-  if (typeof entry.content === 'string') {
-    return Buffer.from(entry.content.replace(/\s+/g, ''), 'base64')
-  }
-
-  return Buffer.from([])
-}
-
-const commitMessage = (operation: string, gitPath: string, explicit?: string, defaults?: string): string => {
-  if (explicit) {
-    return explicit
-  }
-
-  if (defaults) {
-    return defaults
-  }
-
-  return `${operation} ${gitPath} [${randomUUID().slice(0, 6)}]`
-}
-
-interface GitFsAsyncApi {
-  rmdir(path: string): Promise<void>
-  readdir(path: string, options?: ReaddirOptions): Promise<string[] | GitFsDirentLike[]>
-  readFile(path: string, options?: ReadFileOptions): Promise<Buffer | string>
-  writeFile(path: string, data: WriteData, options?: WriteFileOptions): Promise<void>
-  appendFile(path: string, data: WriteData, options?: WriteFileOptions): Promise<void>
-  mkdir(path: string): Promise<void>
-  rm(path: string, options?: RmOptions): Promise<void>
-  unlink(path: string): Promise<void>
-  rename(oldPath: string, newPath: string): Promise<void>
-  copyFile(src: string, dest: string): Promise<void>
-  stat(path: string): Promise<GitFsStats>
-  lstat(path: string): Promise<GitFsStats>
-  exists(path: string): Promise<boolean>
-  access(path: string): Promise<void>
-}
-
-export interface GitFsInstance extends GitFsAsyncApi {
-  api: GitServiceApi
-  promises: GitFsAsyncApi
-  rmdirSync(path: string): never
-  readFileSync(path: string): never
-  writeFileSync(path: string): never
-  appendFileSync(path: string): never
-  readdirSync(path: string): never
-  mkdirSync(path: string): never
-  rmSync(path: string): never
-  unlinkSync(path: string): never
-  renameSync(oldPath: string, newPath: string): never
-  copyFileSync(src: string, dest: string): never
-  statSync(path: string): never
-  lstatSync(path: string): never
-  existsSync(path: string): never
-  accessSync(path: string): never
-}
-
-const buildGitApi = (options: GitFsOptions): GitServiceApi => {
-  if (options.api) {
-    return options.api
-  }
-
-  return createGitServiceApi({
-    config: options.config,
-    defaultOwner: options.defaultOwner,
-    defaultRepo: options.defaultRepo,
-  })
-}
-
-const unsupportedSync = (): never => {
-  throw createFsError('ENOSYS', 'Git filesystem sync APIs are not supported')
-}
-
-export const createGitFs = (options: GitFsOptions = {}): GitFsInstance => {
-  const api = buildGitApi(options)
-  const defaults = { defaultOwner: options.defaultOwner, defaultRepo: options.defaultRepo }
-  const defaultMessage = options.defaultCommitMessage
-
-  const callContentsMethod = async (
-    action: 'list' | 'view' | 'create' | 'update' | 'delete',
-    target: ParsedPath,
-    query?: GitFsQuery,
-    payload?: Record<string, unknown>,
-  ): Promise<GitServiceApiExecutionResult> => {
-    const actionMethod = api.repo.contents[action] as GitServiceApiMethod
-    const args: unknown[] = [target.owner, target.repo, target.repoPath || '']
-
-    const request: Record<string, unknown> = {}
-    if (query && Object.keys(query).length > 0) {
-      request.query = query
-    }
-
-    if (payload !== undefined) {
-      request.data = payload
-    }
-
-    if (Object.keys(request).length > 0) {
-      args.push(request)
-    }
-
-    const response = await actionMethod(...args)
-    if (!response.ok) {
-      throw responseToError(response.status, action, toGitPath(target))
-    }
-
-    return response
-  }
-
-  const listEntries = async (target: ParsedPath, query?: GitFsQuery): Promise<GitContentEntry[]> => {
-    const response = await callContentsMethod('list', target, query)
-    return parseEntries(response.body)
-  }
-
-  const readEntry = async (
-    target: ParsedPath,
-    query?: GitFsQuery,
-  ): Promise<GitContentEntry | null> => {
-    const response = await callContentsMethod('view', target, query)
-    if (Array.isArray(response.body)) {
-      return null
-    }
-
-    return parseFileEntry(response.body)
-  }
-
-  const resolveRefQuery = (options?: { ref?: string }): GitFsQuery | undefined => {
-    if (!options?.ref) {
-      return undefined
-    }
-
-    return { ref: options.ref }
-  }
-
-  const rmdir: GitFsAsyncApi['rmdir'] = async () => {
-    throw createFsError('ENOSYS', 'rmdir is not supported for Git-backed contents')
-  }
-
-  const readdir: GitFsAsyncApi['readdir'] = async (path, options) => {
-    const target = parsePath(path, defaults)
-    const entries = await listEntries(target, resolveRefQuery(options))
-    const filtered = entries.filter((entry) => entry.name.length > 0)
-
-    if (options?.withFileTypes) {
-      return filtered.map((entry) => makeDirent(entry))
-    }
-
-    return filtered.map((entry) => entry.name)
-  }
-
-  const readFile: GitFsAsyncApi['readFile'] = async (path, options) => {
-    const target = parsePath(path, defaults)
-    const response = await callContentsMethod('view', target, resolveRefQuery(options))
-    if (Array.isArray(response.body)) {
-      throw createFsError('EISDIR', `Path is a directory: ${toGitPath(target)}`)
-    }
-
-    const entry = parseFileEntry(response.body)
-    if (!entry) {
-      throw createFsError('ENOENT', `No such file: ${toGitPath(target)}`)
-    }
-
-    if (entry.type === 'dir') {
-      throw createFsError('EISDIR', `Path is a directory: ${toGitPath(target)}`)
-    }
-
-    const data = decodeFromGit(entry)
-    if (options?.encoding) {
-      return data.toString(options.encoding)
-    }
-
-    return data
-  }
-
-  const writeFile: GitFsAsyncApi['writeFile'] = async (path, data, options = {}) => {
-    const target = parsePath(path, defaults)
-    const existing = await readEntry(target).catch((error) => {
-      if ((error as GitFsError).code === 'ENOENT') {
-        return null
-      }
-
-      throw error
-    })
-
-    if (existing?.type === 'dir') {
-      throw createFsError('EISDIR', `Cannot write a file over directory: ${toGitPath(target)}`)
-    }
-
-    if (existing && options.overwrite === false) {
-      throw createFsError('EEXIST', `File exists: ${toGitPath(target)}`)
-    }
-
-    const payload = {
-      content: encodeForGit(data, options.encoding),
-      message: commitMessage(
-        existing ? 'overwrite' : 'file',
-        toGitPath(target),
-        options.message,
-        defaultMessage,
-      ),
-      sha: existing?.sha,
-      branch: options.branch,
-      author: options.author,
-      committer: options.committer,
-    }
-
-    if (existing) {
-      if (!payload.sha) {
-        throw createFsError('EINVAL', `No sha available for update: ${toGitPath(target)}`)
-      }
-
-      await callContentsMethod('update', target, undefined, payload)
-      return
-    }
-
-    await callContentsMethod('create', target, undefined, payload)
-  }
-
-  const appendFile: GitFsAsyncApi['appendFile'] = async (path, data, options) => {
-    const current = await readFile(path).catch((error) => {
-      if ((error as GitFsError).code === 'ENOENT') {
-        return Buffer.from([])
-      }
-
-      throw error
-    })
-    const base = typeof current === 'string' ? Buffer.from(current) : current
-    const payload = typeof data === 'string' ? Buffer.from(data) : Buffer.from(data)
-    await writeFile(path, Buffer.concat([base, payload]), options)
-  }
-
-  const mkdir: GitFsAsyncApi['mkdir'] = async () => {
-    throw createFsError('ENOSYS', 'mkdir is not supported by Git contents API')
-  }
-
-  const rm: GitFsAsyncApi['rm'] = async (path, options = {}) => {
-    if (options.recursive) {
-      throw createFsError('ENOSYS', 'recursive rm is not supported for Git-backed FS')
-    }
-
-    await unlink(path)
-  }
-
-  const unlink: GitFsAsyncApi['unlink'] = async (path) => {
-    const target = parsePath(path, defaults)
-    const existing = await readEntry(target)
-    if (!existing) {
-      throw createFsError('ENOENT', `No such file: ${toGitPath(target)}`)
-    }
-
-    if (existing.type === 'dir') {
-      throw createFsError('EISDIR', `Cannot unlink directory: ${toGitPath(target)}`)
-    }
-
-    if (!existing.sha) {
-      throw createFsError('EINVAL', `No sha available for delete: ${toGitPath(target)}`)
-    }
-
-    await callContentsMethod('delete', target, undefined, {
-      message: commitMessage('delete', toGitPath(target), undefined, defaultMessage),
-      sha: existing.sha,
-    })
-  }
-
-  const rename: GitFsAsyncApi['rename'] = async (oldPath, newPath) => {
-    const content = await readFile(oldPath)
-    await writeFile(newPath, typeof content === 'string' ? content : Buffer.from(content))
-    await unlink(oldPath)
-  }
-
-  const copyFile: GitFsAsyncApi['copyFile'] = async (src, dest) => {
-    const content = await readFile(src)
-    await writeFile(dest, typeof content === 'string' ? content : Buffer.from(content))
-  }
-
-  const stat: GitFsAsyncApi['stat'] = async (path) => {
-    const target = parsePath(path, defaults)
-
-    if (target.repoPath === '') {
-      return makeStats('directory')
-    }
-
-    try {
-      await listEntries(target)
-      return makeStats('directory')
-    } catch (error) {
-      const code = (error as GitFsError).code
-      if (code !== 'ENOENT' && code !== 'ENOTDIR') {
-        throw error
-      }
-    }
-
-    const existing = await readEntry(target)
-    if (!existing) {
-      throw createFsError('ENOENT', `No such path: ${toGitPath(target)}`)
-    }
-
-    if (existing.type === 'dir') {
-      return makeStats('directory', existing)
-    }
-
-    return makeStats('file', existing)
-  }
-
-  const lstat: GitFsAsyncApi['lstat'] = async (path) => {
-    return stat(path)
-  }
-
-  const existsAsync: GitFsAsyncApi['exists'] = async (path) => {
-    try {
-      const target = parsePath(path, defaults)
-      const entry = await readEntry(target)
-      return Boolean(entry)
-    } catch (error) {
-      if ((error as GitFsError).code === 'ENOENT') {
-        return false
-      }
-
-      throw error
-    }
-  }
-
-  const access: GitFsAsyncApi['access'] = async (path) => {
-    const found = await existsAsync(path)
-    if (!found) {
-      throw createFsError('ENOENT', `No such path: ${path}`)
-    }
-  }
-
-  const asyncApi: GitFsAsyncApi = {
-    rmdir,
-    readdir,
-    readFile,
-    writeFile,
-    appendFile,
-    mkdir,
-    rm,
-    unlink,
-    rename,
-    copyFile,
-    stat,
-    lstat,
-    exists: existsAsync,
-    access,
-  }
-
-  const syncUnsupported = {
-    rmdirSync: unsupportedSync,
-    readFileSync: unsupportedSync,
-    writeFileSync: unsupportedSync,
-    appendFileSync: unsupportedSync,
-    readdirSync: unsupportedSync,
-    mkdirSync: unsupportedSync,
-    rmSync: unsupportedSync,
-    unlinkSync: unsupportedSync,
-    renameSync: unsupportedSync,
-    copyFileSync: unsupportedSync,
-    statSync: unsupportedSync,
-    lstatSync: unsupportedSync,
-    existsSync: unsupportedSync,
-    accessSync: unsupportedSync,
-  }
-
-  return {
-    api,
-    ...asyncApi,
-    ...syncUnsupported,
-    promises: asyncApi,
-  }
-}
-
-export const defaultGitFs: GitFsInstance = createGitFs({
-  config: {
-    platform: 'GITEA',
-  },
-  defaultOwner: process.env.GITEA_TEST_OWNER ?? 'example-org',
-  defaultRepo: process.env.GITEA_TEST_REPO ?? 'example-repo',
-})
-
-export const promises = defaultGitFs.promises
-export const readdir = defaultGitFs.readdir
-export const readFile = defaultGitFs.readFile
-export const writeFile = defaultGitFs.writeFile
-export const appendFile = defaultGitFs.appendFile
-export const mkdir = defaultGitFs.mkdir
-export const rm = defaultGitFs.rm
-export const unlink = defaultGitFs.unlink
-export const rename = defaultGitFs.rename
-export const copyFile = defaultGitFs.copyFile
-export const stat = defaultGitFs.stat
-export const lstat = defaultGitFs.lstat
-export const exists = defaultGitFs.exists
-export const access = defaultGitFs.access
-export const rmdir = defaultGitFs.rmdir
-export const readFileSync = defaultGitFs.readFileSync
-export const writeFileSync = defaultGitFs.writeFileSync
-export const appendFileSync = defaultGitFs.appendFileSync
-export const readdirSync = defaultGitFs.readdirSync
-export const mkdirSync = defaultGitFs.mkdirSync
-export const rmSync = defaultGitFs.rmSync
-export const rmdirSync = defaultGitFs.rmdirSync
-export const unlinkSync = defaultGitFs.unlinkSync
-export const renameSync = defaultGitFs.renameSync
-export const copyFileSync = defaultGitFs.copyFileSync
-export const statSync = defaultGitFs.statSync
-export const lstatSync = defaultGitFs.lstatSync
-export const existsSync = defaultGitFs.existsSync
-export const accessSync = defaultGitFs.accessSync