@foundation0/api 1.1.3 → 1.1.4

package/libs/curl.test.ts

@@ -0,0 +1,130 @@
+import { describe, expect, it } from 'bun:test'
+import { curl } from './curl'
+
+describe('api/libs/curl', () => {
+  const withServer = async <T>(fn: (baseUrl: string) => Promise<T>): Promise<T> => {
+    const server = Bun.serve({
+      port: 0,
+      fetch: async (req) => {
+        const url = new URL(req.url)
+
+        if (url.pathname === '/hello') {
+          return new Response('hello', { headers: { 'x-test': '1' } })
+        }
+
+        if (url.pathname === '/echo') {
+          const body = await req.text()
+          return Response.json({
+            method: req.method,
+            body,
+            contentType: req.headers.get('content-type'),
+            ua: req.headers.get('user-agent'),
+          })
+        }
+
+        if (url.pathname === '/redirect') {
+          return new Response('nope', { status: 302, headers: { location: '/hello' } })
+        }
+
+        return new Response('not found', { status: 404 })
+      },
+    })
+
+    try {
+      return await fn(`http://127.0.0.1:${server.port}`)
+    } finally {
+      server.stop(true)
+    }
+  }
+
+  it('fetches a URL and returns body on stdout', async () => {
+    await withServer(async (baseUrl) => {
+      const result = await curl(`${baseUrl}/hello`)
+      expect(result.exitCode).toBe(0)
+      expect(result.timedOut).toBe(false)
+      expect(result.stdout).toBe('hello')
+      expect(result.results?.[0]?.httpCode).toBe(200)
+    })
+  })
+
+  it('defaults scheme-less host URLs to http://', async () => {
+    await withServer(async (baseUrl) => {
+      const url = baseUrl.replace('http://', '')
+      const result = await curl(`${url}/hello`)
+      expect(result.exitCode).toBe(0)
+      expect(result.stdout).toBe('hello')
+    })
+  })
+
+  it('supports -i to include response headers', async () => {
+    await withServer(async (baseUrl) => {
+      const result = await curl('-i', `${baseUrl}/hello`)
+      expect(result.exitCode).toBe(0)
+      expect(result.stdout).toContain('HTTP/1.1 200')
+      expect(result.stdout.toLowerCase()).toContain('x-test: 1')
+      expect(result.stdout).toContain('hello')
+    })
+  })
+
+  it('supports -d for POST body and defaults method to POST', async () => {
+    await withServer(async (baseUrl) => {
+      const result = await curl('-d', 'a=1', `${baseUrl}/echo`)
+      expect(result.exitCode).toBe(0)
+      const payload = JSON.parse(result.stdout)
+      expect(payload.method).toBe('POST')
+      expect(payload.body).toBe('a=1')
+      expect(payload.contentType).toContain('application/x-www-form-urlencoded')
+    })
+  })
+
+  it('supports -G with -d to apply data as query params', async () => {
+    await withServer(async (baseUrl) => {
+      const result = await curl('-G', '-d', 'a=1', `${baseUrl}/hello`)
+      expect(result.exitCode).toBe(0)
+      expect(result.stdout).toBe('hello')
+    })
+  })
+
+  it('supports -L to follow redirects', async () => {
+    await withServer(async (baseUrl) => {
+      const result = await curl('-L', `${baseUrl}/redirect`)
+      expect(result.exitCode).toBe(0)
+      expect(result.results?.[0]?.redirectCount).toBe(1)
+      expect(result.results?.[0]?.urlEffective).toContain('/hello')
+      expect(result.stdout).toBe('hello')
+    })
+  })
+
+  it('supports -f to fail on HTTP >= 400 and suppress body', async () => {
+    await withServer(async (baseUrl) => {
+      const result = await curl('-f', `${baseUrl}/missing`)
+      expect(result.exitCode).toBe(22)
+      expect(result.stdout).toBe('')
+      expect(result.stderr).toContain('returned error')
+    })
+  })
+
+  it('supports -w to write out %{http_code}', async () => {
+    await withServer(async (baseUrl) => {
+      const result = await curl('-w', '%{http_code}', `${baseUrl}/hello`)
+      expect(result.exitCode).toBe(0)
+      expect(result.stdout).toBe('hello200')
+    })
+  })
+
+  it('accepts trailing tool options object without turning it into a curl arg', async () => {
+    await withServer(async (baseUrl) => {
+      const result = await curl(`${baseUrl}/hello`, { timeoutMs: 10_000 })
+      expect(result.exitCode).toBe(0)
+      expect(result.args).toEqual([`${baseUrl}/hello`])
+    })
+  })
+
+  it('returns usage exit code for unsupported flags', async () => {
+    await withServer(async (baseUrl) => {
+      const result = await curl('--version', `${baseUrl}/hello`)
+      expect(result.exitCode).toBe(2)
+      expect(result.stderr).toContain('Unsupported curl option')
+    })
+  })
+})

