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

aury/boot/commands/__init__.py

@@ -1,6 +1,21 @@
 """命令行工具模块。
 
-统一入口: aum
+统一入口: aury
+
+CLI 继承接口：
+    子框架（如 aury-django、aury-cloud）可以通过以下接口继承基础命令：
+    
+    - register_commands(app): 将所有命令注册到目标 app
+    - get_command_modules(): 获取所有命令模块，供进一步定制
+    
+    示例:
+        ```python
+        from typer import Typer
+        from aury.boot.commands import register_commands
+        
+        app = Typer(name="aury-django")
+        register_commands(app)  # 继承所有命令
+        ```
 """
 
 from __future__ import annotations
@@ -9,22 +24,27 @@ from __future__ import annotations
 from .config import ProjectConfig, get_project_config, save_project_config
 
 
-# 延迟导入 app 和 main，避免加载重型依赖
+# 延迟导入 app、main、register_commands、get_command_modules，避免加载重型依赖
 def __getattr__(name: str):
-    if name in ("app", "main"):
-        from .app import main as _main
+    if name in ("app", "main", "register_commands", "get_command_modules"):
+        from .app import _get_app, get_command_modules, main, register_commands
         if name == "main":
-            return _main
-        # app 通过 app 模块的 __getattr__ 获取
-        from . import app as app_module
-        return app_module.app
+            return main
+        if name == "app":
+            return _get_app()
+        if name == "register_commands":
+            return register_commands
+        if name == "get_command_modules":
+            return get_command_modules
     raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
 
 
 __all__ = [
-    "app",
-    "main",
     "ProjectConfig",
+    "app",
+    "get_command_modules",
     "get_project_config",
+    "main",
+    "register_commands",
     "save_project_config",
 ]

aury/boot/commands/app.py

@@ -18,6 +18,22 @@
     aury worker                    # 运行 Worker
     aury migrate up                # 执行数据库迁移
     aury docs all --force          # 更新所有文档
