feat: Add link checker and enhance CLI tools

# Changelog - CLI Tools & Link Checker

## 2026-01-09 - CLI Tools Enhancement

### 🎯 Přidané funkce

#### 1. Link Checker

- **Nový soubor**: `scripts/link-checker.js`

- Automatická kontrola dostupnosti všech archivů

- Kontrola hlavní stránky a Traefik dashboardu

- Generování JSON reportu s výsledky

- Konfigurovatelný timeout a základní URL

- CLI rozhraní s parametry `--url` a `--timeout`

**Použití:**

```bash

node scripts/cli.js check-links --url=http://localhost:1337 --timeout=5000

npm run links:check

npm run links:quick  # Rychlá kontrola vybraných archivů

```

#### 2. Docker příkazy v CLI

- `docker-up` - Spustit všechny kontejnery

- `docker-down` - Zastavit všechny kontejnery

- `docker-ps` - Status kontejnerů

- `docker-logs [service]` - Zobrazit logy

**Použití:**

```bash

node scripts/cli.js docker-up

npm run docker:up

npm run docker:ps

```

#### 3. Generate Compose příkaz

- `generate-compose` - Vygenerovat docker-compose.yml

- Automatická detekce festival-XX složek

- Rozpoznání SPA frameworků (archives 20-23)

- Správné nginx konfigurace pro každý typ

**Použití:**

```bash

node scripts/cli.js generate-compose

npm run docker:generate

```

### 📝 Aktualizované soubory

#### `scripts/cli.js`

- Přidány imports pro `execSync`, `fileURLToPath`, `dirname`

- Nové case větve ve switch pro nové příkazy

- Vylepšený help text s kompletním seznamem příkazů

#### `scripts/generate-compose.js`

- `CONFIG.maxArchive`: 25 → 23

- `CONFIG.spaArchives`: `[21,22,23,24,25]` → `[20,21,22,23]`

- Nginx config pro SPAs: `nginx-archive-spa.conf` → `nginx-spa-with-base.conf`

#### `scripts/link-checker.js`

- Přepsáno z CommonJS na ES modules

- `require()` → `import`

- `module.exports` → `export default`

- `require.main === module` → vlastní detekce main modulu

#### `package.json`

- Přidány nové npm skripty:

  - `docker:ps` - Status kontejnerů

  - `links:check` - Kompletní kontrola odkazů

  - `links:quick` - Rychlá kontrola vybraných archivů

  - `links:test` - Test základní funkčnosti

- Upraveny existující skripty:

  - `docker:generate` - Volá CLI místo přímého scriptu

  - `docker:up` - Odstraněna automatická regenerace

### 📚 Nová dokumentace

#### `CLI-TOOLS.md`

Kompletní dokumentace všech CLI nástrojů:

- Docker management příkazy

- Docker Compose generation

- Link checking nástroje

- Deployment příkazy

- Příklady použití

- Troubleshooting

- Output formáty

#### `README.md`

- Přidána sekce "📖 Dokumentace" s odkazy

- Přidána sekce "🐳 Docker Hosting" s quick start

### 🧪 Testovací soubory

#### `scripts/test-link-checker.js`

- Základní test link checkeru

- Kontrola jednoho archivu

- Test hlavní stránky a Traefik

#### `scripts/quick-link-check.js`

- Rychlá kontrola vybraných archivů (1, 2, 3, 20-23)

- Mix statických HTML a SPA frameworků

- Krátký běh pro quick feedback

#### `scripts/test-integration.js`

- Integrační testy všech nových funkcí

- Testuje generování docker-compose

- Testuje Docker příkazy

- Testuje link checker modul

- Testuje CLI help

- Ověřuje package.json skripty

### ✅ Výsledky testů

```

🧪 Festival Archive CLI Integration Test

✅ Generate docker-compose.yml - PASSED

✅ Check Docker status - PASSED  

✅ Link checker module - PASSED

✅ CLI help/commands - PASSED

✅ Package.json scripts - PASSED

📊 TEST RESULTS

✅ Passed: 5/5

❌ Failed: 0/5

```

### 🔄 Workflow

**Před změnami:**

```bash

node scripts/generate-compose.js

docker-compose up -d

# Manuální testování v prohlížeči

```

**Po změnách:**

```bash

npm run docker:generate

npm run docker:up

npm run links:quick

# Automatická kontrola funkčnosti

```

### 📊 Statistiky

