@softize/opus 8.6.6

package/src/storage/drivers/s3.ts

@@ -0,0 +1,117 @@
+/**
+ * @softize/opus/storage/s3 — driver S3-compatível (EXPERIMENTAL).
+ *
+ * Funciona com AWS S3 e compatíveis (MinIO, R2, Backblaze…): o consumidor
+ * constrói o `S3Client` (região/endpoint/credenciais são dele) e o driver só
+ * opera bucket+key. Peer OPCIONAL: `@aws-sdk/client-s3` (+ `s3-request-presigner`
+ * pra `url()`) — importados sob demanda, quem não usa o driver não os instala.
+ */
+
+import type { StorageAdapter, StorageObject, StoragePutOptions } from '../../core/index.ts'
+import { normalizeKey } from '../index.ts'
+
+/** O subset do S3Client que o driver usa (injetável em teste). */
+export interface S3ClientLike {
+  send(command: unknown): Promise<unknown>
+}
+
+export interface S3StorageOptions {
+  /** Cliente S3 (AWS SDK v3) — o consumidor o constrói e é dono da config/credencial. */
+  client: S3ClientLike
+  bucket: string
+  /** Prefixo lógico dentro do bucket (ex.: `uploads`). */
+  prefix?: string
+  /** Validade default da URL assinada (default 900s = 15 min). */
+  urlExpiresInSeconds?: number
+  /** Nome do adapter (default 's3'). */
+  name?: string
+  /**
+   * Assinador de URL (injetável em teste). Default: `getSignedUrl` do
+   * `@aws-sdk/s3-request-presigner`, importado sob demanda.
+   */
+  presign?: (client: S3ClientLike, command: unknown, opts: { expiresIn: number }) => Promise<string>
+}
+
+// Import sob demanda do SDK (peer opcional): cacheado após o primeiro uso.
+let sdkPromise: Promise<typeof import('@aws-sdk/client-s3')> | null = null
+function sdk(): Promise<typeof import('@aws-sdk/client-s3')> {
+  sdkPromise ??= import('@aws-sdk/client-s3').catch(() => {
+    sdkPromise = null
+    throw new Error('storage/s3 precisa do peer @aws-sdk/client-s3 — `pnpm add @aws-sdk/client-s3`.')
+  })
+  return sdkPromise
+}
+
+async function defaultPresign(
+  client: S3ClientLike,
+  command: unknown,
+  opts: { expiresIn: number },
+): Promise<string> {
+  let presigner: typeof import('@aws-sdk/s3-request-presigner')
+  try {
+    presigner = await import('@aws-sdk/s3-request-presigner')
+  } catch {
+    throw new Error(
+      'storage/s3 url() precisa do peer @aws-sdk/s3-request-presigner — `pnpm add @aws-sdk/s3-request-presigner`.',
+    )
+  }
+  // O tipo real exige o S3Client concreto; o subset injetável cobre os testes.
+  return presigner.getSignedUrl(client as never, command as never, opts)
+}
+
+export function s3Storage(options: S3StorageOptions): StorageAdapter {
+  const prefix = options.prefix?.replace(/^\/+|\/+$/g, '')
+  const presign = options.presign ?? defaultPresign
+
+  function keyOf(key: string): string {
+    const k = normalizeKey(key)
+    return prefix !== undefined && prefix.length > 0 ? `${prefix}/${k}` : k
+  }
+
+  return {
+    name: options.name ?? 's3',
+    kind: 'storage',
+
+    async put(key: string, data: Uint8Array, opts?: StoragePutOptions): Promise<void> {
+      const { PutObjectCommand } = await sdk()
+      await options.client.send(
+        new PutObjectCommand({
+          Bucket: options.bucket,
+          Key: keyOf(key),
+          Body: data,
+          ...(opts?.contentType !== undefined ? { ContentType: opts.contentType } : {}),
+        }),
+      )
+    },
+
+    async get(key: string): Promise<StorageObject | null> {
+      const { GetObjectCommand } = await sdk()
+      let response: { Body?: { transformToByteArray(): Promise<Uint8Array> }; ContentType?: string }
+      try {
+        response = (await options.client.send(new GetObjectCommand({ Bucket: options.bucket, Key: keyOf(key) }))) as never
+      } catch (err) {
+        // NoSuchKey/NotFound = não existe (contrato do get); o resto propaga.
+        const name = (err as { name?: string }).name
+        if (name === 'NoSuchKey' || name === 'NotFound') return null
+        throw err
+      }
+      if (response.Body === undefined) return null
+      const data = await response.Body.transformToByteArray()
+      return { data, ...(response.ContentType !== undefined ? { contentType: response.ContentType } : {}) }
+    },
+
+    async delete(key: string): Promise<void> {
+      const { DeleteObjectCommand } = await sdk()
+      // DeleteObject no S3 já é idempotente (204 mesmo sem o objeto).
+      await options.client.send(new DeleteObjectCommand({ Bucket: options.bucket, Key: keyOf(key) }))
+    },
+
+    async url(key: string, opts?: { expiresInSeconds?: number }): Promise<string> {
+      const { GetObjectCommand } = await sdk()
+      const command = new GetObjectCommand({ Bucket: options.bucket, Key: keyOf(key) })
+      return presign(options.client, command, {
+        expiresIn: opts?.expiresInSeconds ?? options.urlExpiresInSeconds ?? 900,
+      })
+    },
+  }
+}

