@lon-ask/dockit 0.1.0

package/apps/server/src/routes/sources.ts

@@ -0,0 +1,105 @@
+import { Router, Request, Response } from 'express';
+import type { ConfigUseCase } from '../core/usecases/ConfigUseCase.js';
+import type { SourceType } from '../core/domain/types.js';
+
+const VALID_TYPES: SourceType[] = ['zip', 'antora', 'maven', 'asciidoc', 'github-markdown', 'source-code'];
+
+function validateConfig(type: SourceType, config: Record<string, unknown>): string | null {
+  switch (type) {
+    case 'maven':
+      if (!config.groupId || typeof config.groupId !== 'string') return 'groupId is required';
+      if (!config.artifactId || typeof config.artifactId !== 'string') return 'artifactId is required';
+      if (!config.version || typeof config.version !== 'string') return 'version is required';
+      return null;
+    case 'zip': {
+      const hasUrl = config.url && typeof config.url === 'string';
+      const hasLocalPath = config.localPath && typeof config.localPath === 'string';
+      if (!hasUrl && !hasLocalPath) return 'url or localPath is required';
+      return null;
+    }
+    case 'antora': {
+      const hasRepoUrl = config.repoUrl && typeof config.repoUrl === 'string';
+      const hasZipPath = config.zipPath && typeof config.zipPath === 'string';
+      const hasLocalPath = config.localPath && typeof config.localPath === 'string';
+      if (!hasRepoUrl && !hasZipPath && !hasLocalPath) return 'repoUrl, localPath, or zipPath is required';
+      return null;
+    }
+    case 'asciidoc': {
+      const hasRepoUrl = config.repoUrl && typeof config.repoUrl === 'string';
+      const hasZipPath = config.zipPath && typeof config.zipPath === 'string';
+      const hasLocalPath = config.localPath && typeof config.localPath === 'string';
+      if (!hasRepoUrl && !hasZipPath && !hasLocalPath) return 'repoUrl, localPath, or zipPath is required';
+      return null;
+    }
+    case 'github-markdown': {
+      const hasRepoUrl = config.repoUrl && typeof config.repoUrl === 'string';
+      const hasLocalPath = config.localPath && typeof config.localPath === 'string';
+      if (!hasRepoUrl && !hasLocalPath) return 'repoUrl or localPath is required';
+      return null;
+    }
+    case 'source-code': {
+      const hasRepoUrl = config.repoUrl && typeof config.repoUrl === 'string';
+      const hasLocalPath = config.localPath && typeof config.localPath === 'string';
+      const hasZipPath = config.zipPath && typeof config.zipPath === 'string';
+      if (!hasRepoUrl && !hasLocalPath && !hasZipPath) return 'repoUrl, localPath, or zipPath is required';
+      return null;
+    }
+    default:
+      return null;
+  }
+}
+
+export function createSourceRoutes(configUseCase: ConfigUseCase): Router {
+  const router = Router({ mergeParams: true });
+
+  router.post('/', async (req: Request, res: Response) => {
+    const entryId = req.params.entryId as string;
+    const entry = await configUseCase.getEntry(entryId);
+    if (!entry) {
+      res.status(404).json({ error: 'Entry not found' });
+      return;
+    }
+
+    const { type, label, config } = req.body as { type: SourceType; label: string; config: Record<string, unknown> };
+
+    if (!type || !VALID_TYPES.includes(type)) {
+      res.status(400).json({ error: `type must be one of: ${VALID_TYPES.join(', ')}` });
+      return;
+    }
+    if (!label) {
+      res.status(400).json({ error: 'label is required' });
+      return;
+    }
+    const configError = validateConfig(type, config);
+    if (configError) {
+      res.status(400).json({ error: configError });
+      return;
+    }
+
+    const source = await configUseCase.createSource(entryId, { type, label, config: config as any });
+    res.status(201).json(source);
+  });
+
+  return router;
+}
+
+export function createSourceFlatRoutes(configUseCase: ConfigUseCase): Router {
+  const router = Router();
+
+  router.put('/:id', async (req: Request, res: Response) => {
+    const id = req.params.id as string;
+    const input = req.body as { label?: string; config?: Record<string, unknown> };
+    await configUseCase.updateSource(id, input);
+    const { SqliteSourceRepository } = await import('../infrastructure/persistence/sqlite/SqliteSourceRepository.js');
+    const source = await new SqliteSourceRepository().findById(id);
+    res.json(source);
+  });
+
+  router.delete('/:id', async (req: Request, res: Response) => {
+    const id = req.params.id as string;
+    await configUseCase.deleteSource(id);
+    res.json({ success: true });
+  });
+
+  return router;
+}