- **Nové soubory**: 5 (link-checker.js, quick-link-check.js, test-link-checker.js, test-integration.js, CLI-TOOLS.md)

- **Upravené soubory**: 4 (cli.js, generate-compose.js, package.json, README.md)

- **Nové CLI příkazy**: 5 (check-links, docker-up, docker-down, docker-logs, docker-ps)

- **Nové npm skripty**: 4 (docker:ps, links:check, links:quick, links:test)

- **Řádky dokumentace**: ~350 (CLI-TOOLS.md)

### 🎯 Benefit

1. **Automatizace** - Vše lze ovládat z CLI bez manuálního testování

2. **Monitoring** - Link checker automaticky kontroluje funkčnost

3. **Konzistence** - generate-compose.js nyní přesně odpovídá současnému stavu

4. **Dokumentace** - Kompletní dokumentace všech nástrojů

5. **Testovatelnost** - Integrační testy zajišťují správnou funkčnost

### 🚀 Co dál?

Možná další vylepšení:

- CI/CD integrace - automatické link checking při každém commitu

- Grafické reporty z link checkeru

- Email notifikace při broken links

- Health check endpoint pro monitoring

- Docker Compose watch mode pro automatické reloading při změnách

# CLI Tools Documentation

## Overview

Festival Archive projekt obsahuje několik CLI nástrojů pro správu Docker infrastruktury a kontrolu funkčnosti archivů.

## Dostupné příkazy

### Docker Management

```bash

# Spustit všechny kontejnery

node scripts/cli.js docker-up

npm run docker:up

# Zastavit všechny kontejnery

node scripts/cli.js docker-down

npm run docker:down

# Zobrazit status kontejnerů

node scripts/cli.js docker-ps

npm run docker:ps

# Zobrazit logy (všech služeb nebo konkrétní)

node scripts/cli.js docker-logs [service]

npm run docker:logs

# Restartovat kontejnery

npm run docker:restart

```

### Docker Compose Generation

```bash

# Vygenerovat docker-compose.yml ze současných festival-XX složek

node scripts/cli.js generate-compose

npm run docker:generate

```

Tento příkaz:

- Automaticky detekuje všechny `festival-XX` složky

- Rozpozná SPA frameworky (Nuxt.js/Gatsby) pro archivy 20-23

- Vygeneruje kompletní docker-compose.yml s Traefik reverse proxy

- Nastaví správné nginx konfigurace pro každý typ archivu

### Link Checking

```bash

# Kompletní kontrola všech 23 archivů

node scripts/cli.js check-links --url=http://localhost:1337 --timeout=5000

npm run links:check

# Rychlá kontrola vybraných archivů (01, 02, 03, 20-23)

node scripts/quick-link-check.js

npm run links:quick

# Test základní funkčnosti

node scripts/test-link-checker.js

npm run links:test

```

Link checker kontroluje:

- ✅ Dostupnost hlavní stránky (http://localhost:1337)

- ✅ Dostupnost Traefik dashboardu (http://localhost:8080)

- ✅ Dostupnost všech archivů (http://localhost:1337/archive/XX/)

- 📊 Generuje JSON report do `link-check-report.json`

#### Parametry

- `--url` - Základní URL pro kontrolu (výchozí: http://localhost:1337)

- `--timeout` - Timeout pro HTTP požadavky v ms (výchozí: 5000)

### Deployment Commands

```bash

# Export archivů

node scripts/cli.js export

npm run export

# Deploy na server přes Git

node scripts/cli.js deploy

npm run deploy

# Lokální deployment

node scripts/cli.js deploy-local

npm run deploy:local

# Záloha ze serveru

node scripts/cli.js backup

npm run backup

# Cleanup export složky

node scripts/cli.js cleanup

npm run cleanup

```

## Příklady použití

### Kompletní workflow

```bash

# 1. Vygenerovat docker-compose.yml

npm run docker:generate

# 2. Spustit kontejnery

npm run docker:up

# 3. Zkontrolovat status

npm run docker:ps

# 4. Rychlá kontrola funkčnosti

npm run links:quick

# 5. Kompletní kontrola všech archivů

npm run links:check

```

### Debugging

```bash

# Zobrazit logy všech služeb

npm run docker:logs

# Zobrazit logy konkrétní služby

node scripts/cli.js docker-logs traefik

node scripts/cli.js docker-logs archive-20

# Restartovat kontejnery při problémech

npm run docker:restart

```

### Pravidelná kontrola

```bash

# Nastavit cronjoem pravidelnou kontrolu odkazů

# Linux/Mac:

0 2 * * * cd /path/to/archive && npm run links:check >> logs/link-check.log 2>&1

# Windows Task Scheduler:

# Program: npm

# Arguments: run links:check

# Start in: C:\path\to\archive

```

## Output

### Link Check Report

Report se ukládá do `link-check-report.json`:

```json

{

  "timestamp": "2026-01-09T16:08:09.000Z",

  "duration": "1.61s",

  "mainSite": {

    "url": "http://localhost:1337",

    "status": "ok",

    "statusCode": 200

  },

  "traefik": {

    "url": "http://localhost:8080",

    "status": "ok",

    "statusCode": 301

  },

  "archives": [

    {

      "archive": 1,

      "accessible": true,

      "links": [...]

    }

  ]

}

```

### Console Output

```

🔗 Quick Link Check

Testing archives: 01, 02, 03, 20, 21, 22, 23

(mix of static HTML and SPA frameworks)

🔍 Starting link checker...

Base URL: http://localhost:1337

Archives to check: 7

🏠 Checking main website...

✅ Main website is accessible

🔧 Checking Traefik dashboard...

✅ Traefik dashboard is accessible

📦 Checking archive 1...

✅ Archive 1 is accessible

============================================================

📊 SUMMARY

============================================================

⏱️  Duration: 1.61s

🏠 Main site: ✅

🔧 Traefik: ✅

📦 Archives: 7/7 accessible

📝 Report saved to: link-check-report.json

```

## Troubleshooting

### Docker kontejnery neběží

```bash

# Zkontrolovat status

npm run docker:ps

# Zkontrolovat logy

npm run docker:logs

# Restartovat

npm run docker:restart

```

### Link checker hlásí chyby

1. Zkontrolujte, že Docker kontejnery běží: `npm run docker:ps`

2. Ověřte, že Traefik je dostupný: otevřete http://localhost:8080

3. Ověřte hlavní stránku: otevřete http://localhost:1337

4. Zvyšte timeout: `node scripts/cli.js check-links --timeout=10000`

### Změny v archivech se neprojeví

```bash

# Regenerovat docker-compose.yml

npm run docker:generate

# Restartovat kontejnery

npm run docker:restart

```

## Interaktivní režim

Pokud spustíte CLI bez parametrů, zobrazí se interaktivní menu:

```bash

node scripts/cli.js

# nebo

npm start

```

```

 ╭──────────────────────────────────────────────────────╮ 

 │  🎬 Festival Archive Deployment Tool                 │ 

 ╰──────────────────────────────────────────────────────╯ 

 Select an action to perform:

   📦 Export Archive

   🚀 Deploy to Server

 ❯ 🏠 Deploy Locally

   💾 Backup from Server

   🧹 Cleanup

```

## Poznámky

- Link checker automaticky detekuje timeout a retry chyby

- Docker příkazy vyžadují běžící Docker Desktop

- Generování docker-compose.yml nerestartuje kontejnery automaticky

- SPA archivy (20-23) mají známé problémy s assety - viz KNOWN-ISSUES.md

npm run cleanup         # Vyčistit web-archive složku

```

## 📋 Funkce

## � Dokumentace

- **[CLI-TOOLS.md](CLI-TOOLS.md)** - Kompletní dokumentace CLI nástrojů pro Docker a link checking

- **[README-DEPLOY.md](README-DEPLOY.md)** - Deployment dokumentace

- **[KNOWN-ISSUES.md](KNOWN-ISSUES.md)** - Známé problémy a jejich řešení

## 🐳 Docker Hosting

Projekt obsahuje Docker infrastrukturu pro lokální hosting všech archivů:

```bash

# Vygenerovat docker-compose.yml

npm run docker:generate

# Spustit kontejnery

npm run docker:up

# Zkontrolovat status

npm run docker:ps

# Zkontrolovat funkčnost

npm run links:quick

```

Více informací v [CLI-TOOLS.md](CLI-TOOLS.md).

## �📋 Funkce

### 🎨 Interaktivní CLI

		"deploy:local": "node scripts/cli.js deploy-local",

		"backup": "node scripts/deploy.js --backup",

		"cleanup": "node scripts/cli.js cleanup",

		"docker:generate": "node scripts/generate-compose.js",

		"docker:up": "npm run docker:generate && docker-compose up -d",

		"docker:generate": "node scripts/cli.js generate-compose",

		"docker:up": "docker-compose up -d",

		"docker:down": "docker-compose down",

		"docker:restart": "npm run docker:down && npm run docker:up",

		"docker:logs": "docker-compose logs -f"

		"docker:logs": "docker-compose logs -f",

		"docker:ps": "docker-compose ps",

		"links:check": "node scripts/cli.js check-links",

		"links:quick": "node scripts/quick-link-check.js",

		"links:test": "node scripts/test-link-checker.js"

	},

	"keywords": [

		"deploy",

import fs from "fs";

import path from "path";

import { fileURLToPath } from "url";

import { dirname } from "path";

import { execSync } from "child_process";

import React, { useState, useEffect } from "react";

import { render, Box, Text } from "ink";

import { Select, Spinner, ProgressBar, StatusMessage } from "@inkjs/ui";

  createTarArchive,

} from "./deploy.js";

const __filename = fileURLToPath(import.meta.url);

const __dirname = dirname(__filename);

const e = React.createElement;

const ENV_PATH = path.join(process.cwd(), ".env");

        console.log("✅ Cleanup completed!");

        break;

      case "generate-compose":

        console.log("🔧 Generating docker-compose.yml...");

        try {

          execSync("node scripts/generate-compose.js", {

            cwd: process.cwd(),

            stdio: "inherit",

          });

          console.log("✅ docker-compose.yml generated successfully!");

        } catch (error) {

          console.error("❌ Failed to generate docker-compose.yml");

          process.exit(1);

        }

        break;

      case "check-links":

        const urlArg =

          args.find((arg) => arg.startsWith("--url="))?.split("=")[1] ||

          "http://localhost:1337";

        const timeoutArg =

          parseInt(

            args.find((arg) => arg.startsWith("--timeout="))?.split("=")[1]

          ) || 5000;

        console.log(`🔗 Checking links at ${urlArg}...`);

        console.log(`⏱️  Timeout: ${timeoutArg}ms\n`);

        try {

          execSync(

            `node scripts/link-checker.js --url ${urlArg} --timeout ${timeoutArg}`,

            {

              cwd: process.cwd(),

              stdio: "inherit",

            }

          );

        } catch (error) {

          console.error("❌ Link checking failed");

          process.exit(1);

        }

        break;

      case "docker-up":

        console.log("🐳 Starting Docker containers...");

        try {

          execSync("docker-compose up -d", {

            cwd: process.cwd(),

            stdio: "inherit",

          });

          console.log("✅ Docker containers started!");

        } catch (error) {

          console.error("❌ Failed to start Docker containers");

          process.exit(1);

        }

        break;

      case "docker-down":

        console.log("🐳 Stopping Docker containers...");

        try {

          execSync("docker-compose down", {

            cwd: process.cwd(),

            stdio: "inherit",

          });

          console.log("✅ Docker containers stopped!");

        } catch (error) {

          console.error("❌ Failed to stop Docker containers");

          process.exit(1);

        }

        break;

      case "docker-logs":

        const service = args[1] || "";

        console.log(

          service

            ? `📜 Showing logs for ${service}...`

            : "📜 Showing logs for all services..."

        );

        try {

          execSync(`docker-compose logs -f ${service}`, {

            cwd: process.cwd(),

            stdio: "inherit",

          });

        } catch (error) {

          // User interrupted with Ctrl+C

          process.exit(0);

        }

        break;

      case "docker-ps":

        console.log("🐳 Docker containers status:\n");

        try {

          execSync("docker-compose ps", {

            cwd: process.cwd(),

            stdio: "inherit",

          });

        } catch (error) {

          console.error("❌ Failed to get Docker status");

          process.exit(1);

        }

        break;

      default:

        console.log("❌ Unknown command:", command);

        console.log("Available commands:");

        console.log("  export          - Export archives");

        console.log("  deploy          - Deploy to server via Git");

        console.log("  deploy-local    - Deploy locally");

        console.log("  backup          - Create backup");

        console.log("  cleanup         - Clean up export directory");

        console.log("  generate-compose - Generate docker-compose.yml");

        console.log(

          "Available commands: export, deploy (or server), deploy-local, backup, cleanup"

          "  check-links     - Check all archive links (--url=... --timeout=...)"

        );

        console.log("  docker-up       - Start Docker containers");

        console.log("  docker-down     - Stop Docker containers");

        console.log("  docker-logs     - Show Docker logs [service]");

        console.log("  docker-ps       - Show Docker container status");

        process.exit(1);

    }

  } catch (error) {