package/libs/curl.ts

@@ -0,0 +1,770 @@
+import { Buffer } from 'node:buffer'
+import path from 'node:path'
+
+export type CurlToolOptions = {
+  cwd?: string
+  env?: Record<string, string>
+  timeoutMs?: number
+  stdin?: string | Uint8Array
+}
+
+export type CurlPerRequestResult = {
+  url: string
+  urlEffective: string
+  redirectCount: number
+  httpCode: number
+  headers: Record<string, string>
+  stdout: string
+  stdoutBase64: string
+  stderr: string
+  exitCode: number
+  timedOut: boolean
+  durationMs: number
+}
+
+export type CurlResult = {
+  args: string[]
+  exitCode: number
+  stdout: string
+  stderr: string
+  stdoutBase64: string
+  stderrBase64: string
+  timedOut: boolean
+  results?: CurlPerRequestResult[]
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value)
+
+const parseToolOptions = (value: unknown): CurlToolOptions => {
+  if (!isRecord(value)) return {}
+
+  const env: Record<string, string> | undefined = (() => {
+    if (!isRecord(value.env)) return undefined
+    const out: Record<string, string> = {}
+    for (const [key, entry] of Object.entries(value.env)) {
+      if (typeof key !== 'string' || key.trim().length === 0) continue
+      if (entry === undefined || entry === null) continue
+      out[key] = String(entry)
+    }
+    return Object.keys(out).length > 0 ? out : undefined
+  })()
+
+  const timeoutMs = typeof value.timeoutMs === 'number' && Number.isFinite(value.timeoutMs) && value.timeoutMs > 0
+    ? value.timeoutMs
+    : undefined
+  const cwd = typeof value.cwd === 'string' && value.cwd.trim().length > 0 ? value.cwd.trim() : undefined
+
+  const stdin = (() => {
+    const raw = value.stdin
+    if (typeof raw === 'string') return raw
+    if (raw instanceof Uint8Array) return raw
+    return undefined
+  })()
+
+  return { cwd, env, timeoutMs, stdin }
+}
+
+type CurlConfig = {
+  method: string | null
+  headers: Headers
+  dataParts: Array<{ mode: 'raw' | 'binary' | 'urlencode'; value: string }>
+  formParts: Array<{ name: string; value: string } | { name: string; filePath: string }>
+  followRedirects: boolean
+  maxRedirects: number
+  includeHeaders: boolean
+  headOnly: boolean
+  outputPath: string | null
+  remoteName: boolean
+  silent: boolean
+  showError: boolean
+  verbose: boolean
+  fail: boolean
+  getWithData: boolean
+  user: { username: string; password: string } | null
+  writeOut: string | null
+  timeoutMs: number | null
+}
+
+const defaultConfig = (): CurlConfig => ({
+  method: null,
+  headers: new Headers(),
+  dataParts: [],
+  formParts: [],
+  followRedirects: false,
+  maxRedirects: 50,
+  includeHeaders: false,
+  headOnly: false,
+  outputPath: null,
+  remoteName: false,
+  silent: false,
+  showError: false,
+  verbose: false,
+  fail: false,
+  getWithData: false,
+  user: null,
+  writeOut: null,
+  timeoutMs: null,
+})
+
+const isOptionLike = (token: string): boolean => token.startsWith('-') && token.length > 1
+
+const splitShortCluster = (token: string): string[] => {
+  if (!token.startsWith('-') || token.startsWith('--') || token.length <= 2) return [token]
+  const flags = token.slice(1).split('')
+  return flags.map((flag) => `-${flag}`)
+}
+
+const looksLikeUrl = (token: string): boolean => {
+  if (!token) return false
+  if (token.startsWith('http://') || token.startsWith('https://') || token.startsWith('file://')) return true
+  return /^[a-zA-Z][a-zA-Z0-9+.-]*:\/\//.test(token)
+}
+
+const normalizeUrlToken = (token: string): string => {
+  if (looksLikeUrl(token)) return token
+
+  // curl accepts scheme-less URLs like "example.com" and defaults to http://.
+  const trimmed = token.trim()
+  const looksLikeHost = trimmed === 'localhost'
+    || /^[0-9.]+(?::\d+)?(\/|$)/.test(trimmed)
+    || /^[a-zA-Z0-9.-]+\.[a-zA-Z0-9.-]+(?::\d+)?(\/|$)/.test(trimmed)
+    || /^[a-zA-Z0-9.-]+(?::\d+)(\/|$)/.test(trimmed)
+
+  if (looksLikeHost) return `http://${trimmed}`
+  return token
+}
+
+const resolveOutputPathForUrl = (urlText: string, cwd: string | undefined): string => {
+  const parsed = new URL(urlText)
+  const base = parsed.pathname.split('/').filter(Boolean).pop() ?? 'index.html'
+  return cwd ? path.resolve(cwd, base) : base
+}
+
+const readFileAsText = async (filePath: string): Promise<string> => {
+  const bytes = new Uint8Array(await Bun.file(filePath).arrayBuffer())
+  return Buffer.from(bytes).toString('utf8')
+}
+
+const readFileAsBytes = async (filePath: string): Promise<Uint8Array> =>
+  new Uint8Array(await Bun.file(filePath).arrayBuffer())
+
+const encodeUrlDataPart = (value: string): string => {
+  const index = value.indexOf('=')
+  if (index <= 0) return encodeURIComponent(value)
+  const name = value.slice(0, index)
+  const content = value.slice(index + 1)
+  return `${encodeURIComponent(name)}=${encodeURIComponent(content)}`
+}
+
+const applyDataToUrl = (urlText: string, data: string): string => {
+  const url = new URL(urlText)
+  const params = new URLSearchParams(url.search)
+  const pairs = data.split('&').filter((entry) => entry.length > 0)
+  for (const pair of pairs) {
+    const index = pair.indexOf('=')
+    if (index < 0) {
+      params.append(decodeURIComponent(pair), '')
+    } else {
+      const k = pair.slice(0, index)
+      const v = pair.slice(index + 1)
+      params.append(decodeURIComponent(k), decodeURIComponent(v))
+    }
+  }
+  url.search = params.toString()
+  return url.toString()
+}
+
+const buildHeaderBlock = (status: number, statusText: string, headers: Headers): string => {
+  const lines: string[] = []
+  lines.push(`HTTP/1.1 ${status} ${statusText}`.trim())
+  for (const [key, value] of headers.entries()) {
+    lines.push(`${key}: ${value}`)
+  }
+  return `${lines.join('\r\n')}\r\n\r\n`
+}
+
+const curlExitCode = {
+  ok: 0,
+  usage: 2,
+  couldNotResolveHost: 6,
+  httpReturnedError: 22,
+  operationTimeout: 28,
+} as const
+
+const formatWriteOut = (template: string, info: { httpCode: number; urlEffective: string; timeTotalSeconds: number }) =>
+  template
+    .replaceAll('%{http_code}', String(info.httpCode).padStart(3, '0'))
+    .replaceAll('%{url_effective}', info.urlEffective)
+    .replaceAll('%{time_total}', info.timeTotalSeconds.toFixed(3))
+
+const parseCurlArgs = async (
+  rawArgs: string[],
+  toolOptions: CurlToolOptions,
+): Promise<{ config: CurlConfig; urls: string[] }> => {
+  const config = defaultConfig()
+  const urls: string[] = []
+
+  const args: string[] = []
+  for (const token of rawArgs) {
+    if (token === '--') {
+      args.push(token)
+      continue
+    }
+    if (token.startsWith('-') && !token.startsWith('--') && token.length > 2) {
+      args.push(...splitShortCluster(token))
+      continue
+    }
+    args.push(token)
+  }
+
+  const nextValue = (index: number): string => {
+    if (index + 1 >= args.length) throw new Error(`Missing value for ${args[index]}`)
+    return args[index + 1]
+  }
+
+  for (let i = 0; i < args.length; i += 1) {
+    const token = args[i]
+    if (token === '--') {
+      urls.push(...args.slice(i + 1))
+      break
+    }
+
+    if (!isOptionLike(token)) {
+      urls.push(normalizeUrlToken(token))
+      continue
+    }
+
+    if (token === '-X' || token === '--request') {
+      const value = nextValue(i)
+      config.method = value.toUpperCase()
+      i += 1
+      continue
+    }
+
+    if (token.startsWith('-X') && token.length > 2) {
+      config.method = token.slice(2).toUpperCase()
+      continue
+    }
+
+    if (token === '-H' || token === '--header') {
+      const value = nextValue(i)
+      const idx = value.indexOf(':')
+      if (idx < 0) throw new Error(`Invalid header: ${value}`)
+      const key = value.slice(0, idx).trim()
+      const val = value.slice(idx + 1).trim()
+      config.headers.append(key, val)
+      i += 1
+      continue
+    }
+
+    if (token === '-A' || token === '--user-agent') {
+      const value = nextValue(i)
+      config.headers.set('user-agent', value)
+      i += 1
+      continue
+    }
+
+    if (token === '-e' || token === '--referer') {
+      const value = nextValue(i)
+      config.headers.set('referer', value)
+      i += 1
+      continue
+    }
+
+    if (token === '-u' || token === '--user') {
+      const value = nextValue(i)
+      const idx = value.indexOf(':')
+      const username = idx >= 0 ? value.slice(0, idx) : value
+      const password = idx >= 0 ? value.slice(idx + 1) : ''
+      config.user = { username, password }
+      i += 1
+      continue
+    }
+
+    if (token === '-L' || token === '--location') {
+      config.followRedirects = true
+      continue
+    }
+
+    if (token === '--max-redirs') {
+      const value = nextValue(i)
+      const parsed = Number(value)
+      if (!Number.isInteger(parsed) || parsed < 0) throw new Error(`Invalid --max-redirs: ${value}`)
+      config.maxRedirects = parsed
+      i += 1
+      continue
+    }
+
+    if (token === '-i' || token === '--include') {
+      config.includeHeaders = true
+      continue
+    }
+
+    if (token === '-I' || token === '--head') {
+      config.headOnly = true
+      config.method = 'HEAD'
+      continue
+    }
+
+    if (token === '-s' || token === '--silent') {
+      config.silent = true
+      continue
+    }
+
+    if (token === '-S' || token === '--show-error') {
+      config.showError = true
+      continue
+    }
+
+    if (token === '-v' || token === '--verbose') {
+      config.verbose = true
+      continue
+    }
+
+    if (token === '-f' || token === '--fail') {
+      config.fail = true
+      continue
+    }
+
+    if (token === '-G' || token === '--get') {
+      config.getWithData = true
+      continue
+    }
+
+    if (token === '-m' || token === '--max-time') {
+      const value = nextValue(i)
+      const seconds = Number(value)
+      if (!Number.isFinite(seconds) || seconds <= 0) throw new Error(`Invalid --max-time: ${value}`)
+      config.timeoutMs = Math.floor(seconds * 1000)
+      i += 1
+      continue
+    }
+
+    if (token === '-o' || token === '--output') {
+      const value = nextValue(i)
+      config.outputPath = value
+      i += 1
+      continue
+    }
+
+    if (token === '-O' || token === '--remote-name') {
+      config.remoteName = true
+      continue
+    }
+
+    if (token === '-w' || token === '--write-out') {
+      const value = nextValue(i)
+      config.writeOut = value
+      i += 1
+      continue
+    }
+
+    if (token === '--json') {
+      const value = nextValue(i)
+      config.headers.set('content-type', 'application/json')
+      config.dataParts.push({ mode: 'raw', value })
+      if (!config.method) config.method = 'POST'
+      i += 1
+      continue
+    }
+
+    const handleData = async (mode: 'raw' | 'binary' | 'urlencode'): Promise<void> => {
+      const value = nextValue(i)
+      const resolved = (() => {
+        if (value === '@-') {
+          const stdin = toolOptions.stdin
+          if (stdin === undefined) throw new Error('curl: @- requires tool options { stdin }')
+          return typeof stdin === 'string' ? stdin : Buffer.from(stdin).toString('utf8')
+        }
+        if (value.startsWith('@')) {
+          const filePath = value.slice(1)
+          const resolvedPath = toolOptions.cwd ? path.resolve(toolOptions.cwd, filePath) : filePath
+          return readFileAsText(resolvedPath)
+        }
+        return value
+      })()
+
+      const materialized = typeof resolved === 'string' ? resolved : await resolved
+      config.dataParts.push({ mode, value: materialized })
+      if (!config.method) config.method = 'POST'
+      i += 1
+    }
+
+    if (token === '-d' || token === '--data' || token === '--data-raw') {
+      await handleData('raw')
+      continue
+    }
+
+    if (token === '--data-binary') {
+      await handleData('binary')
+      continue
+    }
+
+    if (token === '--data-urlencode') {
+      await handleData('urlencode')
+      continue
+    }
+
+    const handleForm = async (): Promise<void> => {
+      const value = nextValue(i)
+      const idx = value.indexOf('=')
+      if (idx <= 0) throw new Error(`Invalid form field: ${value}`)
+      const name = value.slice(0, idx)
+      const content = value.slice(idx + 1)
+      if (content.startsWith('@')) {
+        const filePath = content.slice(1)
+        const resolvedPath = toolOptions.cwd ? path.resolve(toolOptions.cwd, filePath) : filePath
+        config.formParts.push({ name, filePath: resolvedPath })
+      } else {
+        config.formParts.push({ name, value: content })
+      }
+      if (!config.method) config.method = 'POST'
+      i += 1
+    }
+
+    if (token === '-F' || token === '--form') {
+      await handleForm()
+      continue
+    }
+
+    if (token === '--url') {
+      const value = nextValue(i)
+      urls.push(normalizeUrlToken(value))
+      i += 1
+      continue
+    }
+
+    throw new Error(`Unsupported curl option: ${token}`)
+  }
+
+  // curl defaults to stdout; preserve tool option timeoutMs as a fallback.
+  if (config.timeoutMs === null && typeof toolOptions.timeoutMs === 'number') {
+    config.timeoutMs = toolOptions.timeoutMs
+  }
+
+  return { config, urls }
+}
+
+const toHeaderRecord = (headers: Headers): Record<string, string> => {
+  const out: Record<string, string> = {}
+  for (const [k, v] of headers.entries()) out[k] = v
+  return out
+}
+
+const buildRequestBody = async (
+  config: CurlConfig,
+): Promise<{ body: BodyInit | null; method: string }> => {
+  const method = config.method ?? (config.dataParts.length > 0 || config.formParts.length > 0 ? 'POST' : 'GET')
+
+  if (config.headOnly) return { body: null, method: 'HEAD' }
+
+  if (config.formParts.length > 0) {
+    const form = new FormData()
+    for (const part of config.formParts) {
+      if ('filePath' in part) {
+        const fileName = path.basename(part.filePath)
+        form.append(part.name, Bun.file(part.filePath), fileName)
+      } else {
+        form.append(part.name, part.value)
+      }
+    }
+    return { body: form, method }
+  }
+
+  if (config.dataParts.length > 0) {
+    const rendered = config.dataParts.map((part) => {
+      if (part.mode === 'urlencode') return encodeUrlDataPart(part.value)
+      return part.value
+    }).join('&')
+    return { body: rendered, method }
+  }
+
+  return { body: null, method }
+}
+
+const fetchWithRedirects = async (
+  initialUrl: string,
+  init: RequestInit,
+  followRedirects: boolean,
+  maxRedirects: number,
+  controller: AbortController,
+): Promise<{ response: Response; urlEffective: string; redirectCount: number }> => {
+  if (!followRedirects) {
+    const response = await fetch(initialUrl, { ...init, redirect: 'manual', signal: controller.signal })
+    return { response, urlEffective: initialUrl, redirectCount: 0 }
+  }
+
+  let url = initialUrl
+  let redirectCount = 0
+  let currentInit = { ...init, redirect: 'manual' as const }
+
+  while (true) {
+    const response = await fetch(url, { ...currentInit, signal: controller.signal })
+    const status = response.status
+    const location = response.headers.get('location')
+    const isRedirect = status >= 300 && status < 400 && location
+    if (!isRedirect) {
+      return { response, urlEffective: url, redirectCount }
+    }
+
+    if (redirectCount >= maxRedirects) {
+      return { response, urlEffective: url, redirectCount }
+    }
+
+    const nextUrl = new URL(location, url).toString()
+    redirectCount += 1
+
+    if (status === 303 || status === 301 || status === 302) {
+      const method = (currentInit.method ?? 'GET').toUpperCase()
+      if (method !== 'GET' && method !== 'HEAD') {
+        currentInit = { ...currentInit, method: 'GET', body: undefined }
+      }
+    }
+
+    url = nextUrl
+  }
+}
+
+const buildVerboseDump = (url: string, init: RequestInit): string => {
+  const lines: string[] = []
+  lines.push(`> ${init.method ?? 'GET'} ${url}`)
+  const headers = init.headers instanceof Headers
+    ? init.headers
+    : new Headers(init.headers as HeadersInit | undefined)
+  for (const [k, v] of headers.entries()) {
+    lines.push(`> ${k}: ${v}`)
+  }
+  return `${lines.join('\n')}\n`
+}
+
+export const curl = async (...raw: unknown[]): Promise<CurlResult> => {
+  const trailing = raw.length > 0 ? raw[raw.length - 1] : undefined
+  const toolOptions = parseToolOptions(trailing)
+  const args = isRecord(trailing) ? raw.slice(0, -1) : raw
+  const rawArgs = args.map((arg) => String(arg))
+
+  const startedAll = performance.now()
+
+  const stderrChunks: string[] = []
+  const stdoutChunks: Uint8Array[] = []
+
+  try {
+    const { config, urls } = await parseCurlArgs(rawArgs, toolOptions)
+    const materializedUrls = urls.filter((u) => u.trim().length > 0)
+
+    if (materializedUrls.length === 0) {
+      return {
+        args: rawArgs,
+        exitCode: curlExitCode.usage,
+        stdout: '',
+        stderr: 'curl: no URL specified',
+        stdoutBase64: '',
+        stderrBase64: Buffer.from('curl: no URL specified', 'utf8').toString('base64'),
+        timedOut: false,
+      }
+    }
+
+    const results: CurlPerRequestResult[] = []
+    let finalExitCode = curlExitCode.ok
+    let anyTimedOut = false
+
+    for (const url of materializedUrls) {
+      const started = performance.now()
+      const controller = new AbortController()
+      const timeoutMs = config.timeoutMs ?? null
+      const timeoutId = timeoutMs ? setTimeout(() => controller.abort(), timeoutMs) : null
+
+      let perStdoutBytes = new Uint8Array()
+      let perStderr = ''
+      let exitCode = curlExitCode.ok
+      let timedOut = false
+      let response: Response | null = null
+      let urlEffective = url
+      let redirectCount = 0
+
+      try {
+        const isFileScheme = url.startsWith('file://')
+        const isAbsolutePath = !looksLikeUrl(url) && path.isAbsolute(url)
+
+        if (isFileScheme || isAbsolutePath) {
+          const filePath = isFileScheme ? decodeURIComponent(new URL(url).pathname) : url
+          const resolvedPath = toolOptions.cwd ? path.resolve(toolOptions.cwd, filePath) : filePath
+          const bytes = await readFileAsBytes(resolvedPath)
+          perStdoutBytes = bytes
+          exitCode = curlExitCode.ok
+          urlEffective = isFileScheme ? url : `file://${resolvedPath.replaceAll('\\', '/')}`
+        } else {
+          if (!looksLikeUrl(url)) {
+            throw new Error(`URL missing scheme: ${url}`)
+          }
+
+          const { body, method } = await buildRequestBody(config)
+
+          const headers = new Headers(config.headers)
+          if (config.user && !headers.has('authorization')) {
+            const token = Buffer.from(`${config.user.username}:${config.user.password}`, 'utf8').toString('base64')
+            headers.set('authorization', `Basic ${token}`)
+          }
+          if (config.dataParts.length > 0 && !headers.has('content-type')) {
+            headers.set('content-type', 'application/x-www-form-urlencoded')
+          }
+
+          const init: RequestInit = { method, headers, body: body ?? undefined }
+
+          if (config.verbose) {
+            perStderr += buildVerboseDump(url, init)
+          }
+
+          let requestUrl = url
+          if (config.getWithData && config.dataParts.length > 0) {
+            const encoded = config.dataParts.map((part) => {
+              if (part.mode === 'urlencode') return encodeUrlDataPart(part.value)
+              return part.value
+            }).join('&')
+            requestUrl = applyDataToUrl(url, encoded)
+          }
+
+          const fetched = await fetchWithRedirects(
+            requestUrl,
+            init,
+            config.followRedirects,
+            config.maxRedirects,
+            controller,
+          )
+          response = fetched.response
+          urlEffective = fetched.urlEffective
+          redirectCount = fetched.redirectCount
+
+          const headerBlock = buildHeaderBlock(response.status, response.statusText, response.headers)
+          const headerBytes = new Uint8Array(Buffer.from(headerBlock, 'utf8'))
+
+          const bodyBytes = config.headOnly
+            ? new Uint8Array()
+            : new Uint8Array(await response.arrayBuffer())
+
+          const shouldSuppressBody = config.fail && response.status >= 400
+          if (shouldSuppressBody) {
+            exitCode = curlExitCode.httpReturnedError
+            const msg = `curl: (22) The requested URL returned error: ${response.status}`
+            perStderr += `${msg}\n`
+            perStdoutBytes = config.includeHeaders ? headerBytes : new Uint8Array()
+          } else {
+            perStdoutBytes = config.includeHeaders || config.headOnly
+              ? new Uint8Array([...headerBytes, ...bodyBytes])
+              : bodyBytes
+          }
+        }
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error)
+        if (/aborted/i.test(message) || /abort/i.test(message)) {
+          timedOut = true
+          anyTimedOut = true
+          exitCode = curlExitCode.operationTimeout
+          perStderr += `curl: (28) Operation timed out${timeoutMs ? ` after ${timeoutMs} milliseconds` : ''}\n`
+        } else if (/missing scheme/i.test(message) || /invalid url/i.test(message)) {
+          exitCode = curlExitCode.usage
+          perStderr += `curl: (2) ${message}\n`
+        } else {
+          // Best-effort mapping; fetch failures are often DNS/connection.
+          exitCode = curlExitCode.couldNotResolveHost
+          perStderr += `curl: (6) ${message}\n`
+        }
+      } finally {
+        if (timeoutId) clearTimeout(timeoutId)
+      }
+
+      const durationMs = performance.now() - started
+
+      const httpCode = response?.status ?? 0
+      const headers = response ? toHeaderRecord(response.headers) : {}
+
+      const timeTotalSeconds = durationMs / 1000
+      const writeOut = config.writeOut
+        ? formatWriteOut(config.writeOut, { httpCode, urlEffective, timeTotalSeconds })
+        : ''
+
+      const perStdoutWithWriteOut = writeOut
+        ? new Uint8Array([...perStdoutBytes, ...new Uint8Array(Buffer.from(writeOut, 'utf8'))])
+        : perStdoutBytes
+
+      if (!config.silent) {
+        // We do not implement progress meter; keep stderr clean unless verbose/error.
+      }
+
+      if (!config.silent || config.showError) {
+        // For compatibility, keep stderr behavior: show errors by default, suppress under -s unless -S.
+        // If silent is set and showError is not, drop stderr.
+      }
+
+      const effectiveStderr = config.silent && !config.showError ? '' : perStderr
+      stderrChunks.push(effectiveStderr)
+
+      if (config.outputPath || config.remoteName) {
+        const outPath = config.outputPath
+          ? (toolOptions.cwd ? path.resolve(toolOptions.cwd, config.outputPath) : config.outputPath)
+          : resolveOutputPathForUrl(urlEffective, toolOptions.cwd)
+        await Bun.write(outPath, perStdoutWithWriteOut)
+      } else {
+        stdoutChunks.push(perStdoutWithWriteOut)
+      }
+
+      results.push({
+        url,
+        urlEffective,
+        redirectCount,
+        httpCode,
+        headers,
+        stdout: Buffer.from(perStdoutWithWriteOut).toString('utf8'),
+        stdoutBase64: Buffer.from(perStdoutWithWriteOut).toString('base64'),
+        stderr: effectiveStderr,
+        exitCode,
+        timedOut,
+        durationMs,
+      })
+
+      finalExitCode = finalExitCode === 0 ? exitCode : finalExitCode
+    }
+
+    const stdoutBytes = stdoutChunks.length === 0
+      ? new Uint8Array()
+      : new Uint8Array(stdoutChunks.reduce((acc, chunk) => acc + chunk.length, 0))
+
+    if (stdoutChunks.length > 0) {
+      let offset = 0
+      for (const chunk of stdoutChunks) {
+        stdoutBytes.set(chunk, offset)
+        offset += chunk.length
+      }
+    }
+
+    const stdout = Buffer.from(stdoutBytes).toString('utf8')
+    const stderr = stderrChunks.join('')
+
+    return {
+      args: rawArgs,
+      exitCode: finalExitCode,
+      stdout,
+      stderr,
+      stdoutBase64: Buffer.from(stdoutBytes).toString('base64'),
+      stderrBase64: Buffer.from(stderr, 'utf8').toString('base64'),
+      timedOut: anyTimedOut,
+      results,
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    const stderr = `curl: (2) ${message}`
+    return {
+      args: rawArgs,
+      exitCode: curlExitCode.usage,
+      stdout: '',
+      stderr,
+      stdoutBase64: '',
+      stderrBase64: Buffer.from(stderr, 'utf8').toString('base64'),
+      timedOut: false,
+    }
+  } finally {
+    const elapsed = performance.now() - startedAll
+    void elapsed
+  }
+}