+
+CLI 继承：
+    子框架（如 aury-django、aury-cloud）可以通过 `register_commands` 继承所有基础命令：
+    
+    ```python
+    from typer import Typer
+    from aury.boot.commands import register_commands
+    
+    app = Typer(name="aury-django")
+    register_commands(app)  # 继承所有 aury-boot 命令
+    
+    # 添加 django 特有命令
+    @app.command()
+    def startapp(name: str):
+        ...
+    ```
 """
 
 from __future__ import annotations
@@ -92,7 +108,119 @@ def main() -> None:
     _get_app()()
 
 
-# 为了向后兼容，允许 `from .app import app`
+def register_commands(
+    target_app: typer.Typer,
+    *,
+    include_init: bool = True,
+    include_add: bool = True,
+    include_generate: bool = True,
+    include_server: bool = True,
+    include_scheduler: bool = True,
+    include_worker: bool = True,
+    include_migrate: bool = True,
+    include_docker: bool = True,
+    include_docs: bool = True,
+) -> None:
+    """将 aury-boot 的所有命令注册到目标 Typer app。
+    
+    用于子框架（如 aury-django、aury-cloud）继承基础命令。
+    
+    Args:
+        target_app: 目标 Typer 应用
+        include_*: 是否包含对应的命令组
+    
+    使用示例:
+        ```python
+        from typer import Typer
+        from aury.boot.commands import register_commands
+        
+        app = Typer(name="aury-django")
+        
+        # 继承所有 aury-boot 命令
+        register_commands(app)
+        
+        # 或选择性继承
+        register_commands(app, include_docker=False)
+        
+        # 添加 django 特有命令
+        django_app = Typer(name="django")
+        
+        @django_app.command()
+        def startapp(name: str):
+            '''Django startapp'''
+            ...
+        
+        app.add_typer(django_app, name="django")
+        ```
+    """
+    # 延迟导入子命令
+    if include_init:
+        from .init import init
+        target_app.command(name="init", help="🎯 初始化项目脚手架")(init)
+    
+    if include_add:
+        from .add import app as add_app
+        target_app.add_typer(add_app, name="add", help="➕ 添加可选模块")
+    
+    if include_generate:
+        from .generate import app as generate_app
+        target_app.add_typer(generate_app, name="generate", help="⚡ 代码生成器")
+    
+    if include_server:
+        from .server import app as server_app
+        target_app.add_typer(server_app, name="server", help="🖥️  服务器管理")
+    
+    if include_scheduler:
+        from .scheduler import app as scheduler_app
+        target_app.add_typer(scheduler_app, name="scheduler", help="🕐 独立运行调度器")
+    
+    if include_worker:
+        from .worker import app as worker_app
+        target_app.add_typer(worker_app, name="worker", help="⚙️  运行任务队列 Worker")
+    
+    if include_migrate:
+        from .migrate import app as migrate_app
+        target_app.add_typer(migrate_app, name="migrate", help="🗃️  数据库迁移")
+    
+    if include_docker:
+        from .docker import app as docker_app
+        target_app.add_typer(docker_app, name="docker", help="🐳 Docker 配置")
+    
+    if include_docs:
+        from .docs import app as docs_app
+        target_app.add_typer(docs_app, name="docs", help="📚 生成/更新项目文档")
+
+
+def get_command_modules() -> dict[str, type]:
+    """获取所有命令模块，供子框架进一步定制。
+    
+    Returns:
+        dict: 命令名 -> 模块对象
+    
+    使用示例:
+        ```python
+        from aury.boot.commands import get_command_modules
+        
+        modules = get_command_modules()
+        # {'init': <module>, 'add': <module>, 'server': <module>, ...}
+        ```
+    """
+    from . import add, docker, docs, generate, init, migrate, scheduler, server, worker
+    
+    return {
+        "init": init,
+        "add": add,
+        "generate": generate,
+        "server": server,
+        "scheduler": scheduler,
+        "worker": worker,
+        "migrate": migrate,
+        "docker": docker,
+        "docs": docs,
+    }
+
+
+# 允许 `from .app import app`
 def __getattr__(name: str):
     if name == "app":
         return _get_app()
@@ -101,5 +229,7 @@ def __getattr__(name: str):
 
 __all__ = [
     "app",
+    "get_command_modules",
     "main",
+    "register_commands",
 ]

aury/boot/commands/docs.py

@@ -1,13 +1,15 @@
 """文档生成命令。
 
 提供命令行工具用于在现有项目中生成/更新文档：
-- aury docs dev         生成/更新 DEVELOPMENT.md
+- aury docs agents      生成/更新 AGENTS.md（AI 编程助手上下文）
+- aury docs dev         生成/更新 docs/ 目录（开发文档包）
 - aury docs cli         生成/更新 CLI.md
 - aury docs env         生成/更新 .env.example
 - aury docs all         生成/更新所有文档
 
 使用示例：
-    aury docs dev                    # 生成开发文档
+    aury docs agents                 # 生成 AI 编程助手上下文文档
+    aury docs dev                    # 生成 docs/ 开发文档包
     aury docs cli                    # 生成 CLI 文档
     aury docs env                    # 生成环境变量示例
     aury docs all                    # 生成所有文档
@@ -79,10 +81,17 @@ def _detect_project_info(project_dir: Path) -> dict[str, str]:
 
 
 def _render_template(template_name: str, context: dict[str, str]) -> str:
-    """渲染模板。"""
+    """渲染模板。
+    
+    支持根目录模板和 aury_docs/ 子目录模板。
+    """
+    # 先在根目录找
     template_path = TEMPLATES_DIR / template_name
     if not template_path.exists():
-        raise FileNotFoundError(f"模板文件不存在: {template_path}")
+        # 再在 aury_docs/ 子目录找
+        template_path = AURY_DOCS_TPL_DIR / template_name
+    if not template_path.exists():
+        raise FileNotFoundError(f"模板文件不存在: {template_name}")
     
     content = template_path.read_text(encoding="utf-8")
     return content.format(**context)
