@mantiq/filesystem 0.0.1

package/src/drivers/GCSDriver.ts

@@ -0,0 +1,311 @@
+import type { FilesystemDriver, PutOptions } from '../contracts/FilesystemDriver.ts'
+import { FilesystemError } from '../errors/FilesystemError.ts'
+import { FileNotFoundError } from '../errors/FileNotFoundError.ts'
+import { guessMimeType } from '../helpers/mime.ts'
+
+export interface GCSConfig {
+  bucket: string
+  projectId?: string
+  keyFilename?: string
+  credentials?: Record<string, any>
+  root?: string
+  url?: string
+  visibility?: 'public' | 'private'
+}
+
+/**
+ * Google Cloud Storage filesystem driver.
+ *
+ * Requires: bun add @google-cloud/storage
+ */
+export class GCSDriver implements FilesystemDriver {
+  private _storage: any = null
+  private _bucket: any = null
+  private readonly bucketName: string
+  private readonly prefix: string
+  private readonly urlBase: string | undefined
+  private readonly defaultVisibility: 'public' | 'private'
+  private readonly _config: GCSConfig
+
+  constructor(config: GCSConfig) {
+    this._config = config
+    this.bucketName = config.bucket
+    this.prefix = config.root ? config.root.replace(/^\/+|\/+$/g, '') + '/' : ''
+    this.urlBase = config.url
+    this.defaultVisibility = config.visibility ?? 'private'
+  }
+
+  private async bucket(): Promise<any> {
+    if (!this._bucket) {
+      let Storage: any
+      try {
+        ;({ Storage } = await import('@google-cloud/storage'))
+      } catch {
+        throw new FilesystemError(
+          'The @google-cloud/storage package is required for the GCS driver. Install it with: bun add @google-cloud/storage',
+        )
+      }
+      const opts: any = {}
+      if (this._config.projectId) opts.projectId = this._config.projectId
+      if (this._config.keyFilename) opts.keyFilename = this._config.keyFilename
+      if (this._config.credentials) opts.credentials = this._config.credentials
+      this._storage = new Storage(opts)
+      this._bucket = this._storage.bucket(this.bucketName)
+    }
+    return this._bucket
+  }
+
+  private async file(path: string): Promise<any> {
+    const b = await this.bucket()
+    return b.file(this.key(path))
+  }
+
+  private key(path: string): string {
+    return this.prefix + path.replace(/^\/+/, '')
+  }
+
+  private stripPrefix(key: string): string {
+    return this.prefix && key.startsWith(this.prefix)
+      ? key.slice(this.prefix.length)
+      : key
+  }
+
+  // ── Reads ─────────────────────────────────────────────────────────────────
+
+  async exists(path: string): Promise<boolean> {
+    const f = await this.file(path)
+    const [exists] = await f.exists()
+    return exists
+  }
+
+  async get(path: string): Promise<string | null> {
+    const f = await this.file(path)
+    try {
+      const [contents] = await f.download()
+      return contents.toString('utf-8')
+    } catch (e: any) {
+      if (e.code === 404) return null
+      throw new FilesystemError(`GCS get failed: ${e.message}`, { path })
+    }
+  }
+
+  async getBytes(path: string): Promise<Uint8Array | null> {
+    const f = await this.file(path)
+    try {
+      const [contents] = await f.download()
+      return new Uint8Array(contents)
+    } catch (e: any) {
+      if (e.code === 404) return null
+      throw new FilesystemError(`GCS getBytes failed: ${e.message}`, { path })
+    }
+  }
+
+  async stream(path: string): Promise<ReadableStream | null> {
+    if (!(await this.exists(path))) return null
+    const f = await this.file(path)
+    const nodeStream = f.createReadStream()
+    return new ReadableStream({
+      start(controller) {
+        nodeStream.on('data', (chunk: any) => controller.enqueue(new Uint8Array(chunk)))
+        nodeStream.on('end', () => controller.close())
+        nodeStream.on('error', (err: any) => controller.error(err))
+      },
+    })
+  }
+
+  // ── Writes ────────────────────────────────────────────────────────────────
+
+  async put(path: string, contents: string | Uint8Array, options?: PutOptions): Promise<void> {
+    const f = await this.file(path)
+    const buffer = typeof contents === 'string' ? Buffer.from(contents, 'utf-8') : Buffer.from(contents)
+    const contentType = options?.mimeType ?? guessMimeType(path)
+    await f.save(buffer, {
+      ...(contentType ? { contentType } : {}),
+      resumable: false,
+    })
+    const visibility = options?.visibility ?? this.defaultVisibility
+    if (visibility === 'public') {
+      await f.makePublic()
+    } else {
+      await f.makePrivate()
+    }
+  }
+
+  async putStream(path: string, stream: ReadableStream, options?: PutOptions): Promise<void> {
+    const body = new Uint8Array(await new Response(stream).arrayBuffer())
+    await this.put(path, body, options)
+  }
+
+  async append(path: string, contents: string): Promise<void> {
+    const existing = (await this.get(path)) ?? ''
+    await this.put(path, existing + contents)
+  }
+
+  async prepend(path: string, contents: string): Promise<void> {
+    const existing = (await this.get(path)) ?? ''
+    await this.put(path, contents + existing)
+  }
+
+  // ── Operations ────────────────────────────────────────────────────────────
+
+  async delete(path: string | string[]): Promise<boolean> {
+    const paths = Array.isArray(path) ? path : [path]
+    try {
+      for (const p of paths) {
+        const f = await this.file(p)
+        await f.delete({ ignoreNotFound: true })
+      }
+      return true
+    } catch {
+      return false
+    }
+  }
+
+  async copy(from: string, to: string): Promise<void> {
+    const src = await this.file(from)
+    const dest = await this.file(to)
+    await src.copy(dest)
+  }
+
+  async move(from: string, to: string): Promise<void> {
+    const src = await this.file(from)
+    const dest = await this.file(to)
+    await src.move(dest)
+  }
+
+  // ── Metadata ──────────────────────────────────────────────────────────────
+
+  async size(path: string): Promise<number> {
+    const meta = await this.metadata(path)
+    return parseInt(meta.size ?? '0', 10)
+  }
+
+  async lastModified(path: string): Promise<number> {
+    const meta = await this.metadata(path)
+    return meta.updated ? new Date(meta.updated).getTime() : 0
+  }
+
+  async mimeType(path: string): Promise<string | null> {
+    const meta = await this.metadata(path)
+    return meta.contentType ?? null
+  }
+
+  path(filePath: string): string {
+    return this.key(filePath)
+  }
+
+  // ── URLs ──────────────────────────────────────────────────────────────────
+
+  url(path: string): string {
+    const k = this.key(path)
+    if (this.urlBase) {
+      return `${this.urlBase.replace(/\/+$/, '')}/${k}`
+    }
+    return `https://storage.googleapis.com/${this.bucketName}/${k}`
+  }
+
+  async temporaryUrl(path: string, expiration: number, _options?: Record<string, any>): Promise<string> {
+    const f = await this.file(path)
+    const [url] = await f.getSignedUrl({
+      action: 'read',
+      expires: Date.now() + expiration * 1000,
+    })
+    return url
+  }
+
+  // ── Directories ───────────────────────────────────────────────────────────
+
+  async files(directory: string = ''): Promise<string[]> {
+    const prefix = this.directoryPrefix(directory)
+    const b = await this.bucket()
+    const [files] = await b.getFiles({ prefix, delimiter: '/' })
+    return files
+      .map((f: any) => this.stripPrefix(f.name))
+      .filter((name: string) => !name.endsWith('/'))
+  }
+
+  async allFiles(directory: string = ''): Promise<string[]> {
+    const prefix = this.directoryPrefix(directory)
+    const b = await this.bucket()
+    const [files] = await b.getFiles({ prefix })
+    return files
+      .map((f: any) => this.stripPrefix(f.name))
+      .filter((name: string) => !name.endsWith('/'))
+      .sort()
+  }
+
+  async directories(directory: string = ''): Promise<string[]> {
+    const prefix = this.directoryPrefix(directory)
+    const b = await this.bucket()
+    const [, , apiResponse] = await b.getFiles({ prefix, delimiter: '/', autoPaginate: false })
+    return (apiResponse.prefixes ?? []).map((p: string) =>
+      this.stripPrefix(p).replace(/\/$/, ''),
+    )
+  }
+
+  async allDirectories(directory: string = ''): Promise<string[]> {
+    const allFiles = await this.allFiles(directory)
+    const dirs = new Set<string>()
+    for (const file of allFiles) {
+      const parts = file.split('/')
+      for (let i = 1; i < parts.length; i++) {
+        dirs.add(parts.slice(0, i).join('/'))
+      }
+    }
+    return [...dirs].sort()
+  }
+
+  async makeDirectory(path: string): Promise<void> {
+    const f = await this.file(path + '/')
+    await f.save('', { resumable: false })
+  }
+
+  async deleteDirectory(directory: string): Promise<boolean> {
+    const prefix = this.directoryPrefix(directory)
+    const b = await this.bucket()
+    try {
+      await b.deleteFiles({ prefix, force: true })
+      return true
+    } catch {
+      return false
+    }
+  }
+
+  // ── Visibility ────────────────────────────────────────────────────────────
+
+  async setVisibility(path: string, visibility: 'public' | 'private'): Promise<void> {
+    const f = await this.file(path)
+    if (visibility === 'public') {
+      await f.makePublic()
+    } else {
+      await f.makePrivate()
+    }
+  }
+
+  async getVisibility(path: string): Promise<string> {
+    const f = await this.file(path)
+    try {
+      const [isPublic] = await f.isPublic()
+      return isPublic ? 'public' : 'private'
+    } catch {
+      return 'private'
+    }
+  }
+
+  // ── Internal ──────────────────────────────────────────────────────────────
+
+  private async metadata(path: string): Promise<any> {
+    const f = await this.file(path)
+    try {
+      const [meta] = await f.getMetadata()
+      return meta
+    } catch (e: any) {
+      if (e.code === 404) throw new FileNotFoundError(path)
+      throw new FilesystemError(`GCS metadata failed: ${e.message}`, { path })
+    }
+  }
+
+  private directoryPrefix(directory: string): string {
+    return directory ? this.key(directory).replace(/\/$/, '') + '/' : this.prefix
+  }
+}