package/net.ts

@@ -0,0 +1,170 @@
+import { curl as curlImpl, type CurlResult, type CurlToolOptions } from './libs/curl'
+
+export type NetCurlResult = CurlResult
+
+type NetCurlRequest = {
+  url?: string | string[]
+  urls?: string[]
+  method?: string
+  headers?: Record<string, string>
+  body?: string
+  data?: string | string[]
+  json?: unknown
+  form?: Record<string, string>
+  followRedirects?: boolean
+  location?: boolean
+  maxRedirects?: number
+  includeHeaders?: boolean
+  head?: boolean
+  user?: string
+  output?: string
+  remoteName?: boolean
+  fail?: boolean
+  silent?: boolean
+  showError?: boolean
+  verbose?: boolean
+  writeOut?: string
+  maxTimeSeconds?: number
+  get?: boolean
+  timeoutMs?: number
+  cwd?: string
+  env?: Record<string, string>
+  stdin?: string | Uint8Array | number[]
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value)
+
+const toStringRecord = (value: unknown): Record<string, string> | null => {
+  if (!isRecord(value)) return null
+  const out: Record<string, string> = {}
+  for (const [k, v] of Object.entries(value)) {
+    if (v === undefined || v === null) continue
+    out[k] = String(v)
+  }
+  return out
+}
+
+const parseRequest = (value: unknown): NetCurlRequest | null => {
+  if (!isRecord(value)) return null
+  if ('args' in value) return null
+  if (!('url' in value) && !('urls' in value)) return null
+  return value as NetCurlRequest
+}
+
+const toUint8Array = (value: unknown): Uint8Array | undefined => {
+  if (value instanceof Uint8Array) return value
+  if (Array.isArray(value)) {
+    const bytes = value.map((entry) => Number(entry)).filter((n) => Number.isFinite(n) && n >= 0 && n <= 255)
+    return new Uint8Array(bytes)
+  }
+  return undefined
+}
+
+const buildCurlArgsFromRequest = (request: NetCurlRequest): { args: string[]; toolOptions: CurlToolOptions } => {
+  const args: string[] = []
+
+  const urls = (() => {
+    if (Array.isArray(request.urls)) return request.urls.map(String)
+    if (Array.isArray(request.url)) return request.url.map(String)
+    if (typeof request.url === 'string') return [request.url]
+    return []
+  })()
+
+  const method = typeof request.method === 'string' && request.method.trim().length > 0
+    ? request.method.trim().toUpperCase()
+    : null
+
+  if (request.includeHeaders === true) args.push('-i')
+  if (request.head === true || method === 'HEAD') args.push('-I')
+
+  if (request.followRedirects === true || request.location === true) args.push('-L')
+  if (typeof request.maxRedirects === 'number' && Number.isInteger(request.maxRedirects) && request.maxRedirects >= 0) {
+    args.push('--max-redirs', String(request.maxRedirects))
+  }
+
+  if (request.fail === true) args.push('-f')
+  if (request.silent === true) args.push('-s')
+  if (request.showError === true) args.push('-S')
+  if (request.verbose === true) args.push('-v')
+
+  if (request.get === true) args.push('-G')
+
+  if (typeof request.user === 'string' && request.user.trim().length > 0) {
+    args.push('-u', request.user.trim())
+  }
+
+  const headers = toStringRecord(request.headers)
+  if (headers) {
+    for (const [k, v] of Object.entries(headers)) {
+      args.push('-H', `${k}: ${v}`)
+    }
+  }
+
+  if (typeof request.writeOut === 'string') args.push('-w', request.writeOut)
+  if (typeof request.output === 'string' && request.output.trim().length > 0) args.push('-o', request.output.trim())
+  if (request.remoteName === true) args.push('-O')
+
+  if (typeof request.maxTimeSeconds === 'number' && Number.isFinite(request.maxTimeSeconds) && request.maxTimeSeconds > 0) {
+    args.push('--max-time', String(request.maxTimeSeconds))
+  }
+
+  if (method && method !== 'HEAD' && request.head !== true) {
+    args.push('-X', method)
+  }
+
+  if (typeof request.body === 'string') {
+    args.push('--data-raw', request.body)
+  }
+
+  const data = request.data
+  if (typeof data === 'string') {
+    args.push('-d', data)
+  } else if (Array.isArray(data)) {
+    for (const entry of data) args.push('-d', String(entry))
+  }
+
+  if (request.json !== undefined) {
+    const rendered = typeof request.json === 'string' ? request.json : JSON.stringify(request.json)
+    args.push('--json', rendered)
+  }
+
+  if (isRecord(request.form)) {
+    for (const [k, v] of Object.entries(request.form)) {
+      if (v === undefined || v === null) continue
+      args.push('-F', `${k}=${String(v)}`)
+    }
+  }
+
+  args.push(...urls)
+
+  const toolOptions: CurlToolOptions = {
+    timeoutMs: typeof request.timeoutMs === 'number' && Number.isFinite(request.timeoutMs) && request.timeoutMs > 0
+      ? request.timeoutMs
+      : undefined,
+    cwd: typeof request.cwd === 'string' && request.cwd.trim().length > 0 ? request.cwd.trim() : undefined,
+    env: toStringRecord(request.env) ?? undefined,
+    stdin: typeof request.stdin === 'string' ? request.stdin : toUint8Array(request.stdin),
+  }
+
+  return { args, toolOptions }
+}
+
+export const curl = async (...rawArgs: unknown[]): Promise<CurlResult> => {
+  const request = rawArgs.length === 1 ? parseRequest(rawArgs[0]) : null
+  if (request) {
+    const { args, toolOptions } = buildCurlArgsFromRequest(request)
+    return curlImpl(...args, toolOptions)
+  }
+
+  const stringArgCount = rawArgs.filter((arg) => typeof arg === 'string').length
+  if (stringArgCount === 0 && rawArgs.length === 1 && isRecord(rawArgs[0])) {
+    const maybe = rawArgs[0] as Record<string, unknown>
+    if ('method' in maybe || 'headers' in maybe || 'body' in maybe || 'data' in maybe || 'json' in maybe) {
+      const { args, toolOptions } = buildCurlArgsFromRequest(maybe as NetCurlRequest)
+      return curlImpl(...args, toolOptions)
+    }
+  }
+
+  return curlImpl(...rawArgs)
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foundation0/api",
-  "version": "1.1.3",
+  "version": "1.1.4",
   "description": "Foundation 0 API",
   "type": "module",
   "bin": {
@@ -18,8 +18,10 @@
   "files": [
     "agents.ts",
     "git.ts",
+    "net.ts",
     "taskgraph-parser.ts",
     "projects.ts",
+    "libs",
     "mcp"
   ],
   "publishConfig": {
@@ -32,7 +34,7 @@
   },
   "scripts": {
     "mcp": "bun run mcp/cli.ts",
-    "test": "echo \"Error: no test specified\" && exit 1",
+    "test": "bun test",
     "deploy": "pnpm publish --access public",
     "version:patch": "pnpm version patch && git commit -am \"Bump version to %s\"",
     "version:minor": "pnpm version minor && git commit -am \"Bump version to %s\"",