@@ -116,8 +125,8 @@ def _write_file(
     return True
 
 
-@app.command(name="dev")
-def generate_dev_doc(
+@app.command(name="agents")
+def generate_agents_doc(
     project_dir: Path = typer.Argument(
         Path("."),
         help="项目目录路径",
@@ -139,20 +148,84 @@ def generate_dev_doc(
         help="预览模式，不实际写入文件",
     ),
 ) -> None:
-    """生成/更新 DEVELOPMENT.md 开发文档。"""
+    """生成/更新 AGENTS.md（AI 编程助手上下文文档）。"""
     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"
+        content = _render_template("AGENTS.md.tpl", context)
+        output_path = project_dir / "AGENTS.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)
 
 
+# aury_docs/ 模板目录
+AURY_DOCS_TPL_DIR = TEMPLATES_DIR / "aury_docs"
+
+
+def _get_aury_docs_templates() -> list[Path]:
+    """动态扫描 aury_docs/ 模板目录。"""
+    if not AURY_DOCS_TPL_DIR.exists():
+        return []
+    return sorted(AURY_DOCS_TPL_DIR.glob("*.md.tpl"))
+
+
+@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:
+    """生成/更新 aury_docs/ 开发文档包。"""
+    context = _detect_project_info(project_dir)
+    
+    console.print(f"[cyan]📚 检测到项目: {context['project_name']}[/cyan]")
+    console.print()
+    
+    # 确保输出目录存在
+    aury_docs_dir = project_dir / "aury_docs"
+    if not dry_run:
+        aury_docs_dir.mkdir(parents=True, exist_ok=True)
+    
+    success_count = 0
+    for tpl_path in _get_aury_docs_templates():
+        try:
+            output_name = tpl_path.stem  # 去掉 .tpl 后缀，保留 .md
+            output_path = aury_docs_dir / output_name
+            content = tpl_path.read_text(encoding="utf-8")
+            content = content.format(**context)
+            if _write_file(output_path, content, force=force, dry_run=dry_run):
+                success_count += 1
+        except Exception as e:
+            console.print(f"[red]❌ 生成 {tpl_path.name} 失败: {e}[/red]")
+    
+    console.print()
+    if dry_run:
+        console.print(f"[dim]🔍 预览模式完成，将生成 {success_count} 个文档到 aury_docs/ 目录[/dim]")
+    else:
+        console.print(f"[green]✨ 完成！成功生成 {success_count} 个文档到 aury_docs/ 目录[/green]")
+
+
 @app.command(name="cli")
 def generate_cli_doc(
     project_dir: Path = typer.Argument(
@@ -176,14 +249,18 @@ def generate_cli_doc(
         help="预览模式，不实际写入文件",
     ),
 ) -> None:
-    """生成/更新 CLI.md 命令行文档。"""
+    """生成/更新 aury_docs/99-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"
+        tpl_path = AURY_DOCS_TPL_DIR / "99-cli.md.tpl"
+        content = tpl_path.read_text(encoding="utf-8")
+        content = content.format(**context)
+        output_path = project_dir / "aury_docs" / "99-cli.md"
+        if not dry_run:
+            output_path.parent.mkdir(parents=True, exist_ok=True)
         _write_file(output_path, content, force=force, dry_run=dry_run)
     except Exception as e:
         console.print(f"[red]❌ 生成失败: {e}[/red]")
@@ -250,20 +327,30 @@ def generate_all_docs(
         help="预览模式，不实际写入文件",
     ),
 ) -> None:
-    """生成/更新所有文档（DEVELOPMENT.md, CLI.md, .env.example）。"""
+    """生成/更新所有文档（AGENTS.md, docs/, 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 文档"),
+    # 根目录文档
+    root_docs: list[tuple[str, str, str]] = [
+        ("AGENTS.md.tpl", "AGENTS.md", "AI 编程助手上下文"),
         ("env.example.tpl", ".env.example", "环境变量示例"),
     ]
     
+    # aury_docs/ 开发文档
+    aury_docs_templates = _get_aury_docs_templates()
+    dev_docs = [
+        (tpl.name, f"aury_docs/{tpl.stem}", f"开发文档: {tpl.stem}")
+        for tpl in aury_docs_templates
+    ]
+    
+    # 合并所有文档
+    all_docs = root_docs + dev_docs
+    
     success_count = 0
-    for template_name, output_name, description in docs_to_generate:
+    for template_name, output_name, description in all_docs:
         try:
             content = _render_template(template_name, context)
             output_path = project_dir / output_name

aury/boot/commands/init.py

@@ -156,8 +156,7 @@ TEMPLATE_FILE_MAP = {
     ".env.example": "env.example.tpl",
     ".gitignore": "gitignore.tpl",
     "README.md": "README.md.tpl",
-    "DEVELOPMENT.md": "DEVELOPMENT.md.tpl",
-    "CLI.md": "CLI.md.tpl",
+    "AGENTS.md": "AGENTS.md.tpl",
     "conftest.py": "conftest.py.tpl",
     "admin_console/__init__.py": "admin_console_init.py.tpl",
 }
@@ -712,8 +711,7 @@ def init(
         (code_root / "admin_console" / "__init__.py", "admin_console/__init__.py", False),
         (base_path / "tests" / "conftest.py", "conftest.py", False),  # tests 放在项目根目录
         (base_path / "README.md", "README.md", True),  # 覆盖 uv init 创建的默认 README
-        (base_path / "DEVELOPMENT.md", "DEVELOPMENT.md", False),  # 开发指南
-        (base_path / "CLI.md", "CLI.md", False),  # CLI 命令参考
+        (base_path / "AGENTS.md", "AGENTS.md", False),  # AI 编程助手上下文
         (base_path / ".gitignore", ".gitignore", False),  # Git 忽略文件
     ]
 
@@ -806,13 +804,34 @@ def init(
     else:
         console.print("  [dim]ℹ️  migrations/ 目录已存在，跳过[/dim]")
 
-    # 5. 生成 Docker 配置
+    # 5. 生成开发文档 (aury_docs/) - 动态扫描模板目录
+    console.print("\n[bold]📚 生成开发文档...[/bold]")
+    aury_docs_tpl_dir = TEMPLATES_DIR / "aury_docs"
+    aury_docs_dir = base_path / "aury_docs"
+    aury_docs_dir.mkdir(parents=True, exist_ok=True)
+    docs_count = 0
+    if aury_docs_tpl_dir.exists():
+        for tpl_path in sorted(aury_docs_tpl_dir.glob("*.md.tpl")):
+            output_name = tpl_path.stem  # 去掉 .tpl 后缀，保留 .md
+            output_path = aury_docs_dir / output_name
+            if output_path.exists() and not force:
+                continue
+            try:
+                content = tpl_path.read_text(encoding="utf-8")
+                content = content.format(**template_vars)
+                output_path.write_text(content, encoding="utf-8")
+                docs_count += 1
+            except Exception:
+                pass
+    console.print(f"  [green]✅ 已生成 {docs_count} 个文档到 aury_docs/[/green]")
+
+    # 6. 生成 Docker 配置
     if with_docker:
         console.print("\n[bold]🐳 生成 Docker 配置...[/bold]")
         from .docker import docker_init
         docker_init(force=force)
 
-    # 6. 显示结果
+    # 7. 显示结果
     console.print("\n")
 
     tree = Tree(f"[bold cyan]{project_name}/[/bold cyan]")
@@ -821,8 +840,8 @@ def init(
     tree.add("[dim]alembic.ini[/dim]")
     tree.add("[dim]pyproject.toml[/dim]")
     tree.add("[dim]README.md[/dim]")
-    tree.add("[dim]DEVELOPMENT.md[/dim]")
-    tree.add("[dim]CLI.md[/dim]")
+    tree.add("[dim]AGENTS.md[/dim]")
+    tree.add("[blue]aury_docs/[/blue]")
     if with_docker:
         tree.add("[dim]Dockerfile[/dim]")
         tree.add("[dim]docker-compose.yml[/dim]")

aury/boot/commands/server/app.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import contextlib
 import os
 from pathlib import Path
 import sys
@@ -339,13 +340,11 @@ def dev(
     typer.echo(f"   应用模块: {app_module_path}")
 
     # 在应用启动完成后打印一次服务地址
-    try:
+    with contextlib.suppress(Exception):
         app_instance.add_event_handler(
             "startup",
             lambda: typer.echo(f"✅ 服务已就绪: http://{server_host}:{server_port}"),
         )
-    except Exception:
-        pass
 
     # 默认包含/排除规则（watchfiles 支持）
     reload_includes = [