@mandujs/core 0.18.22 → 0.19.2

package/src/kitchen/api/contract-api.ts

@@ -0,0 +1,225 @@
+/**
+ * Contract Playground API
+ *
+ * GET  /__kitchen/api/contracts           → list all contracts
+ * GET  /__kitchen/api/contracts/:id       → contract detail (with OpenAPI schema)
+ * POST /__kitchen/api/contracts/validate  → validate input against contract
+ * GET  /__kitchen/api/contracts/openapi   → full OpenAPI 3.0.3 document (JSON)
+ * GET  /__kitchen/api/contracts/openapi.yaml → OpenAPI YAML
+ */
+
+import type { RoutesManifest, RouteSpec } from "../../spec/schema";
+import {
+  generateOpenAPIDocument,
+  zodToOpenAPISchema,
+  openAPIToJSON,
+  openAPIToYAML,
+} from "../../openapi/generator";
+import path from "path";
+
+export interface ContractListItem {
+  id: string;
+  pattern: string;
+  methods: string[];
+  description?: string;
+}
+
+export class ContractPlaygroundAPI {
+  private manifest: RoutesManifest;
+
+  constructor(
+    manifest: RoutesManifest,
+    private rootDir: string,
+  ) {
+    this.manifest = manifest;
+  }
+
+  updateManifest(manifest: RoutesManifest): void {
+    this.manifest = manifest;
+  }
+
+  /** GET /__kitchen/api/contracts */
+  async handleList(): Promise<Response> {
+    const contracts: ContractListItem[] = [];
+
+    for (const route of this.manifest.routes) {
+      if (!route.contractModule) continue;
+
+      const contract = await this.loadContract(route);
+      contracts.push({
+        id: route.id,
+        pattern: route.pattern,
+        methods: contract ? Object.keys(contract.request || {}) : route.methods || [],
+        description: contract?.description,
+      });
+    }
+
+    return Response.json({ contracts });
+  }
+
+  /** GET /__kitchen/api/contracts/:id */
+  async handleDetail(id: string): Promise<Response> {
+    const route = this.manifest.routes.find((r) => r.id === id);
+    if (!route || !route.contractModule) {
+      return Response.json({ error: "Contract not found" }, { status: 404 });
+    }
+
+    const contract = await this.loadContract(route);
+    if (!contract) {
+      return Response.json({ error: "Failed to load contract" }, { status: 500 });
+    }
+
+    // Build OpenAPI-like schema for each method
+    const schemas: Record<string, unknown> = {};
+    const HTTP_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE"];
+
+    for (const method of HTTP_METHODS) {
+      const methodSchema = contract.request?.[method];
+      if (!methodSchema) continue;
+
+      const schema: Record<string, unknown> = {};
+      if (methodSchema.query) {
+        schema.query = zodToOpenAPISchema(methodSchema.query);
+      }
+      if (methodSchema.body) {
+        schema.body = zodToOpenAPISchema(methodSchema.body);
+      }
+      if (methodSchema.params) {
+        schema.params = zodToOpenAPISchema(methodSchema.params);
+      }
+      if (methodSchema.headers) {
+        schema.headers = zodToOpenAPISchema(methodSchema.headers);
+      }
+      schemas[method] = schema;
+    }
+
+    // Response schemas
+    const responseSchemas: Record<string, unknown> = {};
+    for (const [status, resSchema] of Object.entries(contract.response || {})) {
+      if (resSchema && typeof resSchema === "object" && "schema" in resSchema) {
+        responseSchemas[status] = zodToOpenAPISchema((resSchema as any).schema);
+      } else if (resSchema) {
+        responseSchemas[status] = zodToOpenAPISchema(resSchema as any);
+      }
+    }
+
+    return Response.json({
+      id: route.id,
+      pattern: route.pattern,
+      description: contract.description,
+      tags: contract.tags,
+      normalize: contract.normalize,
+      request: schemas,
+      response: responseSchemas,
+    });
+  }
+
+  /** POST /__kitchen/api/contracts/validate */
+  async handleValidate(req: Request): Promise<Response> {
+    try {
+      const body = await req.json();
+      const { contractId, method, input } = body as {
+        contractId: string;
+        method: string;
+        input: { query?: unknown; body?: unknown; params?: unknown };
+      };
+
+      if (!contractId || !method) {
+        return Response.json(
+          { error: "Missing contractId or method" },
+          { status: 400 },
+        );
+      }
+
+      const route = this.manifest.routes.find((r) => r.id === contractId);
+      if (!route || !route.contractModule) {
+        return Response.json(
+          { error: "Contract not found" },
+          { status: 404 },
+        );
+      }
+
+      const contract = await this.loadContract(route);
+      if (!contract) {
+        return Response.json(
+          { error: "Failed to load contract" },
+          { status: 500 },
+        );
+      }
+
+      const methodSchema = contract.request?.[method];
+      if (!methodSchema) {
+        return Response.json(
+          { error: `Method ${method} not defined in contract` },
+          { status: 400 },
+        );
+      }
+
+      const errors: Array<{ field: string; issues: unknown[] }> = [];
+
+      // Validate query
+      if (methodSchema.query && input?.query !== undefined) {
+        const result = methodSchema.query.safeParse(input.query);
+        if (!result.success) {
+          errors.push({ field: "query", issues: result.error.issues });
+        }
+      }
+
+      // Validate body
+      if (methodSchema.body && input?.body !== undefined) {
+        const result = methodSchema.body.safeParse(input.body);
+        if (!result.success) {
+          errors.push({ field: "body", issues: result.error.issues });
+        }
+      }
+
+      // Validate params
+      if (methodSchema.params && input?.params !== undefined) {
+        const result = methodSchema.params.safeParse(input.params);
+        if (!result.success) {
+          errors.push({ field: "params", issues: result.error.issues });
+        }
+      }
+
+      if (errors.length > 0) {
+        return Response.json({ valid: false, errors });
+      }
+
+      return Response.json({ valid: true });
+    } catch (e) {
+      return Response.json(
+        { error: "Invalid request body" },
+        { status: 400 },
+      );
+    }
+  }
+
+  /** GET /__kitchen/api/contracts/openapi */
+  async handleOpenAPI(): Promise<Response> {
+    const doc = await generateOpenAPIDocument(this.manifest, this.rootDir);
+    return new Response(openAPIToJSON(doc), {
+      headers: { "Content-Type": "application/json; charset=utf-8" },
+    });
+  }
+
+  /** GET /__kitchen/api/contracts/openapi.yaml */
+  async handleOpenAPIYAML(): Promise<Response> {
+    const doc = await generateOpenAPIDocument(this.manifest, this.rootDir);
+    return new Response(openAPIToYAML(doc), {
+      headers: { "Content-Type": "text/yaml; charset=utf-8" },
+    });
+  }
+
+  // ────────────────────────────────────────────────
+
+  private async loadContract(route: RouteSpec): Promise<any | null> {
+    if (!route.contractModule) return null;
+    try {
+      const fullPath = path.join(this.rootDir, route.contractModule);
+      const module = await import(fullPath);
+      return module.default;
+    } catch {
+      return null;
+    }
+  }
+}