package/apps/server/src/routes/viewer.ts

@@ -0,0 +1,28 @@
+import { Router, Request, Response } from 'express';
+
+import path from 'node:path';
+import fs from 'node:fs';
+import { DATA_ROOT } from '../services/paths.js';
+
+const router = Router();
+
+router.use('/bundle/:entryId', (req: Request, res: Response) => {
+  const entryId = req.params.entryId as string;
+  const filePath = req.path.replace(/^\//, '') || 'index.html';
+  const fullPath = path.resolve(DATA_ROOT, entryId, 'bundle', filePath);
+  const dataRoot = path.resolve(DATA_ROOT);
+
+  if (!fullPath.startsWith(dataRoot)) {
+    res.status(403).json({ error: 'Invalid document path' });
+    return;
+  }
+
+  if (!fs.existsSync(fullPath)) {
+    res.status(404).json({ error: 'Documentation not built yet' });
+    return;
+  }
+
+  res.sendFile(fullPath);
+});
+
+export default router;

package/apps/server/src/services/antora.ts

@@ -0,0 +1,238 @@
+import path from 'node:path';
+import fs from 'node:fs';
+import { execSync, spawn } from 'node:child_process';
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import unzipper from 'unzipper';
+import type { AntoraSourceConfig } from '../core/domain/types.js';
+
+async function cloneRepo(repoUrl: string, targetDir: string, log: (msg: string) => void): Promise<void> {
+  log(`Cloning repository ${repoUrl}`);
+  if (fs.existsSync(targetDir)) fs.rmSync(targetDir, { recursive: true, force: true });
+  return new Promise((resolve, reject) => {
+    const proc = spawn('git', ['clone', '--depth', '1', repoUrl, targetDir], {
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    let stderr = '';
+    proc.stderr?.on('data', (data: Buffer) => {
+      stderr += data.toString();
+      const lines = data.toString().trim().split('\n');
+      for (const line of lines) {
+        if (line) log(`  git: ${line}`);
+      }
+    });
+    proc.on('close', (code) => {
+      if (code === 0) {
+        log('Repository cloned successfully');
+        resolve();
+      } else {
+        reject(new Error(`git clone failed with code ${code}: ${stderr}`));
+      }
+    });
+    proc.on('error', reject);
+  });
+}
+
+async function extractZip(zipPath: string, targetDir: string, log: (msg: string) => void): Promise<void> {
+  log(`Extracting local ZIP from ${zipPath}`);
+  fs.mkdirSync(targetDir, { recursive: true });
+  const data = fs.readFileSync(zipPath);
+  const stream = Readable.from(data);
+  await pipeline(stream, unzipper.Extract({ path: targetDir }));
+
+  const entries = fs.readdirSync(targetDir);
+  if (entries.length === 1 && fs.statSync(path.join(targetDir, entries[0])).isDirectory()) {
+    log('Detected single root directory in ZIP, flattening...');
+    const innerDir = path.join(targetDir, entries[0]);
+    const innerEntries = fs.readdirSync(innerDir);
+    for (const entry of innerEntries) {
+      const src = path.join(innerDir, entry);
+      const dest = path.join(targetDir, entry);
+      fs.renameSync(src, dest);
+    }
+    fs.rmdirSync(innerDir);
+  }
+
+  log(`Extracted ZIP to ${targetDir}`);
+}
+
+function findAntoraYmlFiles(dir: string): string[] {
+  const results: string[] = [];
+  const stack = [dir];
+  while (stack.length > 0) {
+    const current = stack.pop()!;
+    const entries = fs.readdirSync(current, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.name.startsWith('.')) continue;
+      if (entry.name === 'node_modules') continue;
+      const fullPath = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        stack.push(fullPath);
+      } else if (entry.name === 'antora.yml') {
+        results.push(fullPath);
+      }
+    }
+  }
+  return results;
+}
+
+function findExistingPlaybook(contentDir: string): string | null {
+  const candidates = ['antora-playbook.yml', 'site.yml', 'antora-playbook.yaml', 'site.yaml'];
+  for (const name of candidates) {
+    const p = path.join(contentDir, name);
+    if (fs.existsSync(p)) return p;
+  }
+  return null;
+}
+
+function generatePlaybook(
+  entryId: string,
+  contentDir: string,
+  outputDir: string,
+  startPaths: string[],
+  log: (msg: string) => void
+): string {
+  let sourcesYaml: string;
+  if (startPaths.length === 0) {
+    log('  No antora.yml files found — Antora will scan entire repository');
+    sourcesYaml = `    - url: ${contentDir}\n      branches: HEAD`;
+  } else {
+    log(`  Found ${startPaths.length} antora.yml file(s)`);
+    if (startPaths.length === 1) {
+      const rel = path.relative(contentDir, path.dirname(startPaths[0]));
+      log(`  Using start_path: ${rel || '.'}`);
+      sourcesYaml = `    - url: ${contentDir}\n      branches: HEAD\n      start_path: ${rel || '.'}`;
+    } else {
+      const paths = startPaths
+        .map((f) => path.relative(contentDir, path.dirname(f)))
+        .filter((p) => p.length > 0);
+      const pathsStr = paths.length > 0
+        ? `\n${paths.map((p) => `        - ${p}`).join('\n')}`
+        : '';
+      sourcesYaml = `    - url: ${contentDir}\n      branches: HEAD\n      start_paths:${pathsStr}`;
+    }
+  }
+
+  return `
+site:
+  title: Dockit — ${entryId}
+  url: /api/bundle/${entryId}
+content:
+  sources:
+${sourcesYaml}
+ui:
+  bundle:
+    url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?job=bundle-stable
+    snapshot: true
+output:
+  dir: ${outputDir}
+`.trim();
+}
+
+function generatePlaybookFromExisting(playbookPath: string, outputDir: string): string {
+  const raw = fs.readFileSync(playbookPath, 'utf-8');
+  if (raw.includes('output:') && raw.includes('dir:')) {
+    return raw;
+  }
+  return raw + `\noutput:\n  dir: ${outputDir}\n`;
+}
+
+async function runAntora(playbookPath: string, log: (msg: string) => void): Promise<void> {
+  log(`Running Antora with playbook ${playbookPath}`);
+  return new Promise((resolve, reject) => {
+    const proc = spawn('npx', ['antora', playbookPath], {
+      stdio: ['ignore', 'pipe', 'pipe'],
+      cwd: path.dirname(playbookPath),
+      env: { ...process.env, CI: 'true' },
+    });
+
+    let stderr = '';
+    proc.stdout?.on('data', (data: Buffer) => {
+      const lines = data.toString().trim().split('\n');
+      for (const line of lines) {
+        if (line) log(`  antora: ${line}`);
+      }
+    });
+    proc.stderr?.on('data', (data: Buffer) => {
+      stderr += data.toString();
+    });
+
+    proc.on('close', (code) => {
+      if (code === 0) {
+        log('Antora build completed successfully');
+        resolve();
+      } else {
+        const tail = stderr.slice(-800);
+        log(`Antora build failed (stderr: ${tail})`);
+        reject(new Error(`Antora build failed with code ${code}`));
+      }
+    });
+    proc.on('error', reject);
+  });
+}
+
+export async function buildAntoraSource(
+  config: AntoraSourceConfig,
+  entryId: string,
+  workDir: string,
+  log: (msg: string) => void
+): Promise<string> {
+  let contentDir: string;
+  let cleanupDir: string | undefined;
+
+  if (config.localPath) {
+    if (!fs.existsSync(config.localPath)) {
+      throw new Error(`Local path not found: ${config.localPath}`);
+    }
+    if (!fs.statSync(config.localPath).isDirectory()) {
+      throw new Error(`localPath must be a directory: ${config.localPath}`);
+    }
+    log(`Using local directory: ${config.localPath}`);
+    contentDir = config.localPath;
+  } else if (config.repoUrl) {
+    contentDir = path.join(workDir, 'content');
+    await cloneRepo(config.repoUrl, contentDir, log);
+    cleanupDir = contentDir;
+  } else if (config.zipPath) {
+    contentDir = path.join(workDir, 'content');
+    await extractZip(config.zipPath, contentDir, log);
+    cleanupDir = contentDir;
+  } else {
+    throw new Error('Antora source requires repoUrl, localPath, or zipPath');
+  }
+
+  const playbookPath = path.join(workDir, 'antora-playbook.yml');
+  const outputDir = path.join(workDir, 'output');
+  const existingPlaybook = findExistingPlaybook(contentDir);
+
+  if (existingPlaybook) {
+    log(`Found existing playbook at ${path.relative(contentDir, existingPlaybook)}`);
+    const playbookContent = generatePlaybookFromExisting(existingPlaybook, outputDir);
+    fs.writeFileSync(playbookPath, playbookContent, 'utf-8');
+  } else {
+    const antoraFiles = findAntoraYmlFiles(contentDir);
+    if (antoraFiles.length === 0) {
+      throw new Error(
+        `No antora.yml files found in repository. ` +
+        `This repo does not appear to be an Antora-based documentation source. ` +
+        `Use a ZIP or Maven source type instead, or provide the URL to the specific ` +
+        `Antora documentation repository (e.g. a repo containing antora.yml files).`
+      );
+    }
+    const playbookContent = generatePlaybook(entryId, contentDir, outputDir, antoraFiles, log);
+    fs.writeFileSync(playbookPath, playbookContent, 'utf-8');
+  }
+
+  await runAntora(playbookPath, log);
+
+  return outputDir;
+}
+
+export function ensureAntoraInstalled(): boolean {
+  try {
+    execSync('npx antora --version', { stdio: 'pipe' });
+    return true;
+  } catch {
+    return false;
+  }
+}

package/apps/server/src/services/asciidoc.ts

@@ -0,0 +1,221 @@
+import path from 'node:path';
+import fs from 'node:fs';
+import os from 'node:os';
+import { spawn } from 'node:child_process';
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import unzipper from 'unzipper';
+import asciidoctorModule from '@asciidoctor/core';
+import type { AsciidocSourceConfig } from '../core/domain/types.js';
+
+type Processor = {
+  convertFile(file: string, options?: Record<string, unknown>): unknown;
+};
+const asciidoctor = asciidoctorModule as unknown as () => Processor;
+
+const SKIP_DIRS = new Set([
+  'node_modules', 'target', 'build', 'dist', '.git',
+  'integrations', 'extensions', 'independent-projects',
+  'test', 'tests', 'tcks',
+]);
+
+async function cloneRepo(repoUrl: string, targetDir: string, log: (msg: string) => void): Promise<void> {
+  log(`Cloning repository ${repoUrl}`);
+  if (fs.existsSync(targetDir)) fs.rmSync(targetDir, { recursive: true, force: true });
+  return new Promise((resolve, reject) => {
+    const proc = spawn('git', ['clone', '--depth', '1', repoUrl, targetDir], {
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    let stderr = '';
+    proc.stderr?.on('data', (data: Buffer) => {
+      stderr += data.toString();
+      const lines = data.toString().trim().split('\n');
+      for (const line of lines) {
+        if (line) log(`  git: ${line}`);
+      }
+    });
+    proc.on('close', (code) => {
+      if (code === 0) {
+        log('Repository cloned successfully');
+        resolve();
+      } else {
+        reject(new Error(`git clone failed with code ${code}: ${stderr}`));
+      }
+    });
+    proc.on('error', reject);
+  });
+}
+
+async function extractZip(zipPath: string, targetDir: string, log: (msg: string) => void): Promise<void> {
+  log(`Extracting local ZIP from ${zipPath}`);
+  fs.mkdirSync(targetDir, { recursive: true });
+  const data = fs.readFileSync(zipPath);
+  const stream = Readable.from(data);
+  await pipeline(stream, unzipper.Extract({ path: targetDir }));
+
+  const entries = fs.readdirSync(targetDir);
+  if (entries.length === 1 && fs.statSync(path.join(targetDir, entries[0])).isDirectory()) {
+    log('Detected single root directory, flattening...');
+    const innerDir = path.join(targetDir, entries[0]);
+    const innerEntries = fs.readdirSync(innerDir);
+    for (const entry of innerEntries) {
+      fs.renameSync(path.join(innerDir, entry), path.join(targetDir, entry));
+    }
+    fs.rmdirSync(innerDir);
+  }
+  log(`Extracted ZIP to ${targetDir}`);
+}
+
+function findAdocFiles(dir: string, sourcePath: string): string[] {
+  const root = sourcePath ? path.join(dir, sourcePath) : dir;
+  if (!fs.existsSync(root)) {
+    return [];
+  }
+  const results: string[] = [];
+  const stack = [root];
+  while (stack.length > 0) {
+    const current = stack.pop()!;
+    let entries: fs.Dirent[];
+    try {
+      entries = fs.readdirSync(current, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      if (entry.name.startsWith('.') || SKIP_DIRS.has(entry.name)) continue;
+      const fullPath = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        stack.push(fullPath);
+      } else if (entry.name.endsWith('.adoc')) {
+        results.push(fullPath);
+      }
+    }
+  }
+  return results;
+}
+
+async function runAsciidoctor(
+  adocFiles: string[],
+  sourceRoot: string,
+  targetDir: string,
+  log: (msg: string) => void
+): Promise<void> {
+  log(`Converting ${adocFiles.length} .adoc files to HTML`);
+
+  const adoc = asciidoctor();
+  let filesProcessed = 0;
+  let filesSkipped = 0;
+
+  for (const adocFile of adocFiles) {
+    try {
+      const relPath = path.relative(sourceRoot, adocFile);
+      const outDir = path.join(targetDir, path.dirname(relPath));
+      fs.mkdirSync(outDir, { recursive: true });
+
+      adoc.convertFile(adocFile, {
+        to_dir: outDir,
+        base_dir: path.dirname(adocFile),
+        mkdirs: true,
+        safe: 'unsafe',
+      });
+      filesProcessed++;
+    } catch (err: any) {
+      const rel = path.relative(sourceRoot, adocFile);
+      log(`  WARNING: Failed to convert ${rel}: ${err.message || err}`);
+      filesSkipped++;
+    }
+  }
+
+  const htmlCount = countHtmlFiles(targetDir);
+  log(`AsciiDoc conversion complete: ${filesProcessed} converted, ${filesSkipped} skipped, ${htmlCount} HTML files generated`);
+
+  if (htmlCount === 0 && filesProcessed === 0) {
+    throw new Error('Asciidoctor failed to produce any HTML. Check that the source files are valid.');
+  }
+}
+
+function countHtmlFiles(dir: string): number {
+  if (!fs.existsSync(dir)) return 0;
+  let count = 0;
+  const stack = [dir];
+  while (stack.length > 0) {
+    const current = stack.pop()!;
+    let entries: fs.Dirent[];
+    try { entries = fs.readdirSync(current, { withFileTypes: true }); } catch { continue; }
+    for (const e of entries) {
+      const p = path.join(current, e.name);
+      if (e.isDirectory() && !e.name.startsWith('.')) stack.push(p);
+      else if (e.name.endsWith('.html')) count++;
+    }
+  }
+  return count;
+}
+
+function rmDir(dir: string): void {
+  try {
+    fs.rmSync(dir, { recursive: true, force: true });
+  } catch {
+    // best-effort cleanup
+  }
+}
+
+export async function buildAsciidocSource(
+  config: AsciidocSourceConfig,
+  targetDir: string,
+  log: (msg: string) => void
+): Promise<void> {
+  let repoDir: string;
+  let shouldCleanup: boolean;
+
+  if (config.localPath) {
+    if (!fs.existsSync(config.localPath)) {
+      throw new Error(`Local path not found: ${config.localPath}`);
+    }
+    if (!fs.statSync(config.localPath).isDirectory()) {
+      throw new Error(`localPath must be a directory: ${config.localPath}`);
+    }
+    log(`Using local directory: ${config.localPath}`);
+    repoDir = config.localPath;
+    shouldCleanup = false;
+  } else if (config.repoUrl) {
+    repoDir = path.join(os.tmpdir(), `dockit-asciidoc-${Date.now()}`);
+    await cloneRepo(config.repoUrl, repoDir, log);
+    shouldCleanup = true;
+  } else if (config.zipPath) {
+    repoDir = path.join(os.tmpdir(), `dockit-asciidoc-${Date.now()}`);
+    fs.mkdirSync(repoDir, { recursive: true });
+    await extractZip(config.zipPath, repoDir, log);
+    shouldCleanup = true;
+  } else {
+    throw new Error('AsciiDoc source requires repoUrl, localPath, or zipPath');
+  }
+
+  try {
+    const sourcePath = config.sourcePath || '';
+    const sourceRoot = sourcePath ? path.join(repoDir, sourcePath) : repoDir;
+
+    log(`Scanning for .adoc files in ${sourcePath || 'repository root'}`);
+    const adocFiles = findAdocFiles(repoDir, sourcePath);
+
+    if (adocFiles.length === 0) {
+      if (sourcePath) {
+        throw new Error(`No .adoc files found at path "${sourcePath}" in the repository`);
+      }
+      throw new Error(
+        `No .adoc files found in the repository. ` +
+        `If the docs live in a subdirectory, set the "sourcePath" field ` +
+        `(e.g. "docs/src/main/asciidoc" for Quarkus).`
+      );
+    }
+
+    log(`Found ${adocFiles.length} .adoc file(s)`);
+
+    fs.mkdirSync(targetDir, { recursive: true });
+    await runAsciidoctor(adocFiles, sourceRoot, targetDir, log);
+  } finally {
+    if (shouldCleanup && fs.existsSync(repoDir)) {
+      log('Cleaning up cloned repository...');
+      rmDir(repoDir);
+    }
+  }
+}