package/src/storage/index.ts

@@ -0,0 +1,27 @@
+/**
+ * @softize/opus/storage — helpers compartilhados dos drivers de storage.
+ *
+ * EXPERIMENTAL. O contrato (`StorageAdapter`) vive no core; drivers em
+ * `storage/fs` (disco local) e `storage/s3` (S3-compatível). A superfície é a
+ * mínima de backoffice (put/get/delete/url) e cresce por reincidência — não por
+ * especulação (streams, list e metadata ricos entram quando um caso real cobrar).
+ */
+
+export type { StorageAdapter, StoragePutOptions, StorageObject } from '../core/index.ts'
+
+/**
+ * Normaliza e valida uma key de storage: caminho lógico relativo, sem traversal.
+ * Rejeita absoluto, `..`, backslash e segmento vazio — a MESMA régua em todo
+ * driver (o fs depende disso pra não escapar do root; o s3 herda a disciplina).
+ */
+export function normalizeKey(key: string): string {
+  const k = key.trim()
+  if (k.length === 0) throw new Error('Key de storage vazia.')
+  if (k.includes('\\')) throw new Error(`Key de storage com backslash: "${key}" (use "/").`)
+  if (k.startsWith('/')) throw new Error(`Key de storage absoluta: "${key}" (use caminho relativo).`)
+  const parts = k.split('/')
+  if (parts.some((p) => p === '' || p === '.' || p === '..')) {
+    throw new Error(`Key de storage inválida: "${key}" (sem "..", "." nem segmento vazio).`)
+  }
+  return parts.join('/')
+}

package/src/testing/fake.ts