package/src/drivers/LocalDriver.ts

@@ -0,0 +1,281 @@
+import { resolve, join, dirname, relative } from 'node:path'
+import { mkdir, rm, readdir, stat, rename, copyFile, chmod, appendFile } from 'node:fs/promises'
+import type { FilesystemDriver, PutOptions } from '../contracts/FilesystemDriver.ts'
+import { FilesystemError } from '../errors/FilesystemError.ts'
+import { FileNotFoundError } from '../errors/FileNotFoundError.ts'
+
+export class LocalDriver implements FilesystemDriver {
+  private readonly root: string
+  private readonly urlBase: string | undefined
+  private readonly defaultVisibility: 'public' | 'private'
+
+  constructor(root: string, urlBase?: string, defaultVisibility: 'public' | 'private' = 'public') {
+    this.root = resolve(root)
+    this.urlBase = urlBase
+    this.defaultVisibility = defaultVisibility
+  }
+
+  // ── Reads ───────────────────────────────────────────────────────────────────
+
+  async exists(path: string): Promise<boolean> {
+    return Bun.file(this.fullPath(path)).exists()
+  }
+
+  async get(path: string): Promise<string | null> {
+    const fp = this.fullPath(path)
+    const file = Bun.file(fp)
+    if (!(await file.exists())) return null
+    return file.text()
+  }
+
+  async getBytes(path: string): Promise<Uint8Array | null> {
+    const fp = this.fullPath(path)
+    const file = Bun.file(fp)
+    if (!(await file.exists())) return null
+    return new Uint8Array(await file.arrayBuffer())
+  }
+
+  async stream(path: string): Promise<ReadableStream | null> {
+    const fp = this.fullPath(path)
+    const file = Bun.file(fp)
+    if (!(await file.exists())) return null
+    return file.stream()
+  }
+
+  // ── Writes ──────────────────────────────────────────────────────────────────
+
+  async put(path: string, contents: string | Uint8Array, options?: PutOptions): Promise<void> {
+    const fp = this.fullPath(path)
+    await mkdir(dirname(fp), { recursive: true })
+    await Bun.write(fp, contents)
+
+    const visibility = options?.visibility ?? this.defaultVisibility
+    await this.applyVisibility(fp, visibility)
+  }
+
+  async putStream(path: string, stream: ReadableStream, options?: PutOptions): Promise<void> {
+    const fp = this.fullPath(path)
+    await mkdir(dirname(fp), { recursive: true })
+    // Consume the stream into a Response to get the full body, then write
+    const body = await new Response(stream).arrayBuffer()
+    await Bun.write(fp, body)
+
+    const visibility = options?.visibility ?? this.defaultVisibility
+    await this.applyVisibility(fp, visibility)
+  }
+
+  async append(path: string, contents: string): Promise<void> {
+    const fp = this.fullPath(path)
+    await mkdir(dirname(fp), { recursive: true })
+    await appendFile(fp, contents)
+  }
+
+  async prepend(path: string, contents: string): Promise<void> {
+    const fp = this.fullPath(path)
+    await mkdir(dirname(fp), { recursive: true })
+    const file = Bun.file(fp)
+    const existing = (await file.exists()) ? await file.text() : ''
+    await Bun.write(fp, contents + existing)
+  }
+
+  // ── Operations ──────────────────────────────────────────────────────────────
+
+  async delete(path: string | string[]): Promise<boolean> {
+    const paths = Array.isArray(path) ? path : [path]
+    let allDeleted = true
+
+    for (const p of paths) {
+      const fp = this.fullPath(p)
+      try {
+        if (await Bun.file(fp).exists()) {
+          await rm(fp)
+        } else {
+          allDeleted = false
+        }
+      } catch {
+        allDeleted = false
+      }
+    }
+
+    return allDeleted
+  }
+
+  async copy(from: string, to: string): Promise<void> {
+    const fromPath = this.fullPath(from)
+    const toPath = this.fullPath(to)
+    await mkdir(dirname(toPath), { recursive: true })
+    await copyFile(fromPath, toPath)
+  }
+
+  async move(from: string, to: string): Promise<void> {
+    const fromPath = this.fullPath(from)
+    const toPath = this.fullPath(to)
+    await mkdir(dirname(toPath), { recursive: true })
+    await rename(fromPath, toPath)
+  }
+
+  // ── Metadata ────────────────────────────────────────────────────────────────
+
+  async size(path: string): Promise<number> {
+    const fp = this.fullPath(path)
+    try {
+      const s = await stat(fp)
+      return s.size
+    } catch {
+      throw new FileNotFoundError(path)
+    }
+  }
+
+  async lastModified(path: string): Promise<number> {
+    const fp = this.fullPath(path)
+    try {
+      const s = await stat(fp)
+      return Math.floor(s.mtimeMs)
+    } catch {
+      throw new FileNotFoundError(path)
+    }
+  }
+
+  async mimeType(path: string): Promise<string | null> {
+    const fp = this.fullPath(path)
+    const file = Bun.file(fp)
+    if (!(await file.exists())) return null
+    return file.type || null
+  }
+
+  path(filePath: string): string {
+    return this.fullPath(filePath)
+  }
+
+  // ── URLs ────────────────────────────────────────────────────────────────────
+
+  url(path: string): string {
+    if (!this.urlBase) {
+      throw new FilesystemError('URL generation is not supported — no url configured for this disk.', { path })
+    }
+    return `${this.urlBase.replace(/\/+$/, '')}/${path.replace(/^\/+/, '')}`
+  }
+
+  async temporaryUrl(_path: string, _expiration: number, _options?: Record<string, any>): Promise<string> {
+    throw new FilesystemError('Temporary URLs are not supported by the local driver.')
+  }
+
+  // ── Directories ─────────────────────────────────────────────────────────────
+
+  async files(directory: string = ''): Promise<string[]> {
+    const dir = this.fullPath(directory)
+    try {
+      const entries = await readdir(dir, { withFileTypes: true })
+      return entries
+        .filter((e) => e.isFile())
+        .map((e) => directory ? `${directory}/${e.name}` : e.name)
+    } catch {
+      return []
+    }
+  }
+
+  async allFiles(directory: string = ''): Promise<string[]> {
+    const dir = this.fullPath(directory)
+    try {
+      const entries = await readdir(dir, { withFileTypes: true, recursive: true })
+      const results: string[] = []
+      for (const e of entries) {
+        if (e.isFile()) {
+          // Build relative path from the parentPath if available
+          const parentRel = this.entryRelativePath(e, dir)
+          const full = parentRel ? `${parentRel}/${e.name}` : e.name
+          results.push(directory ? `${directory}/${full}` : full)
+        }
+      }
+      return results.sort()
+    } catch {
+      return []
+    }
+  }
+
+  async directories(directory: string = ''): Promise<string[]> {
+    const dir = this.fullPath(directory)
+    try {
+      const entries = await readdir(dir, { withFileTypes: true })
+      return entries
+        .filter((e) => e.isDirectory())
+        .map((e) => directory ? `${directory}/${e.name}` : e.name)
+    } catch {
+      return []
+    }
+  }
+
+  async allDirectories(directory: string = ''): Promise<string[]> {
+    const dir = this.fullPath(directory)
+    try {
+      const entries = await readdir(dir, { withFileTypes: true, recursive: true })
+      const results: string[] = []
+      for (const e of entries) {
+        if (e.isDirectory()) {
+          const parentRel = this.entryRelativePath(e, dir)
+          const full = parentRel ? `${parentRel}/${e.name}` : e.name
+          results.push(directory ? `${directory}/${full}` : full)
+        }
+      }
+      return results.sort()
+    } catch {
+      return []
+    }
+  }
+
+  async makeDirectory(path: string): Promise<void> {
+    await mkdir(this.fullPath(path), { recursive: true })
+  }
+
+  async deleteDirectory(directory: string): Promise<boolean> {
+    const fp = this.fullPath(directory)
+    try {
+      await rm(fp, { recursive: true, force: true })
+      return true
+    } catch {
+      return false
+    }
+  }
+
+  // ── Visibility ──────────────────────────────────────────────────────────────
+
+  async setVisibility(path: string, visibility: 'public' | 'private'): Promise<void> {
+    await this.applyVisibility(this.fullPath(path), visibility)
+  }
+
+  async getVisibility(path: string): Promise<string> {
+    const fp = this.fullPath(path)
+    const s = await stat(fp)
+    // Check if "others" have read permission (o+r)
+    return (s.mode & 0o004) ? 'public' : 'private'
+  }
+
+  // ── Internal ────────────────────────────────────────────────────────────────
+
+  private fullPath(path: string): string {
+    const resolved = resolve(this.root, path)
+    this.assertWithinRoot(resolved)
+    return resolved
+  }
+
+  private assertWithinRoot(resolvedPath: string): void {
+    if (!resolvedPath.startsWith(this.root)) {
+      throw new FilesystemError(
+        'Path traversal detected — resolved path escapes the disk root.',
+        { resolved: resolvedPath, root: this.root },
+      )
+    }
+  }
+
+  private async applyVisibility(fullPath: string, visibility: 'public' | 'private'): Promise<void> {
+    const mode = visibility === 'public' ? 0o644 : 0o600
+    await chmod(fullPath, mode)
+  }
+
+  private entryRelativePath(entry: any, baseDir: string): string {
+    // Bun/Node 20+ Dirent has parentPath or path property
+    const parent: string | undefined = entry.parentPath ?? entry.path
+    if (!parent) return ''
+    return relative(baseDir, parent)
+  }
+}