package/src/kitchen/api/diff-parser.ts

@@ -0,0 +1,108 @@
+/**
+ * Unified Diff Parser
+ *
+ * Parses git diff output into structured DiffHunk/DiffLine objects
+ * for rendering in the Kitchen Preview panel.
+ */
+
+export interface DiffLine {
+  type: "add" | "remove" | "context";
+  content: string;
+  oldLine?: number;
+  newLine?: number;
+}
+
+export interface DiffHunk {
+  header: string;
+  lines: DiffLine[];
+}
+
+export interface FileDiff {
+  filePath: string;
+  hunks: DiffHunk[];
+  additions: number;
+  deletions: number;
+  isNew: boolean;
+}
+
+/**
+ * Parse unified diff output for a single file.
+ */
+export function parseUnifiedDiff(raw: string, filePath: string): FileDiff {
+  const result: FileDiff = {
+    filePath,
+    hunks: [],
+    additions: 0,
+    deletions: 0,
+    isNew: false,
+  };
+
+  if (!raw.trim()) return result;
+
+  const lines = raw.split("\n");
+  let currentHunk: DiffHunk | null = null;
+  let oldLine = 0;
+  let newLine = 0;
+
+  for (const line of lines) {
+    // Detect new file
+    if (line.startsWith("new file mode")) {
+      result.isNew = true;
+      continue;
+    }
+
+    // Skip diff headers
+    if (
+      line.startsWith("diff ") ||
+      line.startsWith("index ") ||
+      line.startsWith("--- ") ||
+      line.startsWith("+++ ") ||
+      line.startsWith("Binary ")
+    ) {
+      continue;
+    }
+
+    // Hunk header: @@ -oldStart,oldCount +newStart,newCount @@
+    const hunkMatch = line.match(
+      /^@@\s+-(\d+)(?:,\d+)?\s+\+(\d+)(?:,\d+)?\s+@@(.*)$/,
+    );
+    if (hunkMatch) {
+      currentHunk = {
+        header: line,
+        lines: [],
+      };
+      result.hunks.push(currentHunk);
+      oldLine = parseInt(hunkMatch[1], 10);
+      newLine = parseInt(hunkMatch[2], 10);
+      continue;
+    }
+
+    if (!currentHunk) continue;
+
+    if (line.startsWith("+")) {
+      currentHunk.lines.push({
+        type: "add",
+        content: line.slice(1),
+        newLine: newLine++,
+      });
+      result.additions++;
+    } else if (line.startsWith("-")) {
+      currentHunk.lines.push({
+        type: "remove",
+        content: line.slice(1),
+        oldLine: oldLine++,
+      });
+      result.deletions++;
+    } else if (line.startsWith(" ")) {
+      currentHunk.lines.push({
+        type: "context",
+        content: line.slice(1),
+        oldLine: oldLine++,
+        newLine: newLine++,
+      });
+    }
+    // Skip "" and other non-standard lines
+  }
+
+  return result;
+}