@@ -0,0 +1,298 @@
+/**
+ * `fake` — dado sintético DETERMINÍSTICO a partir de um schema zod. É a matéria-prima do
+ * modo design: um `mockHandler` devolve `fake(entity)`/`fakeMany(entity, n)` e o preview mostra
+ * a UI com dado realista, sem backend nem banco (o design-mode do runtime nem toca `ctx.db`).
+ *
+ * DETERMINISMO: PRNG próprio semeado (mulberry32) — mesma `seed` → mesma saída, sempre. Nunca
+ * `Math.random` (o preview tem que ser reproduzível entre execuções). O default é semeado por
+ * um valor fixo; `fakeMany` varia a seed por índice (itens diferentes, estáveis).
+ *
+ * VALIDADE: a saída satisfaz o schema (`safeParse` passa) pros checks comuns — min/max/int/
+ * length, enum/literal, e formatos por CHECK (email é length-aware; uuid/url/datetime têm
+ * tamanho próprio, então um length CONFLITANTE com esses é schema contraditório, sem valor
+ * válido — aceito como tal). Formato por NOME de campo (telefone, cpf, data…) é só PALPITE:
+ * havendo length/min/max, a restrição vence o palpite. Refinamentos (`.refine`, `.regex`,
+ * `.multipleOf`) são caixa-preta — sem garantia; use schemas de contrato/entidade normais.
+ *
+ * REALISMO: heurística por check do zod primeiro, depois pelo NOME do campo (email, nome, id,
+ * data, telefone, cpf/cnpj, descrição…) — com sabor pt-BR, que é quem consome (GB).
+ */
+import { z, type ZodTypeAny } from 'zod'
+
+export interface FakeOptions {
+  /** Semente do PRNG. Mesma seed → mesma saída. Default: 1. Aceita string (hasheada). */
+  seed?: number | string
+}
+
+// ── PRNG determinístico ─────────────────────────────────────────────────────────
+
+function mulberry32(seed: number): () => number {
+  let a = seed >>> 0
+  return () => {
+    a = (a + 0x6d2b79f5) | 0
+    let t = Math.imul(a ^ (a >>> 15), 1 | a)
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296
+  }
+}
+
+function hashStr(s: string): number {
+  let h = 2166136261
+  for (let i = 0; i < s.length; i++) {
+    h ^= s.charCodeAt(i)
+    h = Math.imul(h, 16777619)
+  }
+  return h >>> 0
+}
+
+interface Rng {
+  next: () => number
+}
+const rint = (r: Rng, min: number, max: number): number => min + Math.floor(r.next() * (max - min + 1))
+const rpick = <T>(r: Rng, arr: readonly T[]): T => arr[Math.floor(r.next() * arr.length)] ?? arr[0]!
+
+// ── Pools pt-BR ─────────────────────────────────────────────────────────────────
+
+const FIRST = ['Ana', 'Bruno', 'Carla', 'Diego', 'Elena', 'Felipe', 'Gabriela', 'Hugo', 'Inês', 'João', 'Larissa', 'Marcos', 'Natália', 'Otávio', 'Paula', 'Rafael', 'Sofia', 'Tiago', 'Vitória', 'Yasmin']
+const LAST = ['Silva', 'Souza', 'Oliveira', 'Santos', 'Pereira', 'Costa', 'Almeida', 'Lima', 'Gomes', 'Ribeiro', 'Carvalho', 'Fernandes', 'Araújo', 'Melo']
+const WORDS = ['relatório', 'unidade', 'evento', 'proposta', 'cliente', 'veículo', 'agenda', 'pedido', 'campanha', 'lead', 'serviço', 'peça', 'garantia', 'departamento']
+
+function fullName(r: Rng): string {
+  return `${rpick(r, FIRST)} ${rpick(r, LAST)}`
+}
+function slug(s: string): string {
+  return s
+    .normalize('NFD')
+    .replace(/[̀-ͯ]/g, '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '.')
+    .replace(/^\.|\.$/g, '')
+}
+function sentence(r: Rng): string {
+  const n = rint(r, 4, 9)
+  const ws = Array.from({ length: n }, () => rpick(r, WORDS))
+  const s = ws.join(' ')
+  return `${s[0]!.toUpperCase()}${s.slice(1)}.`
+}
+function uuid(r: Rng): string {
+  const hex = '0123456789abcdef'
+  let s = ''
+  for (let i = 0; i < 32; i++) {
+    if (i === 12) s += '4'
+    else if (i === 16) s += hex[8 + Math.floor(r.next() * 4)]
+    else s += hex[Math.floor(r.next() * 16)]
+    if (i === 7 || i === 11 || i === 15 || i === 19) s += '-'
+  }
+  return s
+}
+function isoDate(r: Rng): string {
+  // Janela ±180 dias em torno de um epoch FIXO (determinístico; sem Date.now).
+  const base = 1_750_000_000_000 // ~jun/2025, fixo
+  const ms = base + rint(r, -180, 180) * 86_400_000 + rint(r, 0, 86_399) * 1000
+  return new Date(ms).toISOString()
+}
+function digits(r: Rng, n: number): string {
+  let s = ''
+  for (let i = 0; i < n; i++) s += String(rint(r, 0, 9))
+  return s
+}
+function cpf(r: Rng): string {
+  const d = digits(r, 11)
+  return `${d.slice(0, 3)}.${d.slice(3, 6)}.${d.slice(6, 9)}-${d.slice(9)}`
+}
+function cnpj(r: Rng): string {
+  const d = digits(r, 14)
+  return `${d.slice(0, 2)}.${d.slice(2, 5)}.${d.slice(5, 8)}/${d.slice(8, 12)}-${d.slice(12)}`
+}
+function phone(r: Rng): string {
+  return `(${digits(r, 2)}) 9${digits(r, 4)}-${digits(r, 4)}`
+}
+const capitalize = (s: string): string => (s.length > 0 ? s[0]!.toUpperCase() + s.slice(1) : s)
+const FILL = ['a', 'e', 'i', 'o', 'n', 's', 'r', 't'] as const
+
+/** Ajusta uma string SEM formato ao length/min/max — só preenche/trunca (texto puro). */
+function fitPlain(s: string, r: Rng, minC?: number, maxC?: number, lenC?: number): string {
+  let out = s
+  const target = lenC ?? minC
+  if (target !== undefined) while (out.length < target) out += rpick(r, FILL)
+  const cap = lenC ?? maxC
+  if (cap !== undefined && out.length > cap) out = out.slice(0, cap)
+  return out
+}
+
+/** Email VÁLIDO respeitando max/min — encurta ('aaaa@b.co') quando o max aperta, ou estende o
+ *  local quando o min cobra. Um `max` < 6 é schema contraditório (não há email tão curto). */
+function fakeEmail(r: Rng, minC?: number, maxC?: number): string {
+  let e = `${slug(fullName(r))}@exemplo.com.br`
+  if (maxC !== undefined && e.length > maxC) {
+    e = `${'a'.repeat(Math.max(1, maxC - 5))}@b.co` // reserva '@b.co' (5 chars)
+  }
+  if (minC !== undefined && e.length < minC) {
+    const at = e.indexOf('@')
+    e = e.slice(0, at) + 'x'.repeat(minC - e.length) + e.slice(at)
+  }
+  return e
+}
+
+// ── Introspecção zod 3 ──────────────────────────────────────────────────────────
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type Def = any
+function def(schema: ZodTypeAny): Def {
+  return (schema as unknown as { _def: Def })._def
+}
+function findCheck(d: Def, kind: string): Def | undefined {
+  return (d.checks ?? []).find((c: Def) => c.kind === kind)
+}
+
+function fakeString(schema: ZodTypeAny, r: Rng, hint: string): string {
+  const d = def(schema)
+  const minC = findCheck(d, 'min')?.value as number | undefined
+  const maxC = findCheck(d, 'max')?.value as number | undefined
+  const lenC = findCheck(d, 'length')?.value as number | undefined
+  const has = (k: string): boolean => findCheck(d, k) !== undefined
+  const bounded = minC !== undefined || maxC !== undefined || lenC !== undefined
+  const h = hint.toLowerCase()
+
+  // 1) Formato por CHECK do zod — a validade EXIGE o formato. Email é length-aware; uuid/url/
+  //    datetime têm tamanho próprio, então um length conflitante COM esses é schema contraditório.
+  if (has('email')) return fakeEmail(r, minC, maxC)
+  if (has('uuid')) return uuid(r)
+  if (has('datetime')) return isoDate(r)
+  if (has('url')) return `https://exemplo.com.br/${slug(rpick(r, WORDS))}`
+  if (has('cuid') || has('cuid2')) return `c${digits(r, 24)}`
+
+  // 2) Formato por NOME de campo — só um PALPITE. Se houver length/min/max, a restrição VENCE
+  //    (é autoritativa) e caímos no texto puro; sem restrição, o palpite formata.
+  if (!bounded) {
+    if (/mail/.test(h)) return fakeEmail(r)
+    if (/cnpj/.test(h)) return cnpj(r)
+    if (/cpf|documento|doc$/.test(h)) return cpf(r)
+    if (/(phone|fone|tel|celular|whats)/.test(h)) return phone(r)
+    if (/(^id$|_id$|id$|uuid)/.test(h)) return uuid(r)
+    if (/(url|link|site|href)/.test(h)) return `https://exemplo.com.br/${slug(rpick(r, WORDS))}`
+    if (/(at$|_at|date|data|prazo|vencimento)/.test(h)) return isoDate(r)
+  }
+
+  // 3) Texto puro — conteúdo por heurística leve, tamanho ajustado por fitPlain.
+  let s: string
+  if (/(desc|descric|observ|obs$|nota|resumo|body|conteudo)/.test(h)) s = sentence(r)
+  else if (/(nome|name|responsavel|contato)/.test(h)) s = fullName(r)
+  else if (/(titulo|title|label|assunto|slug)/.test(h)) s = capitalize(rpick(r, WORDS))
+  else s = rpick(r, WORDS)
+  return fitPlain(s, r, minC, maxC, lenC)
+}
+
+function fakeNumber(schema: ZodTypeAny, r: Rng): number {
+  const d = def(schema)
+  const isInt = Boolean(findCheck(d, 'int'))
+  const minC = findCheck(d, 'min')
+  const maxC = findCheck(d, 'max')
+  const eps = isInt ? 1 : 0.01 // recuo dos exclusivos; casa com o round(2) do float
+  let min = minC?.value as number | undefined
+  let max = maxC?.value as number | undefined
+  // `.gt`/`.lt` (inclusive === false) recuam pro primeiro válido.
+  if (min !== undefined && minC?.inclusive === false) min += eps
+  if (max !== undefined && maxC?.inclusive === false) max -= eps
+  // Defaults derivados: só-max → min = max-100 (cobre max negativo); só-min → max = min+100.
+  if (min === undefined) min = max !== undefined ? max - 100 : 0
+  if (max === undefined) max = min + 100
+  if (max < min) max = min
+  const raw = min + r.next() * (max - min)
+  const v = isInt ? Math.round(raw) : Math.round(raw * 100) / 100
+  return Math.max(min, Math.min(max, v)) // o round pode empurrar 1 casa pra fora dos limites
+}
+
+function gen(schema: ZodTypeAny, r: Rng, hint: string): unknown {
+  const d = def(schema)
+  switch (d.typeName as string) {
+    case 'ZodString':
+      return fakeString(schema, r, hint)
+    case 'ZodNumber':
+      return fakeNumber(schema, r)
+    case 'ZodBigInt':
+      return BigInt(rint(r, 0, 1_000_000))
+    case 'ZodBoolean':
+      return r.next() < 0.5
+    case 'ZodDate':
+      return new Date(isoDate(r))
+    case 'ZodLiteral':
+      return d.value
+    case 'ZodEnum':
+      return rpick(r, d.values as string[])
+    case 'ZodNativeEnum': {
+      // Enum numérico do TS tem reverse-mapping (`{0:'Red', Red:0}`); os VÁLIDOS são os valores
+      // das chaves cujo valor NÃO aponta pra um número (igual `getValidEnumValues` do zod).
+      const obj = d.values as Record<string, unknown>
+      const valid = Object.keys(obj)
+        .filter((k) => typeof obj[obj[k] as string] !== 'number')
+        .map((k) => obj[k])
+      return rpick(r, valid)
+    }
+    case 'ZodObject': {
+      const shape = typeof d.shape === 'function' ? d.shape() : d.shape
+      const out: Record<string, unknown> = {}
+      for (const key of Object.keys(shape)) out[key] = gen(shape[key] as ZodTypeAny, r, key)
+      return out
+    }
+    case 'ZodArray': {
+      const n = rint(r, 2, 4)
+      return Array.from({ length: n }, () => gen(d.type as ZodTypeAny, r, hint))
+    }
+    case 'ZodTuple':
+      return (d.items as ZodTypeAny[]).map((it) => gen(it, r, hint))
+    case 'ZodOptional':
+    case 'ZodNullable':
+    case 'ZodDefault':
+    case 'ZodCatch':
+    case 'ZodReadonly':
+    case 'ZodBranded':
+      // Populamos o interior (fixture rico); optional/nullable NÃO viram undefined/null.
+      return gen((d.innerType ?? d.schema) as ZodTypeAny, r, hint)
+    case 'ZodEffects':
+      return gen(d.schema as ZodTypeAny, r, hint)
+    case 'ZodPipeline':
+      return gen(d.in as ZodTypeAny, r, hint)
+    case 'ZodUnion':
+      return gen(rpick(r, d.options as ZodTypeAny[]), r, hint)
+    case 'ZodDiscriminatedUnion': {
+      const opts = [...(d.options as Map<unknown, ZodTypeAny> | ZodTypeAny[]).values?.() ?? (d.options as ZodTypeAny[])]
+      return gen(rpick(r, opts as ZodTypeAny[]), r, hint)
+    }
+    case 'ZodRecord': {
+      const out: Record<string, unknown> = {}
+      for (let i = 0; i < rint(r, 1, 3); i++) out[slug(rpick(r, WORDS))] = gen(d.valueType as ZodTypeAny, r, hint)
+      return out
+    }
+    case 'ZodNull':
+      return null
+    case 'ZodAny':
+    case 'ZodUnknown':
+    case 'ZodUndefined':
+    case 'ZodVoid':
+      return undefined
+    default:
+      return undefined
+  }
+}
+
+// ── API pública ─────────────────────────────────────────────────────────────────
+
+function seedOf(opts: FakeOptions | undefined, salt: number): number {
+  const s = opts?.seed ?? 1
+  return (typeof s === 'string' ? hashStr(s) : s >>> 0) ^ (salt * 0x9e3779b1)
+}
+
+/** Um valor sintético que satisfaz o schema. Determinístico pela `seed`. */
+export function fake<T>(schema: z.ZodType<T>, opts?: FakeOptions): T {
+  const r: Rng = { next: mulberry32(seedOf(opts, 0)) }
+  return gen(schema as ZodTypeAny, r, '') as T
+}
+
+/** `count` valores sintéticos distintos (seed variada por índice), estáveis entre execuções. */
+export function fakeMany<T>(schema: z.ZodType<T>, count: number, opts?: FakeOptions): T[] {
+  return Array.from({ length: Math.max(0, count) }, (_, i) => {
+    const r: Rng = { next: mulberry32(seedOf(opts, i + 1)) }
+    return gen(schema as ZodTypeAny, r, '') as T
+  })
+}