package/src/drivers/NullDriver.ts

@@ -0,0 +1,35 @@
+import type { FilesystemDriver, PutOptions } from '../contracts/FilesystemDriver.ts'
+
+export class NullDriver implements FilesystemDriver {
+  async exists(_path: string): Promise<boolean> { return false }
+  async get(_path: string): Promise<string | null> { return null }
+  async getBytes(_path: string): Promise<Uint8Array | null> { return null }
+  async stream(_path: string): Promise<ReadableStream | null> { return null }
+
+  async put(_path: string, _contents: string | Uint8Array, _options?: PutOptions): Promise<void> {}
+  async putStream(_path: string, _stream: ReadableStream, _options?: PutOptions): Promise<void> {}
+  async append(_path: string, _contents: string): Promise<void> {}
+  async prepend(_path: string, _contents: string): Promise<void> {}
+
+  async delete(_path: string | string[]): Promise<boolean> { return true }
+  async copy(_from: string, _to: string): Promise<void> {}
+  async move(_from: string, _to: string): Promise<void> {}
+
+  async size(_path: string): Promise<number> { return 0 }
+  async lastModified(_path: string): Promise<number> { return 0 }
+  async mimeType(_path: string): Promise<string | null> { return null }
+  path(filePath: string): string { return filePath }
+
+  url(path: string): string { return path }
+  async temporaryUrl(path: string, _expiration: number): Promise<string> { return path }
+
+  async files(_directory?: string): Promise<string[]> { return [] }
+  async allFiles(_directory?: string): Promise<string[]> { return [] }
+  async directories(_directory?: string): Promise<string[]> { return [] }
+  async allDirectories(_directory?: string): Promise<string[]> { return [] }
+  async makeDirectory(_path: string): Promise<void> {}
+  async deleteDirectory(_directory: string): Promise<boolean> { return true }
+
+  async setVisibility(_path: string, _visibility: 'public' | 'private'): Promise<void> {}
+  async getVisibility(_path: string): Promise<string> { return 'public' }
+}