@mandujs/core 0.21.0 → 0.22.1

package/src/storage/s3/index.ts

@@ -0,0 +1,412 @@
+/**
+ * @mandujs/core/storage/s3
+ *
+ * Thin, S3-compatible object storage helper backed by **native `Bun.S3Client`**
+ * (no AWS SDK, no external deps). The same client works against AWS S3,
+ * Cloudflare R2, MinIO, DigitalOcean Spaces, and any other S3-compatible
+ * service — the only thing that changes is the `endpoint` URL.
+ *
+ * ## Credentials
+ *
+ * Bun reads `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` (and optionally
+ * `AWS_SESSION_TOKEN`) — plus the `S3_*` variants — from the environment at
+ * initialization time. You can also pass them explicitly to the underlying
+ * `Bun.S3Client`, but this helper intentionally does **not** surface that
+ * option: routing secrets through env vars (or a `.env` file loaded by Bun)
+ * keeps credentials out of application code. See
+ * https://bun.com/docs/runtime/s3#credentials for the full matrix.
+ *
+ * ## Endpoint
+ *
+ * Pass `endpoint` on the client config for R2/MinIO/GCS/Supabase/etc. Omit it
+ * for AWS (Bun infers the endpoint from `region` + `bucket`).
+ *
+ * @example
+ * ```ts
+ * import { createS3Client } from "@mandujs/core/storage/s3";
+ *
+ * const storage = createS3Client({
+ *   bucket: "uploads",
+ *   endpoint: "https://<account>.r2.cloudflarestorage.com",
+ *   region: "auto",
+ * });
+ *
+ * const url = await storage.upload(file, { key: `u/${id}.png` });
+ * const presigned = await storage.presign({ key: "u/next.png", method: "PUT", contentType: "image/png" });
+ * ```
+ *
+ * @module storage/s3
+ */
+
+// ─── Public types ───────────────────────────────────────────────────────────
+
+/**
+ * S3 client configuration. Credentials are **not** part of this interface —
+ * they come from `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` env vars that
+ * Bun auto-reads. See module docs.
+ */
+export interface S3Config {
+  /** Bucket name. Required. */
+  bucket: string;
+  /**
+   * Custom endpoint URL. Required for R2/MinIO/GCS/etc.; omit for AWS (Bun
+   * infers from `region`).
+   */
+  endpoint?: string;
+  /**
+   * Force path-style URLs (`endpoint/bucket/key`) instead of virtual-hosted
+   * (`bucket.endpoint/key`). MinIO usually needs this set to `true`. AWS and
+   * R2 work with either but default to virtual-hosted. Default: `false`.
+   */
+  forcePathStyle?: boolean;
+  /**
+   * Region. Bun defaults to `us-east-1` for AWS; set `"auto"` for Cloudflare
+   * R2. No default applied here — we pass through as-is so Bun's own
+   * defaulting logic stays authoritative.
+   */
+  region?: string;
+}
+
+/** Options for uploading a single object. */
+export interface S3UploadOptions {
+  /** Target object key (path inside the bucket). Required. */
+  key: string;
+  /**
+   * Content-Type header. Inferred from the key's file extension when omitted
+   * — see `getContentType` below for the covered extensions.
+   */
+  contentType?: string;
+  /**
+   * User metadata. Keys are lowercased and prefixed with `x-amz-meta-` by S3.
+   * Values must be ASCII — non-ASCII characters will be rejected by most
+   * providers; we do not validate here.
+   */
+  metadata?: Record<string, string>;
+  /**
+   * Canned ACL. Applied to this upload only. Omit to inherit the bucket
+   * default (recommended for private buckets).
+   */
+  acl?: "private" | "public-read";
+}
+
+/** Options for generating a presigned URL. */
+export interface S3PresignOptions {
+  /** Object key. Required. */
+  key: string;
+  /** HTTP method. Default: `"PUT"` (client-direct upload is the common case). */
+  method?: "GET" | "PUT";
+  /** URL lifetime in **seconds**. Default: 900 (15 minutes). */
+  expiresIn?: number;
+  /**
+   * `Content-Type` baked into the signature. Only meaningful for `PUT`; the
+   * uploading client MUST send a matching header or the signature will fail.
+   */
+  contentType?: string;
+}
+
+/** Opaque client instance. */
+export interface S3Client {
+  /**
+   * Uploads a blob/buffer and resolves to the canonical object URL
+   * (endpoint + bucket + key).
+   */
+  upload(
+    body: Blob | ArrayBuffer | Uint8Array,
+    options: S3UploadOptions,
+  ): Promise<string>;
+
+  /** Generates a presigned URL for client-direct upload (PUT) or download (GET). */
+  presign(options: S3PresignOptions): Promise<string>;
+
+  /** Deletes an object. Resolves silently if the object does not exist. */
+  delete(key: string): Promise<void>;
+
+  /** Returns a readable stream for the object body. Throws if not found. */
+  getReadable(key: string): Promise<ReadableStream>;
+
+  /**
+   * Head check — `true` if the object exists, `false` on 404. Any other error
+   * (network failure, 403, malformed response) is re-thrown.
+   */
+  exists(key: string): Promise<boolean>;
+}
+
+// ─── Bun runtime surface (structural; no `any`) ─────────────────────────────
+
+/** Options accepted by `S3File.write`. Mirrors Bun's BlobPropertyBag extensions. */
+interface BunS3WriteOptions {
+  type?: string;
+  acl?: "private" | "public-read";
+}
+
+/** Options accepted by `S3File.presign`. */
+interface BunS3PresignOptions {
+  method?: "GET" | "PUT";
+  expiresIn?: number;
+  type?: string;
+}
+
+/** Minimal shape of the `S3File` handle returned by `client.file(key)`. */
+interface BunS3File {
+  write(
+    body: Blob | ArrayBuffer | Uint8Array,
+    options?: BunS3WriteOptions,
+  ): Promise<number>;
+  presign(options?: BunS3PresignOptions): string;
+  delete(): Promise<void>;
+  exists(): Promise<boolean>;
+  stream(): ReadableStream;
+}
+
+/** Options accepted by the `Bun.S3Client` constructor. */
+interface BunS3ClientConfig {
+  bucket: string;
+  endpoint?: string;
+  region?: string;
+  virtualHostedStyle?: boolean;
+}
+
+/** Minimal `Bun.S3Client` instance shape used by this module. */
+export interface BunS3ClientInstance {
+  file(key: string): BunS3File;
+}
+
+/**
+ * Constructor surface — `Bun.S3Client` is a class. We only need the `new`
+ * signature structurally, so we type it as a callable returning an instance.
+ */
+export type BunS3ClientCtor = new (config: BunS3ClientConfig) => BunS3ClientInstance;
+
+// ─── Content-type inference ─────────────────────────────────────────────────
+
+const EXTENSION_MAP: ReadonlyMap<string, string> = new Map([
+  ["jpg", "image/jpeg"],
+  ["jpeg", "image/jpeg"],
+  ["png", "image/png"],
+  ["webp", "image/webp"],
+  ["gif", "image/gif"],
+  ["pdf", "application/pdf"],
+  ["txt", "text/plain"],
+  ["json", "application/json"],
+  ["csv", "text/csv"],
+  ["zip", "application/zip"],
+  ["mp4", "video/mp4"],
+  ["webm", "video/webm"],
+]);
+
+/**
+ * Maps a key's trailing file extension to a MIME type. Returns
+ * `application/octet-stream` for unknown/missing extensions.
+ *
+ * Exported for tests and for callers that want to inspect the mapping without
+ * uploading (e.g., for building a `Content-Type` header on a presigned PUT).
+ */
+export function getContentType(key: string): string {
+  const lastDot = key.lastIndexOf(".");
+  if (lastDot === -1 || lastDot === key.length - 1) {
+    return "application/octet-stream";
+  }
+  const ext = key.slice(lastDot + 1).toLowerCase();
+  return EXTENSION_MAP.get(ext) ?? "application/octet-stream";
+}
+
+// ─── URL construction ───────────────────────────────────────────────────────
+
+/**
+ * Builds the canonical object URL that `upload()` returns. Uses the same
+ * path-vs-virtual-host logic Bun itself applies, so the URL matches what
+ * `fetch()` would resolve.
+ *
+ * For AWS (no endpoint set), we return an `s3://<bucket>/<key>` URI — the
+ * caller may not know the region and we don't want to guess at a public URL.
+ */
+function buildObjectUrl(
+  config: S3Config,
+  key: string,
+): string {
+  const encodedKey = encodeKey(key);
+
+  if (!config.endpoint) {
+    // Bun infers the AWS endpoint; returning s3:// keeps this provider-agnostic
+    // without pretending to know if the bucket is public-read.
+    return `s3://${config.bucket}/${encodedKey}`;
+  }
+
+  const base = config.endpoint.replace(/\/+$/, "");
+  if (config.forcePathStyle) {
+    return `${base}/${config.bucket}/${encodedKey}`;
+  }
+
+  // Virtual-hosted style: splice bucket into the hostname.
+  try {
+    const url = new URL(base);
+    url.hostname = `${config.bucket}.${url.hostname}`;
+    return `${url.toString().replace(/\/+$/, "")}/${encodedKey}`;
+  } catch {
+    // Malformed endpoint — fall back to path style so we still return a
+    // deterministic, debuggable URL.
+    return `${base}/${config.bucket}/${encodedKey}`;
+  }
+}
+
+/** URL-encodes every path segment of an S3 key while preserving `/` separators. */
+function encodeKey(key: string): string {
+  return key
+    .split("/")
+    .map((segment) => encodeURIComponent(segment))
+    .join("/");
+}
+
+// ─── Bun runtime probe ──────────────────────────────────────────────────────
+
+function getBunS3ClientCtor(): BunS3ClientCtor {
+  const g = globalThis as unknown as { Bun?: { S3Client?: BunS3ClientCtor } };
+  if (!g.Bun || !g.Bun.S3Client) {
+    throw new Error(
+      "[@mandujs/core/storage/s3] Bun.S3Client is unavailable — this module requires the Bun runtime (>= 1.3).",
+    );
+  }
+  return g.Bun.S3Client;
+}
+
+// ─── Factory ────────────────────────────────────────────────────────────────
+
+/**
+ * Internal factory accepting an injectable `S3Client` constructor — used by
+ * unit tests to swap in a fake implementation. Production callers use
+ * {@link createS3Client}, which binds this to `Bun.S3Client`.
+ */
+export function _createS3ClientWith(
+  Ctor: BunS3ClientCtor,
+  config: S3Config,
+): S3Client {
+  if (!config.bucket || typeof config.bucket !== "string") {
+    throw new TypeError(
+      "[@mandujs/core/storage/s3] createS3Client: 'bucket' is required.",
+    );
+  }
+
+  const bunClient = new Ctor({
+    bucket: config.bucket,
+    endpoint: config.endpoint,
+    region: config.region,
+    // forcePathStyle === true  ⇒ virtualHostedStyle: false (the Bun default).
+    // forcePathStyle === false ⇒ leave Bun's default untouched.
+    // Only set virtualHostedStyle explicitly if the user *opts out* of path
+    // style for a service that normally defaults to it. The map here is 1:1.
+    virtualHostedStyle: config.forcePathStyle === true ? false : undefined,
+  });
+
+  async function upload(
+    body: Blob | ArrayBuffer | Uint8Array,
+    options: S3UploadOptions,
+  ): Promise<string> {
+    if (!options.key) {
+      throw new TypeError(
+        "[@mandujs/core/storage/s3] upload: 'key' is required.",
+      );
+    }
+    const file = bunClient.file(options.key);
+    const contentType = options.contentType ?? getContentType(options.key);
+
+    await file.write(body, {
+      type: contentType,
+      ...(options.acl !== undefined ? { acl: options.acl } : {}),
+    });
+
+    // NOTE: metadata is accepted in our public type for forward-compat, but
+    // Bun 1.3's `S3File.write` does not surface a `metadata` option. Dropping
+    // it silently would be a bug waiting to happen, so we throw at call time.
+    if (options.metadata && Object.keys(options.metadata).length > 0) {
+      throw new Error(
+        "[@mandujs/core/storage/s3] upload: 'metadata' is not yet supported by Bun.S3Client.write. Use a presigned URL with custom headers, or file an issue upstream.",
+      );
+    }
+
+    return buildObjectUrl(config, options.key);
+  }
+
+  async function presign(options: S3PresignOptions): Promise<string> {
+    if (!options.key) {
+      throw new TypeError(
+        "[@mandujs/core/storage/s3] presign: 'key' is required.",
+      );
+    }
+    const method = options.method ?? "PUT";
+    const expiresIn = options.expiresIn ?? 900;
+    const file = bunClient.file(options.key);
+
+    // Bun.S3File.presign is synchronous; we wrap in a Promise so the public
+    // API stays consistent with the rest of the helper surface.
+    const url = file.presign({
+      method,
+      expiresIn,
+      ...(options.contentType !== undefined ? { type: options.contentType } : {}),
+    });
+    return url;
+  }
+
+  async function deleteObject(key: string): Promise<void> {
+    const file = bunClient.file(key);
+    try {
+      await file.delete();
+    } catch (err) {
+      // S3 returns success for delete-of-missing-key; but some S3-compatible
+      // providers (and network hiccups) can surface a 404-shaped error. We
+      // swallow "not found" and re-throw everything else.
+      if (isNotFoundError(err)) return;
+      throw err;
+    }
+  }
+
+  async function getReadable(key: string): Promise<ReadableStream> {
+    const file = bunClient.file(key);
+    // `file.stream()` is synchronous and returns a ReadableStream that lazily
+    // issues the GET when you start consuming. We preserve that laziness and
+    // let errors surface on first read rather than proactively HEAD-ing here.
+    return file.stream();
+  }
+
+  async function exists(key: string): Promise<boolean> {
+    const file = bunClient.file(key);
+    try {
+      return await file.exists();
+    } catch (err) {
+      if (isNotFoundError(err)) return false;
+      throw err;
+    }
+  }
+
+  return {
+    upload,
+    presign,
+    delete: deleteObject,
+    getReadable,
+    exists,
+  };
+}
+
+/**
+ * Creates an S3-compatible storage client.
+ *
+ * @throws if `config.bucket` is missing, or if called outside the Bun runtime.
+ */
+export function createS3Client(config: S3Config): S3Client {
+  return _createS3ClientWith(getBunS3ClientCtor(), config);
+}
+
+// ─── Error helpers ──────────────────────────────────────────────────────────
+
+/**
+ * Structural check for "object not found" errors raised by Bun's S3 layer.
+ * Bun emits an `S3Error` instance with `code` set; we also handle the
+ * HTTP-status-bearing variants some providers surface.
+ */
+function isNotFoundError(err: unknown): boolean {
+  if (!err || typeof err !== "object") return false;
+  const e = err as { name?: unknown; code?: unknown; status?: unknown };
+  if (e.code === "NoSuchKey") return true;
+  if (e.code === "NotFound") return true;
+  if (e.status === 404) return true;
+  return false;
+}

