aury-boot 0.0.2__py3-none-any.whl → 0.0.4__py3-none-any.whl

aury/boot/commands/docker.py

@@ -0,0 +1,367 @@
+"""Docker 相关命令。
+
+生成 Docker 配置文件：
+- Dockerfile
+- docker-compose.yml
+- .dockerignore
+
+使用示例：
+    aury docker init
+    aury docker init --force
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from rich.console import Console
+from rich.panel import Panel
+import typer
+
+from .config import get_project_config
+
+console = Console()
+
+# 创建 docker 子应用
+app = typer.Typer(
+    name="docker",
+    help="Docker 配置文件生成",
+    no_args_is_help=True,
+)
+
+
+# ============================================================
+# 模板
+# ============================================================
+
+DOCKERFILE_TEMPLATE = '''# =============================================================================
+# {project_name} Dockerfile
+# =============================================================================
+# 多阶段构建优化镜像大小
+
+# 基础镜像
+FROM python:3.13-slim AS base
+
+ENV PYTHONDONTWRITEBYTECODE=1 \\
+    PYTHONUNBUFFERED=1 \\
+    PIP_NO_CACHE_DIR=1 \\
+    PIP_DISABLE_PIP_VERSION_CHECK=1
+
+WORKDIR /app
+
+# 安装系统依赖
+RUN apt-get update && apt-get install -y --no-install-recommends \\
+    curl \\
+    && rm -rf /var/lib/apt/lists/*
+
+# -----------------------------------------------------------------------------
+# 构建阶段：安装依赖
+# -----------------------------------------------------------------------------
+FROM base AS builder
+
+# 安装 uv
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /bin/uv
+
+# 复制依赖文件
+COPY pyproject.toml uv.lock* ./
+
+# 安装依赖到虚拟环境
+RUN uv sync --frozen --no-dev --no-install-project
+
+# -----------------------------------------------------------------------------
+# 运行阶段
+# -----------------------------------------------------------------------------
+FROM base AS runtime
+
+# 从 builder 复制虚拟环境
+COPY --from=builder /app/.venv /app/.venv
+
+# 设置 PATH
+ENV PATH="/app/.venv/bin:$PATH"
+
+# 复制应用代码
+COPY . .
+
+# 创建非 root 用户
+RUN useradd --create-home --shell /bin/bash appuser && \\
+    chown -R appuser:appuser /app
+USER appuser
+
+# 健康检查
+HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \\
+    CMD curl -f http://localhost:8000/health || exit 1
+
+# 默认命令
+CMD ["aury", "server", "prod"]
+'''
+
+
+DOCKER_COMPOSE_TEMPLATE = '''# =============================================================================
+# {project_name} Docker Compose
+# =============================================================================
+# 服务编排配置
+
+services:
+  # ---------------------------------------------------------------------------
+  # 基础服务（共享配置）
+  # ---------------------------------------------------------------------------
+  base: &base
+    build:
+      context: .
+      dockerfile: Dockerfile
+    env_file:
+      - .env
+    volumes:
+      - ./logs:/app/logs
+    restart: unless-stopped
+    networks:
+      - {project_name_snake}_network
+
+  # ---------------------------------------------------------------------------
+  # API 服务
+  # ---------------------------------------------------------------------------
+  api:
+    <<: *base
+    container_name: {project_name_snake}_api
+    environment:
+      - SERVICE_NAME=api
+      - SERVICE_TYPE=api
+      - SCHEDULER_ENABLED=false  # API 服务不启动内嵌调度器
+    ports:
+      - "${{API_PORT:-8000}}:8000"
+    command: ["aury", "server", "prod"]
+    depends_on:
+      - redis
+      - postgres
+
+  # ---------------------------------------------------------------------------
+  # Scheduler 服务（定时任务）
+  # ---------------------------------------------------------------------------
+  scheduler:
+    <<: *base
+    container_name: {project_name_snake}_scheduler
+    environment:
+      - SERVICE_NAME=scheduler
+    command: ["aury", "scheduler"]
+    depends_on:
+      - redis
+      - postgres
+
+  # ---------------------------------------------------------------------------
+  # Worker 服务（异步任务）
+  # ---------------------------------------------------------------------------
+  worker:
+    <<: *base
+    container_name: {project_name_snake}_worker
+    environment:
+      - SERVICE_NAME=worker
+    command: ["aury", "worker", "-c", "8"]
+    depends_on:
+      - redis
+      - postgres
+
+  # ---------------------------------------------------------------------------
+  # 基础设施服务
+  # ---------------------------------------------------------------------------
+  postgres:
+    image: postgres:16-alpine
+    container_name: {project_name_snake}_postgres
+    environment:
+      POSTGRES_USER: ${{POSTGRES_USER:-postgres}}
+      POSTGRES_PASSWORD: ${{POSTGRES_PASSWORD:-postgres}}
+      POSTGRES_DB: ${{POSTGRES_DB:-{project_name_snake}}}
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+    ports:
+      - "${{POSTGRES_PORT:-5432}}:5432"
+    networks:
+      - {project_name_snake}_network
+    restart: unless-stopped
+
+  redis:
+    image: redis:7-alpine
+    container_name: {project_name_snake}_redis
+    command: redis-server --appendonly yes
+    volumes:
+      - redis_data:/data
+    ports:
+      - "${{REDIS_PORT:-6379}}:6379"
+    networks:
+      - {project_name_snake}_network
+    restart: unless-stopped
+
+# -----------------------------------------------------------------------------
+# 网络和卷
+# -----------------------------------------------------------------------------
+networks:
+  {project_name_snake}_network:
+    driver: bridge
+
+volumes:
+  postgres_data:
+  redis_data:
+'''
+
+
+DOCKERIGNORE_TEMPLATE = '''# =============================================================================
+# Docker 忽略文件
+# =============================================================================
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+.venv/
+venv/
+ENV/
+env/
+.eggs/
+*.egg-info/
+*.egg
+
+# 开发工具
+.git/
+.gitignore
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# 测试
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.nox/
+
+# 构建
+dist/
+build/
+*.egg-info/
+
+# 文档
+docs/
+*.md
+!README.md
+
+# 本地配置
+.env.local
+.env.*.local
+*.local.yml
+
+# 日志
+logs/
+*.log
+
+# 缓存
+.cache/
+.mypy_cache/
+.ruff_cache/
+
+# IDE
+.idea/
+.vscode/
+*.sublime-*
+
+# macOS
+.DS_Store
+
+# 其他
+Makefile
+docker-compose.override.yml
+'''
+
+
+# ============================================================
+# 命令
+# ============================================================
+
+
+def _to_snake_case(name: str) -> str:
+    """转换为 snake_case。"""
+    import re
+    s1 = re.sub(r"(.)([A-Z][a-z]+)", r"\1_\2", name)
+    return re.sub(r"([a-z0-9])([A-Z])", r"\1_\2", s1).lower().replace("-", "_")
+
+
+@app.command(name="init")
+def docker_init(
+    force: bool = typer.Option(
+        False,
+        "--force",
+        "-f",
+        help="强制覆盖已存在的文件",
+    ),
+) -> None:
+    """生成 Docker 配置文件。
+
+    生成：
+    - Dockerfile
+    - docker-compose.yml
+    - .dockerignore
+
+    示例：
+        aury docker init
+        aury docker init --force
+    """
+    base_path = Path.cwd()
+
+    # 获取项目名称
+    project_name = base_path.name
+    project_name_snake = _to_snake_case(project_name)
+
+    # 读取项目配置，获取包名
+    config = get_project_config(base_path)
+    package_or_dot = f"{config.package}." if config.has_package else ""
+
+    console.print(Panel.fit(
+        f"[bold cyan]🐳 生成 Docker 配置: {project_name}[/bold cyan]",
+        border_style="cyan",
+    ))
+
+    created_files = []
+
+    # 模板变量
+    template_vars = {
+        "project_name": project_name,
+        "project_name_snake": project_name_snake,
+        "package_or_dot": package_or_dot,
+    }
+
+    # 生成文件
+    files_to_create = [
+        ("Dockerfile", DOCKERFILE_TEMPLATE),
+        ("docker-compose.yml", DOCKER_COMPOSE_TEMPLATE),
+        (".dockerignore", DOCKERIGNORE_TEMPLATE),
+    ]
+
+    for file_name, template in files_to_create:
+        file_path = base_path / file_name
+
+        if file_path.exists() and not force:
+            console.print(f"  [dim]⏭️  {file_name} 已存在，跳过[/dim]")
+            continue
+
+        content = template.format(**template_vars)
+        file_path.write_text(content, encoding="utf-8")
+        created_files.append(file_name)
+        console.print(f"  [green]✅ {file_name}[/green]")
+
+    if created_files:
+        console.print("\n[bold green]✨ Docker 配置生成完成！[/bold green]\n")
+        console.print("[bold]使用方法：[/bold]")
+        console.print("  1. 启动所有服务：")
+        console.print("     [cyan]docker-compose up -d[/cyan]")
+        console.print("  2. 只启动 API：")
+        console.print("     [cyan]docker-compose up -d api[/cyan]")
+        console.print("  3. 查看日志：")
+        console.print("     [cyan]docker-compose logs -f api[/cyan]")
+        console.print("  4. 停止服务：")
+        console.print("     [cyan]docker-compose down[/cyan]")
+    else:
+        console.print("\n[dim]所有文件已存在，使用 --force 覆盖[/dim]")
+
+
+__all__ = ["app"]

aury/boot/commands/docs.py

@@ -0,0 +1,284 @@
+"""文档生成命令。
+
+提供命令行工具用于在现有项目中生成/更新文档：
+- aury docs dev         生成/更新 DEVELOPMENT.md
+- aury docs cli         生成/更新 CLI.md
+- aury docs env         生成/更新 .env.example
+- aury docs all         生成/更新所有文档
+
+使用示例：
+    aury docs dev                    # 生成开发文档
+    aury docs cli                    # 生成 CLI 文档
+    aury docs env                    # 生成环境变量示例
+    aury docs all                    # 生成所有文档
+    aury docs all --force            # 强制覆盖已存在的文件
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from rich.console import Console
+import typer
+
+app = typer.Typer(
+    name="docs",
+    help="📚 生成/更新项目文档",
+    no_args_is_help=True,
+)
+
+console = Console()
+
+# 模板目录
+TEMPLATES_DIR = Path(__file__).parent / "templates" / "project"
+
+
+def _detect_project_info(project_dir: Path) -> dict[str, str]:
+    """检测项目信息。
+    
+    从 pyproject.toml 或目录结构中推断项目名称和包名。
+    """
+    # 尝试从 pyproject.toml 读取
+    pyproject_path = project_dir / "pyproject.toml"
+    if pyproject_path.exists():
+        try:
+            import tomllib
+            with open(pyproject_path, "rb") as f:
+                data = tomllib.load(f)
+                project_name = data.get("project", {}).get("name", "")
+                if project_name:
+                    # 转换为 snake_case
+                    project_name_snake = project_name.replace("-", "_").lower()
+                    return {
+                        "project_name": project_name,
+                        "project_name_snake": project_name_snake,
+                        "package_name": project_name_snake,
+                        "import_prefix": project_name_snake,
+                    }
+        except Exception:
+            pass
+    
+    # 尝试从目录名推断
+    dir_name = project_dir.name
+    project_name_snake = dir_name.replace("-", "_").lower()
+    
+    # 检查是否有匹配的 Python 包目录
+    package_name = project_name_snake
+    for candidate in [project_name_snake, "app", "src"]:
+        candidate_path = project_dir / candidate
+        if candidate_path.is_dir() and (candidate_path / "__init__.py").exists():
+            package_name = candidate
+            break
+    
+    return {
+        "project_name": dir_name,
+        "project_name_snake": project_name_snake,
+        "package_name": package_name,
+        "import_prefix": package_name,
+    }
+
+
+def _render_template(template_name: str, context: dict[str, str]) -> str:
+    """渲染模板。"""
+    template_path = TEMPLATES_DIR / template_name
+    if not template_path.exists():
+        raise FileNotFoundError(f"模板文件不存在: {template_path}")
+    
+    content = template_path.read_text(encoding="utf-8")
+    return content.format(**context)
+
+
+def _write_file(
+    output_path: Path,
+    content: str,
+    force: bool = False,
+    dry_run: bool = False,
+) -> bool:
+    """写入文件。
+    
+    Returns:
+        bool: 是否成功写入
+    """
+    if output_path.exists() and not force:
+        console.print(f"[yellow]⚠️  文件已存在，跳过: {output_path}[/yellow]")
+        console.print("   使用 --force 覆盖已存在的文件")
+        return False
+    
+    if dry_run:
+        console.print(f"[dim]🔍 预览模式，将生成: {output_path}[/dim]")
+        return True
+    
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    output_path.write_text(content, encoding="utf-8")
+    
+    action = "覆盖" if output_path.exists() else "创建"
+    console.print(f"[green]✅ {action}: {output_path}[/green]")
+    return True
+
+
+@app.command(name="dev")
+def generate_dev_doc(
+    project_dir: Path = typer.Argument(
+        Path("."),
+        help="项目目录路径",
+        exists=True,
+        file_okay=False,
+        dir_okay=True,
+        resolve_path=True,
+    ),
+    force: bool = typer.Option(
+        False,
+        "--force",
+        "-f",
+        help="强制覆盖已存在的文件",
+    ),
+    dry_run: bool = typer.Option(
+        False,
+        "--dry-run",
+        "-n",
+        help="预览模式，不实际写入文件",
+    ),
+) -> None:
+    """生成/更新 DEVELOPMENT.md 开发文档。"""
+    context = _detect_project_info(project_dir)
+    
+    console.print(f"[cyan]📚 检测到项目: {context['project_name']}[/cyan]")
+    
+    try:
+        content = _render_template("DEVELOPMENT.md.tpl", context)
+        output_path = project_dir / "DEVELOPMENT.md"
+        _write_file(output_path, content, force=force, dry_run=dry_run)
+    except Exception as e:
+        console.print(f"[red]❌ 生成失败: {e}[/red]")
+        raise typer.Exit(1)
+
+
+@app.command(name="cli")
+def generate_cli_doc(
+    project_dir: Path = typer.Argument(
+        Path("."),
+        help="项目目录路径",
+        exists=True,
+        file_okay=False,
+        dir_okay=True,
+        resolve_path=True,
+    ),
+    force: bool = typer.Option(
+        False,
+        "--force",
+        "-f",
+        help="强制覆盖已存在的文件",
+    ),
+    dry_run: bool = typer.Option(
+        False,
+        "--dry-run",
+        "-n",
+        help="预览模式，不实际写入文件",
+    ),
+) -> None:
+    """生成/更新 CLI.md 命令行文档。"""
+    context = _detect_project_info(project_dir)
+    
+    console.print(f"[cyan]📚 检测到项目: {context['project_name']}[/cyan]")
+    
+    try:
+        content = _render_template("CLI.md.tpl", context)
+        output_path = project_dir / "CLI.md"
+        _write_file(output_path, content, force=force, dry_run=dry_run)
+    except Exception as e:
+        console.print(f"[red]❌ 生成失败: {e}[/red]")
+        raise typer.Exit(1)
+
+
+@app.command(name="env")
+def generate_env_example(
+    project_dir: Path = typer.Argument(
+        Path("."),
+        help="项目目录路径",
+        exists=True,
+        file_okay=False,
+        dir_okay=True,
+        resolve_path=True,
+    ),
+    force: bool = typer.Option(
+        False,
+        "--force",
+        "-f",
+        help="强制覆盖已存在的文件",
+    ),
+    dry_run: bool = typer.Option(
+        False,
+        "--dry-run",
+        "-n",
+        help="预览模式，不实际写入文件",
+    ),
+) -> None:
+    """生成/更新 .env.example 环境变量示例。"""
+    context = _detect_project_info(project_dir)
+    
+    console.print(f"[cyan]📚 检测到项目: {context['project_name']}[/cyan]")
+    
+    try:
+        content = _render_template("env.example.tpl", context)
+        output_path = project_dir / ".env.example"
+        _write_file(output_path, content, force=force, dry_run=dry_run)
+    except Exception as e:
+        console.print(f"[red]❌ 生成失败: {e}[/red]")
+        raise typer.Exit(1)
+
+
+@app.command(name="all")
+def generate_all_docs(
+    project_dir: Path = typer.Argument(
+        Path("."),
+        help="项目目录路径",
+        exists=True,
+        file_okay=False,
+        dir_okay=True,
+        resolve_path=True,
+    ),
+    force: bool = typer.Option(
+        False,
+        "--force",
+        "-f",
+        help="强制覆盖已存在的文件",
+    ),
+    dry_run: bool = typer.Option(
+        False,
+        "--dry-run",
+        "-n",
+        help="预览模式，不实际写入文件",
+    ),
+) -> None:
+    """生成/更新所有文档（DEVELOPMENT.md, CLI.md, .env.example）。"""
+    context = _detect_project_info(project_dir)
+    
+    console.print(f"[cyan]📚 检测到项目: {context['project_name']}[/cyan]")
+    console.print()
+    
+    docs_to_generate = [
+        ("DEVELOPMENT.md.tpl", "DEVELOPMENT.md", "开发文档"),
+        ("CLI.md.tpl", "CLI.md", "CLI 文档"),
+        ("env.example.tpl", ".env.example", "环境变量示例"),
+    ]
+    
+    success_count = 0
+    for template_name, output_name, description in docs_to_generate:
+        try:
+            content = _render_template(template_name, context)
+            output_path = project_dir / output_name
+            if _write_file(output_path, content, force=force, dry_run=dry_run):
+                success_count += 1
+        except FileNotFoundError:
+            console.print(f"[yellow]⚠️  模板不存在，跳过: {template_name}[/yellow]")
+        except Exception as e:
+            console.print(f"[red]❌ 生成 {description} 失败: {e}[/red]")
+    
+    console.print()
+    if dry_run:
+        console.print(f"[dim]🔍 预览模式完成，将生成 {success_count} 个文件[/dim]")
+    else:
+        console.print(f"[green]✨ 完成！成功生成 {success_count} 个文档[/green]")
+
+
+__all__ = ["app"]