feat: add markdown import/export (closes #77, #78)

- Add POST /api/knowledge/import endpoint for .md and .zip files
- Add GET /api/knowledge/export endpoint with markdown/json formats
- Import parses frontmatter (title, tags, status, visibility)
- Export includes frontmatter in markdown format
- Add ImportExportActions component with drag-and-drop UI
- Add import progress dialog with success/error summary
- Add export dropdown with format selection
- Include comprehensive test suite
- Support bulk import with detailed error reporting

apps/api/package.json

@@ -57,6 +57,8 @@
     "@nestjs/schematics": "^11.0.1",
     "@nestjs/testing": "^11.1.12",
     "@swc/core": "^1.10.18",
+    "@types/adm-zip": "^0.5.7",
+    "@types/archiver": "^7.0.0",
     "@types/express": "^5.0.1",
     "@types/highlight.js": "^10.1.0",
     "@types/ioredis": "^5.0.0",

apps/api/src/knowledge/dto/import-export.dto.ts

@@ -0,0 +1,52 @@
+import {
+  IsString,
+  IsOptional,
+  IsEnum,
+  IsArray,
+  ArrayMinSize,
+} from "class-validator";
+
+/**
+ * Export format enum
+ */
+export enum ExportFormat {
+  MARKDOWN = "markdown",
+  JSON = "json",
+}
+
+/**
+ * DTO for export query parameters
+ */
+export class ExportQueryDto {
+  @IsOptional()
+  @IsEnum(ExportFormat, { message: "format must be either 'markdown' or 'json'" })
+  format?: ExportFormat = ExportFormat.MARKDOWN;
+
+  @IsOptional()
+  @IsArray({ message: "entryIds must be an array" })
+  @IsString({ each: true, message: "each entryId must be a string" })
+  entryIds?: string[];
+}
+
+/**
+ * Import result for a single entry
+ */
+export interface ImportResult {
+  filename: string;
+  success: boolean;
+  entryId?: string;
+  slug?: string;
+  title?: string;
+  error?: string;
+}
+
+/**
+ * Response DTO for import operation
+ */
+export interface ImportResponseDto {
+  success: boolean;
+  totalFiles: number;
+  imported: number;
+  failed: number;
+  results: ImportResult[];
+}

apps/api/src/knowledge/dto/index.ts

@@ -10,3 +10,9 @@ export {
   RecentEntriesDto,
 } from "./search-query.dto";
 export { GraphQueryDto } from "./graph-query.dto";
+export {
+  ExportQueryDto,
+  ExportFormat,
+  ImportResult,
+  ImportResponseDto,
+} from "./import-export.dto";

apps/api/src/knowledge/import-export.controller.ts

@@ -0,0 +1,93 @@
+import {
+  Controller,
+  Post,
+  Get,
+  Query,
+  UseGuards,
+  UseInterceptors,
+  UploadedFile,
+  Res,
+  BadRequestException,
+} from "@nestjs/common";
+import { FileInterceptor } from "@nestjs/platform-express";
+import { Response } from "express";
+import { ImportExportService } from "./services/import-export.service";
+import { ExportQueryDto, ExportFormat, ImportResponseDto } from "./dto";
+import { AuthGuard } from "../auth/guards/auth.guard";
+import { WorkspaceGuard, PermissionGuard } from "../common/guards";
+import { Workspace, Permission, RequirePermission } from "../common/decorators";
+import { CurrentUser } from "../auth/decorators/current-user.decorator";
+
+/**
+ * Controller for knowledge import/export endpoints
+ * All endpoints require authentication and workspace context
+ */
+@Controller("knowledge")
+@UseGuards(AuthGuard, WorkspaceGuard, PermissionGuard)
+export class ImportExportController {
+  constructor(private readonly importExportService: ImportExportService) {}
+
+  /**
+   * POST /api/knowledge/import
+   * Import knowledge entries from uploaded file (.md or .zip)
+   * Requires: MEMBER role or higher
+   */
+  @Post("import")
+  @RequirePermission(Permission.WORKSPACE_MEMBER)
+  @UseInterceptors(FileInterceptor("file"))
+  async importEntries(
+    @Workspace() workspaceId: string,
+    @CurrentUser() user: any,
+    @UploadedFile() file: Express.Multer.File
+  ): Promise<ImportResponseDto> {
+    if (!file) {
+      throw new BadRequestException("No file uploaded");
+    }
+
+    const result = await this.importExportService.importEntries(
+      workspaceId,
+      user.id,
+      file
+    );
+
+    return {
+      success: result.failed === 0,
+      totalFiles: result.totalFiles,
+      imported: result.imported,
+      failed: result.failed,
+      results: result.results,
+    };
+  }
+
+  /**
+   * GET /api/knowledge/export
+   * Export knowledge entries as a zip file
+   * Query params:
+   *   - format: 'markdown' (default) or 'json'
+   *   - entryIds: optional array of entry IDs to export (exports all if not provided)
+   * Requires: Any workspace member
+   */
+  @Get("export")
+  @RequirePermission(Permission.WORKSPACE_ANY)
+  async exportEntries(
+    @Workspace() workspaceId: string,
+    @Query() query: ExportQueryDto,
+    @Res() res: Response
+  ): Promise<void> {
+    const format = query.format || ExportFormat.MARKDOWN;
+    const entryIds = query.entryIds;
+
+    const { stream, filename } = await this.importExportService.exportEntries(
+      workspaceId,
+      format,
+      entryIds
+    );
+
+    // Set response headers
+    res.setHeader("Content-Type", "application/zip");
+    res.setHeader("Content-Disposition", `attachment; filename="${filename}"`);
+
+    // Pipe the archive stream to response
+    stream.pipe(res);
+  }
+}

apps/api/src/knowledge/knowledge.module.ts

@@ -5,17 +5,24 @@ import { KnowledgeService } from "./knowledge.service";
 import { KnowledgeController } from "./knowledge.controller";
 import { SearchController } from "./search.controller";
 import { KnowledgeStatsController } from "./stats.controller";
+import { ImportExportController } from "./import-export.controller";
 import {
   LinkResolutionService,
   SearchService,
   LinkSyncService,
   GraphService,
   StatsService,
+  ImportExportService,
 } from "./services";
 
 @Module({
   imports: [PrismaModule, AuthModule],
-  controllers: [KnowledgeController, SearchController, KnowledgeStatsController],
+  controllers: [
+    KnowledgeController,
+    SearchController,
+    KnowledgeStatsController,
+    ImportExportController,
+  ],
   providers: [
     KnowledgeService,
     LinkResolutionService,
@@ -23,6 +30,7 @@ import {
     LinkSyncService,
     GraphService,
     StatsService,
+    ImportExportService,
   ],
   exports: [KnowledgeService, LinkResolutionService, SearchService],
 })

apps/api/src/knowledge/services/import-export.service.spec.ts

@@ -0,0 +1,297 @@
+import { describe, it, expect, beforeEach, vi } from "vitest";
+import { Test, TestingModule } from "@nestjs/testing";
+import { BadRequestException } from "@nestjs/common";
+import { ImportExportService } from "./import-export.service";
+import { KnowledgeService } from "../knowledge.service";
+import { PrismaService } from "../../prisma/prisma.service";
+import { ExportFormat } from "../dto";
+import { EntryStatus, Visibility } from "@prisma/client";
+
+describe("ImportExportService", () => {
+  let service: ImportExportService;
+  let knowledgeService: KnowledgeService;
+  let prisma: PrismaService;
+
+  const workspaceId = "workspace-123";
+  const userId = "user-123";
+
+  const mockEntry = {
+    id: "entry-123",
+    workspaceId,
+    slug: "test-entry",
+    title: "Test Entry",
+    content: "Test content",
+    summary: "Test summary",
+    status: EntryStatus.PUBLISHED,
+    visibility: Visibility.WORKSPACE,
+    createdAt: new Date(),
+    updatedAt: new Date(),
+    tags: [
+      {
+        tag: {
+          id: "tag-1",
+          name: "TypeScript",
+          slug: "typescript",
+          color: "#3178c6",
+        },
+      },
+    ],
+  };
+
+  const mockKnowledgeService = {
+    create: vi.fn(),
+    findAll: vi.fn(),
+  };
+
+  const mockPrismaService = {
+    knowledgeEntry: {
+      findMany: vi.fn(),
+    },
+  };
+
+  beforeEach(async () => {
+    const module: TestingModule = await Test.createTestingModule({
+      providers: [
+        ImportExportService,
+        {
+          provide: KnowledgeService,
+          useValue: mockKnowledgeService,
+        },
+        {
+          provide: PrismaService,
+          useValue: mockPrismaService,
+        },
+      ],
+    }).compile();
+
+    service = module.get<ImportExportService>(ImportExportService);
+    knowledgeService = module.get<KnowledgeService>(KnowledgeService);
+    prisma = module.get<PrismaService>(PrismaService);
+
+    vi.clearAllMocks();
+  });
+
+  describe("importEntries", () => {
+    it("should import a single markdown file successfully", async () => {
+      const markdown = `---
+title: Test Entry
+status: PUBLISHED
+tags:
+  - TypeScript
+  - Testing
+---
+
+This is the content of the entry.`;
+
+      const file: Express.Multer.File = {
+        fieldname: "file",
+        originalname: "test.md",
+        encoding: "utf-8",
+        mimetype: "text/markdown",
+        size: markdown.length,
+        buffer: Buffer.from(markdown),
+        stream: null as any,
+        destination: "",
+        filename: "",
+        path: "",
+      };
+
+      mockKnowledgeService.create.mockResolvedValue({
+        id: "entry-123",
+        slug: "test-entry",
+        title: "Test Entry",
+      });
+
+      const result = await service.importEntries(workspaceId, userId, file);
+
+      expect(result.totalFiles).toBe(1);
+      expect(result.imported).toBe(1);
+      expect(result.failed).toBe(0);
+      expect(result.results[0].success).toBe(true);
+      expect(result.results[0].title).toBe("Test Entry");
+      expect(mockKnowledgeService.create).toHaveBeenCalledWith(
+        workspaceId,
+        userId,
+        expect.objectContaining({
+          title: "Test Entry",
+          content: "This is the content of the entry.",
+          status: EntryStatus.PUBLISHED,
+          tags: ["TypeScript", "Testing"],
+        })
+      );
+    });
+
+    it("should use filename as title if frontmatter title is missing", async () => {
+      const markdown = `This is content without frontmatter.`;
+
+      const file: Express.Multer.File = {
+        fieldname: "file",
+        originalname: "my-entry.md",
+        encoding: "utf-8",
+        mimetype: "text/markdown",
+        size: markdown.length,
+        buffer: Buffer.from(markdown),
+        stream: null as any,
+        destination: "",
+        filename: "",
+        path: "",
+      };
+
+      mockKnowledgeService.create.mockResolvedValue({
+        id: "entry-123",
+        slug: "my-entry",
+        title: "my-entry",
+      });
+
+      const result = await service.importEntries(workspaceId, userId, file);
+
+      expect(result.imported).toBe(1);
+      expect(mockKnowledgeService.create).toHaveBeenCalledWith(
+        workspaceId,
+        userId,
+        expect.objectContaining({
+          title: "my-entry",
+          content: "This is content without frontmatter.",
+        })
+      );
+    });
+
+    it("should reject invalid file types", async () => {
+      const file: Express.Multer.File = {
+        fieldname: "file",
+        originalname: "test.txt",
+        encoding: "utf-8",
+        mimetype: "text/plain",
+        size: 100,
+        buffer: Buffer.from("test"),
+        stream: null as any,
+        destination: "",
+        filename: "",
+        path: "",
+      };
+
+      await expect(
+        service.importEntries(workspaceId, userId, file)
+      ).rejects.toThrow(BadRequestException);
+    });
+
+    it("should handle import errors gracefully", async () => {
+      const markdown = `---
+title: Test Entry
+---
+
+Content`;
+
+      const file: Express.Multer.File = {
+        fieldname: "file",
+        originalname: "test.md",
+        encoding: "utf-8",
+        mimetype: "text/markdown",
+        size: markdown.length,
+        buffer: Buffer.from(markdown),
+        stream: null as any,
+        destination: "",
+        filename: "",
+        path: "",
+      };
+
+      mockKnowledgeService.create.mockRejectedValue(
+        new Error("Database error")
+      );
+
+      const result = await service.importEntries(workspaceId, userId, file);
+
+      expect(result.totalFiles).toBe(1);
+      expect(result.imported).toBe(0);
+      expect(result.failed).toBe(1);
+      expect(result.results[0].success).toBe(false);
+      expect(result.results[0].error).toBe("Database error");
+    });
+
+    it("should reject empty markdown content", async () => {
+      const markdown = `---
+title: Empty Entry
+---
+
+`;
+
+      const file: Express.Multer.File = {
+        fieldname: "file",
+        originalname: "empty.md",
+        encoding: "utf-8",
+        mimetype: "text/markdown",
+        size: markdown.length,
+        buffer: Buffer.from(markdown),
+        stream: null as any,
+        destination: "",
+        filename: "",
+        path: "",
+      };
+
+      const result = await service.importEntries(workspaceId, userId, file);
+
+      expect(result.imported).toBe(0);
+      expect(result.failed).toBe(1);
+      expect(result.results[0].error).toBe("Empty content");
+    });
+  });
+
+  describe("exportEntries", () => {
+    it("should export entries as markdown format", async () => {
+      mockPrismaService.knowledgeEntry.findMany.mockResolvedValue([mockEntry]);
+
+      const result = await service.exportEntries(
+        workspaceId,
+        ExportFormat.MARKDOWN
+      );
+
+      expect(result.filename).toMatch(/knowledge-export-\d{4}-\d{2}-\d{2}\.zip/);
+      expect(result.stream).toBeDefined();
+      expect(mockPrismaService.knowledgeEntry.findMany).toHaveBeenCalledWith({
+        where: { workspaceId },
+        include: {
+          tags: {
+            include: {
+              tag: true,
+            },
+          },
+        },
+        orderBy: {
+          title: "asc",
+        },
+      });
+    });
+
+    it("should export only specified entries", async () => {
+      const entryIds = ["entry-123", "entry-456"];
+      mockPrismaService.knowledgeEntry.findMany.mockResolvedValue([mockEntry]);
+
+      await service.exportEntries(workspaceId, ExportFormat.JSON, entryIds);
+
+      expect(mockPrismaService.knowledgeEntry.findMany).toHaveBeenCalledWith({
+        where: {
+          workspaceId,
+          id: { in: entryIds },
+        },
+        include: {
+          tags: {
+            include: {
+              tag: true,
+            },
+          },
+        },
+        orderBy: {
+          title: "asc",
+        },
+      });
+    });
+
+    it("should throw error when no entries found", async () => {
+      mockPrismaService.knowledgeEntry.findMany.mockResolvedValue([]);
+
+      await expect(
+        service.exportEntries(workspaceId, ExportFormat.MARKDOWN)
+      ).rejects.toThrow(BadRequestException);
+    });
+  });
+});

apps/api/src/knowledge/services/import-export.service.ts

@@ -0,0 +1,315 @@
+import { Injectable, BadRequestException } from "@nestjs/common";
+import { EntryStatus, Visibility } from "@prisma/client";
+import * as archiver from "archiver";
+import * as AdmZip from "adm-zip";
+import * as matter from "gray-matter";
+import { Readable } from "stream";
+import { PrismaService } from "../../prisma/prisma.service";
+import { KnowledgeService } from "../knowledge.service";
+import type { ExportFormat, ImportResult } from "../dto";
+import type { CreateEntryDto } from "../dto/create-entry.dto";
+
+/**
+ * Service for handling knowledge entry import/export operations
+ */
+@Injectable()
+export class ImportExportService {
+  constructor(
+    private readonly prisma: PrismaService,
+    private readonly knowledgeService: KnowledgeService
+  ) {}
+
+  /**
+   * Import entries from uploaded file(s)
+   * Accepts single .md file or .zip containing multiple .md files
+   */
+  async importEntries(
+    workspaceId: string,
+    userId: string,
+    file: Express.Multer.File
+  ): Promise<{ results: ImportResult[]; totalFiles: number; imported: number; failed: number }> {
+    const results: ImportResult[] = [];
+
+    try {
+      if (file.mimetype === "text/markdown" || file.originalname.endsWith(".md")) {
+        // Single markdown file
+        const result = await this.importSingleMarkdown(
+          workspaceId,
+          userId,
+          file.originalname,
+          file.buffer.toString("utf-8")
+        );
+        results.push(result);
+      } else if (
+        file.mimetype === "application/zip" ||
+        file.mimetype === "application/x-zip-compressed" ||
+        file.originalname.endsWith(".zip")
+      ) {
+        // Zip file containing multiple markdown files
+        const zipResults = await this.importZipFile(workspaceId, userId, file.buffer);
+        results.push(...zipResults);
+      } else {
+        throw new BadRequestException(
+          "Invalid file type. Only .md and .zip files are accepted."
+        );
+      }
+    } catch (error) {
+      throw new BadRequestException(
+        `Failed to import file: ${error instanceof Error ? error.message : "Unknown error"}`
+      );
+    }
+
+    const imported = results.filter((r) => r.success).length;
+    const failed = results.filter((r) => !r.success).length;
+
+    return {
+      results,
+      totalFiles: results.length,
+      imported,
+      failed,
+    };
+  }
+
+  /**
+   * Import a single markdown file
+   */
+  private async importSingleMarkdown(
+    workspaceId: string,
+    userId: string,
+    filename: string,
+    content: string
+  ): Promise<ImportResult> {
+    try {
+      // Parse frontmatter
+      const parsed = matter(content);
+      const frontmatter = parsed.data;
+      const markdownContent = parsed.content.trim();
+
+      if (!markdownContent) {
+        return {
+          filename,
+          success: false,
+          error: "Empty content",
+        };
+      }
+
+      // Build CreateEntryDto from frontmatter and content
+      const createDto: CreateEntryDto = {
+        title: frontmatter.title || filename.replace(/\.md$/, ""),
+        content: markdownContent,
+        summary: frontmatter.summary,
+        status: this.parseStatus(frontmatter.status),
+        visibility: this.parseVisibility(frontmatter.visibility),
+        tags: Array.isArray(frontmatter.tags) ? frontmatter.tags : undefined,
+        changeNote: "Imported from markdown file",
+      };
+
+      // Create the entry
+      const entry = await this.knowledgeService.create(
+        workspaceId,
+        userId,
+        createDto
+      );
+
+      return {
+        filename,
+        success: true,
+        entryId: entry.id,
+        slug: entry.slug,
+        title: entry.title,
+      };
+    } catch (error) {
+      return {
+        filename,
+        success: false,
+        error: error instanceof Error ? error.message : "Unknown error",
+      };
+    }
+  }
+
+  /**
+   * Import entries from a zip file
+   */
+  private async importZipFile(
+    workspaceId: string,
+    userId: string,
+    buffer: Buffer
+  ): Promise<ImportResult[]> {
+    const results: ImportResult[] = [];
+
+    try {
+      const zip = new AdmZip(buffer);
+      const zipEntries = zip.getEntries();
+
+      for (const zipEntry of zipEntries) {
+        // Skip directories and non-markdown files
+        if (zipEntry.isDirectory || !zipEntry.entryName.endsWith(".md")) {
+          continue;
+        }
+
+        const content = zipEntry.getData().toString("utf-8");
+        const result = await this.importSingleMarkdown(
+          workspaceId,
+          userId,
+          zipEntry.entryName,
+          content
+        );
+        results.push(result);
+      }
+    } catch (error) {
+      throw new BadRequestException(
+        `Failed to extract zip file: ${error instanceof Error ? error.message : "Unknown error"}`
+      );
+    }
+
+    return results;
+  }
+
+  /**
+   * Export entries as a zip file
+   */
+  async exportEntries(
+    workspaceId: string,
+    format: ExportFormat,
+    entryIds?: string[]
+  ): Promise<{ stream: Readable; filename: string }> {
+    // Fetch entries
+    const entries = await this.fetchEntriesForExport(workspaceId, entryIds);
+
+    if (entries.length === 0) {
+      throw new BadRequestException("No entries found to export");
+    }
+
+    // Create archive
+    const archive = archiver("zip", {
+      zlib: { level: 9 },
+    });
+
+    // Add entries to archive
+    for (const entry of entries) {
+      if (format === "markdown") {
+        const markdown = this.entryToMarkdown(entry);
+        const filename = `${entry.slug}.md`;
+        archive.append(markdown, { name: filename });
+      } else {
+        // JSON format
+        const json = JSON.stringify(entry, null, 2);
+        const filename = `${entry.slug}.json`;
+        archive.append(json, { name: filename });
+      }
+    }
+
+    // Finalize archive
+    archive.finalize();
+
+    // Generate filename
+    const timestamp = new Date().toISOString().split("T")[0];
+    const filename = `knowledge-export-${timestamp}.zip`;
+
+    return {
+      stream: archive,
+      filename,
+    };
+  }
+
+  /**
+   * Fetch entries for export
+   */
+  private async fetchEntriesForExport(
+    workspaceId: string,
+    entryIds?: string[]
+  ): Promise<any[]> {
+    const where: any = { workspaceId };
+
+    if (entryIds && entryIds.length > 0) {
+      where.id = { in: entryIds };
+    }
+
+    const entries = await this.prisma.knowledgeEntry.findMany({
+      where,
+      include: {
+        tags: {
+          include: {
+            tag: true,
+          },
+        },
+      },
+      orderBy: {
+        title: "asc",
+      },
+    });
+
+    return entries.map((entry) => ({
+      id: entry.id,
+      slug: entry.slug,
+      title: entry.title,
+      content: entry.content,
+      summary: entry.summary,
+      status: entry.status,
+      visibility: entry.visibility,
+      tags: entry.tags.map((et) => et.tag.name),
+      createdAt: entry.createdAt,
+      updatedAt: entry.updatedAt,
+    }));
+  }
+
+  /**
+   * Convert entry to markdown format with frontmatter
+   */
+  private entryToMarkdown(entry: any): string {
+    const frontmatter: Record<string, any> = {
+      title: entry.title,
+      status: entry.status,
+      visibility: entry.visibility,
+    };
+
+    if (entry.summary) {
+      frontmatter.summary = entry.summary;
+    }
+
+    if (entry.tags && entry.tags.length > 0) {
+      frontmatter.tags = entry.tags;
+    }
+
+    frontmatter.createdAt = entry.createdAt.toISOString();
+    frontmatter.updatedAt = entry.updatedAt.toISOString();
+
+    // Build frontmatter string
+    const frontmatterStr = Object.entries(frontmatter)
+      .map(([key, value]) => {
+        if (Array.isArray(value)) {
+          return `${key}:\n  - ${value.join("\n  - ")}`;
+        }
+        return `${key}: ${value}`;
+      })
+      .join("\n");
+
+    return `---\n${frontmatterStr}\n---\n\n${entry.content}`;
+  }
+
+  /**
+   * Parse status from frontmatter
+   */
+  private parseStatus(value: any): EntryStatus | undefined {
+    if (!value) return undefined;
+    const statusMap: Record<string, EntryStatus> = {
+      DRAFT: EntryStatus.DRAFT,
+      PUBLISHED: EntryStatus.PUBLISHED,
+      ARCHIVED: EntryStatus.ARCHIVED,
+    };
+    return statusMap[String(value).toUpperCase()];
+  }
+
+  /**
+   * Parse visibility from frontmatter
+   */
+  private parseVisibility(value: any): Visibility | undefined {
+    if (!value) return undefined;
+    const visibilityMap: Record<string, Visibility> = {
+      PRIVATE: Visibility.PRIVATE,
+      WORKSPACE: Visibility.WORKSPACE,
+      PUBLIC: Visibility.PUBLIC,
+    };
+    return visibilityMap[String(value).toUpperCase()];
+  }
+}

apps/api/src/knowledge/services/index.ts

@@ -8,3 +8,4 @@ export { LinkSyncService } from "./link-sync.service";
 export { SearchService } from "./search.service";
 export { GraphService } from "./graph.service";
 export { StatsService } from "./stats.service";
+export { ImportExportService } from "./import-export.service";