package/src/testing/index.ts

@@ -3,6 +3,8 @@
  * 서버 없이 라우트/filling 단위 테스트
  */
 
+import path from "path";
+import os from "os";
 import { ManduContext } from "../filling/context";
 import type { ManduFilling } from "../filling/filling";
 import type { RouteSpec, RoutesManifest } from "../spec/schema";
@@ -187,3 +189,59 @@ export function createTestManifest(routes: Partial<RouteSpec>[]): RoutesManifest
 export function createTestIsland(name: string, strategy: string = "visible") {
   return { __island: true, __hydrate: strategy, __name: name };
 }
+
+// ========== createMockMcpContext ==========
+
+/**
+ * Mock MCP context shape mirroring the real MCP server context
+ * (see `packages/mcp/src/utils/project.ts`).
+ *
+ * Use this in tests for MCP tool plugins and slot/contract validators
+ * that accept an MCP-context-like object.
+ */
+export interface MockMcpContext {
+  paths: {
+    repoRoot: string;
+    manduDir: string;
+    manifestPath: string;
+    specsDir: string;
+    slotsDir: string;
+  };
+  readConfig: () => Promise<Record<string, unknown>>;
+  readManifest: () => Promise<RoutesManifest>;
+}
+
+/**
+ * Create a mock MCP context suitable for unit-testing MCP tools without
+ * spinning up an actual project on disk.
+ *
+ * @example
+ * ```typescript
+ * const ctx = createMockMcpContext({
+ *   config: { guard: { preset: "fsd" } },
+ *   manifest: createTestManifest([{ id: "home", kind: "page", pattern: "/" }]),
+ * });
+ * await myTool.execute(ctx, { input: "..." });
+ * ```
+ */
+export function createMockMcpContext(options: {
+  root?: string;
+  config?: Record<string, unknown>;
+  manifest?: RoutesManifest;
+} = {}): MockMcpContext {
+  const root = options.root ?? path.join(os.tmpdir(), "mandu-mock-mcp");
+  const config = options.config ?? {};
+  const manifest = options.manifest ?? { version: 1, routes: [] };
+
+  return {
+    paths: {
+      repoRoot: root,
+      manduDir: path.join(root, ".mandu"),
+      manifestPath: path.join(root, ".mandu", "routes.manifest.json"),
+      specsDir: path.join(root, "spec"),
+      slotsDir: path.join(root, "spec", "slots"),
+    },
+    readConfig: async () => config,
+    readManifest: async () => manifest,
+  };
+}