package/src/kitchen/api/file-api.ts

@@ -0,0 +1,273 @@
+/**
+ * File API - Provides file read, diff, and recent changes for Kitchen Preview.
+ *
+ * GET /__kitchen/api/file?path=...        → file content
+ * GET /__kitchen/api/file/diff?path=...   → git diff for file
+ * GET /__kitchen/api/file/changes         → git status (recent changes)
+ */
+
+import path from "path";
+import fs from "fs";
+import { parseUnifiedDiff, type FileDiff } from "./diff-parser";
+
+export interface RecentFileChange {
+  filePath: string;
+  status: "added" | "modified" | "deleted" | "renamed" | "untracked";
+}
+
+export class FileAPI {
+  private gitRoot: string | null | undefined;
+
+  constructor(private rootDir: string) {}
+
+  /**
+   * GET /__kitchen/api/file?path=...
+   * Read file content with language detection.
+   */
+  async handleReadFile(url: URL): Promise<Response> {
+    const filePath = url.searchParams.get("path");
+    if (!filePath) {
+      return Response.json(
+        { error: "Missing 'path' query parameter" },
+        { status: 400 },
+      );
+    }
+
+    const resolved = this.validatePath(filePath);
+    if (!resolved) {
+      return Response.json(
+        { error: "Path outside project root" },
+        { status: 403 },
+      );
+    }
+
+    try {
+      const file = Bun.file(resolved);
+      const exists = await file.exists();
+      if (!exists) {
+        return Response.json({ error: "File not found" }, { status: 404 });
+      }
+
+      const content = await file.text();
+      const language = detectLanguage(filePath);
+
+      return Response.json({ filePath, content, language });
+    } catch (error) {
+      return Response.json(
+        { error: "Failed to read file" },
+        { status: 500 },
+      );
+    }
+  }
+
+  /**
+   * GET /__kitchen/api/file/diff?path=...
+   * Get git diff for a specific file.
+   */
+  async handleFileDiff(url: URL): Promise<Response> {
+    const filePath = url.searchParams.get("path");
+    if (!filePath) {
+      return Response.json(
+        { error: "Missing 'path' query parameter" },
+        { status: 400 },
+      );
+    }
+
+    const resolved = this.validatePath(filePath);
+    if (!resolved) {
+      return Response.json(
+        { error: "Path outside project root" },
+        { status: 403 },
+      );
+    }
+
+    try {
+      const diff = await this.getFileDiff(filePath, resolved);
+      return Response.json(diff);
+    } catch (error) {
+      return Response.json(
+        { error: "Failed to get diff" },
+        { status: 500 },
+      );
+    }
+  }
+
+  /**
+   * GET /__kitchen/api/file/changes
+   * List recently changed files via git status.
+   */
+  async handleRecentChanges(): Promise<Response> {
+    try {
+      const changes = await this.getGitStatus();
+      return Response.json({ changes });
+    } catch (error) {
+      return Response.json(
+        { error: "Failed to get changes" },
+        { status: 500 },
+      );
+    }
+  }
+
+  // ────────────────────────────────────────────────
+
+  private validatePath(filePath: string): string | null {
+    const resolved = path.resolve(this.rootDir, filePath);
+    if (!resolved.startsWith(this.rootDir + path.sep) && resolved !== this.rootDir) {
+      return null;
+    }
+    return resolved;
+  }
+
+  private getGitRoot(): string | null {
+    if (this.gitRoot !== undefined) {
+      return this.gitRoot;
+    }
+
+    let current = path.resolve(this.rootDir);
+    while (true) {
+      if (fs.existsSync(path.join(current, ".git"))) {
+        this.gitRoot = current;
+        return current;
+      }
+
+      const parent = path.dirname(current);
+      if (parent === current) {
+        this.gitRoot = null;
+        return null;
+      }
+      current = parent;
+    }
+  }
+
+  private async runGit(args: string[], cwd: string): Promise<string> {
+    const proc = Bun.spawn(["git", ...args], {
+      cwd,
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    const stdout = await new Response(proc.stdout).text();
+    const stderr = await new Response(proc.stderr).text();
+    const exitCode = await proc.exited;
+
+    if (exitCode !== 0) {
+      throw new Error(stderr || stdout || `git ${args.join(" ")} failed`);
+    }
+
+    return stdout;
+  }
+
+  private getRepoRelativePath(resolvedPath: string, gitRoot: string): string {
+    return path.relative(gitRoot, resolvedPath).replace(/\\/g, "/");
+  }
+
+  private getProjectRelativePath(repoRelativePath: string, gitRoot: string): string {
+    const absolutePath = path.resolve(gitRoot, repoRelativePath.replace(/\//g, path.sep));
+    return path.relative(this.rootDir, absolutePath).replace(/\\/g, "/");
+  }
+
+  private async getFileDiff(filePath: string, resolvedPath: string): Promise<FileDiff> {
+    const gitRoot = this.getGitRoot();
+    if (!gitRoot) {
+      return this.createSyntheticDiff(filePath, resolvedPath);
+    }
+
+    const repoRelativePath = this.getRepoRelativePath(resolvedPath, gitRoot);
+    const stdout = await this.runGit(["diff", "--", repoRelativePath], gitRoot);
+    if (stdout.trim()) {
+      return parseUnifiedDiff(stdout, filePath);
+    }
+
+    if (!fs.existsSync(resolvedPath)) {
+      return parseUnifiedDiff("", filePath);
+    }
+
+    const status = await this.runGit(["status", "--porcelain", "--", repoRelativePath], gitRoot);
+    if (status.trim().startsWith("??")) {
+      return this.createSyntheticDiff(filePath, resolvedPath);
+    }
+
+    return parseUnifiedDiff("", filePath);
+  }
+
+  private createSyntheticDiff(filePath: string, resolvedPath: string): FileDiff {
+    // Bun.file().text() is async, but synthetic diffs are only used in non-git fallback.
+    // Use fs for synchronous fallback to keep the response fast.
+    const normalized = fs.readFileSync(resolvedPath, "utf-8").replace(/\r\n/g, "\n");
+    if (!normalized) {
+      return parseUnifiedDiff("", filePath);
+    }
+
+    const lines = normalized.split("\n");
+    if (lines.length > 0 && lines[lines.length - 1] === "") {
+      lines.pop();
+    }
+
+    const raw = [
+      "new file mode 100644",
+      `@@ -0,0 +1,${lines.length} @@`,
+      ...lines.map((line) => `+${line}`),
+    ].join("\n");
+
+    return parseUnifiedDiff(raw, filePath);
+  }
+
+  private async getGitStatus(): Promise<RecentFileChange[]> {
+    const gitRoot = this.getGitRoot();
+    if (!gitRoot) {
+      return [];
+    }
+
+    const repoRelativeRoot = this.getRepoRelativePath(this.rootDir, gitRoot);
+    const args = ["status", "--porcelain"];
+    if (repoRelativeRoot && repoRelativeRoot !== ".") {
+      args.push("--", repoRelativeRoot);
+    }
+
+    const stdout = await this.runGit(args, gitRoot);
+
+    const changes: RecentFileChange[] = [];
+    for (const line of stdout.split("\n")) {
+      if (!line.trim()) continue;
+
+      const statusCode = line.substring(0, 2);
+      const gitFilePath = line.substring(3).trim();
+      const filePath = this.getProjectRelativePath(gitFilePath, gitRoot);
+
+      changes.push({
+        filePath,
+        status: parseGitStatus(statusCode),
+      });
+    }
+
+    return changes;
+  }
+}
+
+function parseGitStatus(code: string): RecentFileChange["status"] {
+  const x = code[0];
+  const y = code[1];
+
+  if (x === "?" || y === "?") return "untracked";
+  if (x === "A" || y === "A") return "added";
+  if (x === "D" || y === "D") return "deleted";
+  if (x === "R" || y === "R") return "renamed";
+  return "modified";
+}
+
+function detectLanguage(filePath: string): string {
+  const ext = path.extname(filePath).toLowerCase();
+  const langMap: Record<string, string> = {
+    ".ts": "typescript",
+    ".tsx": "typescript",
+    ".js": "javascript",
+    ".jsx": "javascript",
+    ".json": "json",
+    ".css": "css",
+    ".html": "html",
+    ".md": "markdown",
+    ".yaml": "yaml",
+    ".yml": "yaml",
+    ".toml": "toml",
+  };
+  return langMap[ext] || "text";
+}

package/src/kitchen/api/guard-api.ts

@@ -0,0 +1,83 @@
+/**
+ * Guard API - Exposes architecture guard data to Kitchen UI.
+ *
+ * GET /__kitchen/api/guard       → latest cached violation report
+ * POST /__kitchen/api/guard/scan → trigger full directory scan
+ */
+
+import type { GuardConfig, ViolationReport } from "../../guard/types";
+import { checkDirectory } from "../../guard/watcher";
+
+export class GuardAPI {
+  private cachedReport: ViolationReport | null = null;
+  private scanning = false;
+
+  constructor(
+    private config: GuardConfig | null,
+    private rootDir: string,
+  ) {}
+
+  /** Update config at runtime (e.g., when mandu.config.ts changes) */
+  updateConfig(config: GuardConfig | null): void {
+    this.config = config;
+  }
+
+  /** Handle GET /__kitchen/api/guard */
+  handleGetReport(): Response {
+    if (!this.config) {
+      return Response.json(
+        { enabled: false, message: "Guard is not configured" },
+        { status: 200 },
+      );
+    }
+
+    if (!this.cachedReport) {
+      return Response.json({
+        enabled: true,
+        preset: this.config.preset,
+        report: null,
+        message: "No scan has been run yet. POST /__kitchen/api/guard/scan to trigger.",
+      });
+    }
+
+    return Response.json({
+      enabled: true,
+      preset: this.config.preset,
+      report: this.cachedReport,
+    });
+  }
+
+  /** Handle POST /__kitchen/api/guard/scan */
+  async handleScan(): Promise<Response> {
+    if (!this.config) {
+      return Response.json(
+        { enabled: false, message: "Guard is not configured" },
+        { status: 200 },
+      );
+    }
+
+    if (this.scanning) {
+      return Response.json(
+        { message: "Scan already in progress" },
+        { status: 409 },
+      );
+    }
+
+    this.scanning = true;
+    try {
+      this.cachedReport = await checkDirectory(this.config, this.rootDir);
+      return Response.json({
+        enabled: true,
+        preset: this.config.preset,
+        report: this.cachedReport,
+      });
+    } finally {
+      this.scanning = false;
+    }
+  }
+
+  /** Called by guard watcher's onViolation to push incremental updates */
+  pushViolationReport(report: ViolationReport): void {
+    this.cachedReport = report;
+  }
+}