pz-cli 5.0.0__py3-none-any.whl

pz_core/authoring/repo_keys.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+
+def _identity_basename(identity: str) -> str:
+    candidate = str(identity or "").strip().rstrip("/\\")
+    if not candidate:
+        return "repo"
+    normalized = candidate.replace("\\", "/").replace(":", "/")
+    parts = [part for part in normalized.split("/") if part]
+    name = parts[-1] if parts else "repo"
+    if name.lower().endswith(".git"):
+        name = name[:-4]
+    return name or "repo"
+
+
+def build_repo_key(identity: str) -> str:
+    name = _identity_basename(identity)
+    safe_name = "".join(ch if ch.isalnum() or ch in {"_", "-"} else "_" for ch in name)
+    return safe_name or "repo"
+
+
+def normalize_repo_key_candidate(value: object) -> str | None:
+    if not isinstance(value, str):
+        return None
+    candidate = value.strip()
+    if not candidate:
+        return None
+    candidate = "".join(ch if ch.isalnum() or ch in {"_", "-"} else "_" for ch in candidate)
+    return candidate or None

pz_core/authoring/root_cli.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from pz_core.root_cli import RootCommandHandler
+from pz_core.runtime.run_cli import main as run_main
+
+from .cli import main
+from .project_settings_cli import main as settings_main
+
+
+def _delegate_with_prefix(prefix: str, argv: Sequence[str]) -> int:
+    return main([prefix, *argv])
+
+
+def get_root_command_handlers() -> tuple[RootCommandHandler, ...]:
+    return (
+        RootCommandHandler(command_path=("settings",), handler=settings_main),
+        RootCommandHandler(command_path=("env",), handler=lambda argv: _delegate_with_prefix("env", argv)),
+        RootCommandHandler(command_path=("startapp",), handler=lambda argv: _delegate_with_prefix("startapp", argv)),
+        RootCommandHandler(command_path=("app",), handler=lambda argv: _delegate_with_prefix("app", argv)),
+        RootCommandHandler(command_path=("dev",), handler=lambda argv: _delegate_with_prefix("dev", argv)),
+        RootCommandHandler(command_path=("pub",), handler=lambda argv: _delegate_with_prefix("pub", argv)),
+        RootCommandHandler(command_path=("run",), handler=run_main),
+    )
+
+
+__all__ = ["get_root_command_handlers"]

pz_core/authoring/scaffold_service.py

@@ -0,0 +1,325 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+from pz_core.project_runtime_cli import resolve_project_runtime_package_root
+from pz_core.runtime.errors import PzError
+from pz_core.project_sources import resolve_sources_root
+
+from .files import (
+    ScaffoldFile,
+    append_or_create_file,
+    render_upserted_managed_block,
+    write_files,
+)
+from .naming import build_app_id, derive_default_local_app_slug, normalize_app_slug
+from .project_state import resolve_runtime_source_path
+from .repo_keys import build_repo_key
+from .workspace import resolve_workspace_package
+from .templates.app.apps import app_apps_template
+from .templates.app.auth_package_init import app_auth_package_init_template
+from .templates.app.auth_readme import app_auth_readme_template
+from .templates.app.configs_package_init import app_configs_package_init_template
+from .templates.app.default_env import app_default_env_template
+from .templates.app.default_jsonc import app_default_jsonc_template
+from .templates.app.locales_readme import app_locales_readme_template
+from .templates.app.migrations_readme import app_migrations_readme_template
+from .templates.app.models import app_models_template
+from .templates.app.package_init import app_package_init_template
+from .templates.app.api import app_api_template
+from .templates.app.pages_base import (
+    app_pages_base_template,
+    app_pages_key_template,
+    app_pages_namespace_base_template,
+)
+from .templates.app.pages_readme import app_pages_readme_template
+from .templates.app.public import app_public_template
+from .templates.app.pyproject import app_pyproject_template
+from .templates.app.readme import app_readme_template
+from .templates.app.urls import app_urls_template
+from .templates.app.settings import app_settings_template
+from .templates.app.static_app_js import app_static_app_js_template
+from .templates.app.static_readme import app_static_readme_template
+from .templates.app.template_config_page import app_template_config_page_template
+from .templates.app.template_index_html import app_template_index_html_template
+from .templates.app.templates_readme import app_templates_readme_template
+from .templates.app.views import app_views_template
+from .templates.project.agents import project_agents_template
+from .templates.project.apps_container_readme import apps_container_readme_template
+from .templates.project.main_py import main_py_template
+from .templates.project.project_env import project_env_template
+from .templates.project.pyproject import project_pyproject_template
+from .templates.project.pz_env_env import pz_env_env_template
+from .templates.project.pz_env_jsonc import pz_env_jsonc_template
+from .templates.project.pz_jsonc import pz_jsonc_template
+from .templates.project.readme import project_readme_template
+from .templates.project.root_gitkeep import root_gitkeep_template
+
+_AGENTS_START_MARKER = "<!-- pz:managed:start -->"
+_AGENTS_END_MARKER = "<!-- pz:managed:end -->"
+_PZ_RUNTIME_REPO = "git@github.com:JiXiangTools/pyzza.git"
+
+
+@dataclass(frozen=True, slots=True)
+class ProjectScaffoldResult:
+    created: bool
+
+
+@dataclass(frozen=True, slots=True)
+class LocalAppScaffoldResult:
+    app_id: str | None
+    created: bool
+
+
+@dataclass(frozen=True, slots=True)
+class ProjectAgentsRefreshResult:
+    path: Path
+    created: bool
+
+
+def _repo_key(identity: str) -> str:
+    return build_repo_key(identity)
+
+
+def _default_project_local_pz_docs_root(project_dir: Path) -> Path:
+    return (
+        resolve_sources_root(project_dir)
+        / _repo_key(_PZ_RUNTIME_REPO)
+        / "pz_core"
+        / "pz_core"
+        / "docs"
+        / "pz规范与使用"
+    )
+
+
+def resolve_project_local_pz_docs_root(project_dir: Path) -> Path:
+    workspace_package = resolve_workspace_package("pz", anchors=(project_dir,))
+    if workspace_package is not None:
+        workspace_root = workspace_package.repo
+        for docs_candidate in (
+            workspace_root / "docs" / "pz规范与使用",
+            workspace_root / "pz_core" / "docs" / "pz规范与使用",
+            workspace_root / "pz_core" / "pz_core" / "docs" / "pz规范与使用",
+            workspace_root.parent / "docs" / "pz规范与使用",
+        ):
+            if docs_candidate.is_dir():
+                return docs_candidate.resolve()
+    runtime_root = resolve_runtime_source_path(project_dir, "pz")
+    if runtime_root is not None:
+        docs_candidate = runtime_root / "docs" / "pz规范与使用"
+        if not docs_candidate.is_dir():
+            parent_candidate = runtime_root.parent / "docs" / "pz规范与使用"
+            if parent_candidate.is_dir():
+                docs_candidate = parent_candidate
+        if docs_candidate.is_dir():
+            return docs_candidate.resolve()
+    for candidate in sorted(resolve_sources_root(project_dir).glob("*/pz_core/pz_core/docs/pz规范与使用")):
+        if candidate.is_dir():
+            return candidate.resolve()
+    return _default_project_local_pz_docs_root(project_dir)
+
+
+def _relative_doc_path(project_dir: Path, target: Path) -> str:
+    return Path(os.path.relpath(target, start=project_dir.resolve())).as_posix()
+
+
+def _resolve_project_local_pz_docs_display_root(project_dir: Path) -> Path:
+    for candidate in sorted(resolve_sources_root(project_dir).glob("*/pz_core/pz_core/docs/pz规范与使用")):
+        if candidate.is_dir():
+            return candidate
+    runtime_package_root = resolve_project_runtime_package_root(project_dir)
+    if runtime_package_root is not None:
+        docs_candidate = runtime_package_root / "docs" / "pz规范与使用"
+        if docs_candidate.is_dir():
+            return docs_candidate
+        parent_candidate = runtime_package_root.parent / "docs" / "pz规范与使用"
+        if parent_candidate.is_dir():
+            return parent_candidate
+    return resolve_project_local_pz_docs_root(project_dir)
+
+
+def render_project_agents_content(project_dir: Path) -> str:
+    docs_guides_dir = _resolve_project_local_pz_docs_display_root(project_dir)
+    docs_dir = docs_guides_dir.parent
+    return project_agents_template(
+        pz_docs_readme=_relative_doc_path(project_dir, docs_dir / "README.md"),
+        pz_design_docs_dir=_relative_doc_path(project_dir, docs_guides_dir),
+        pz_pz_commands_doc=_relative_doc_path(project_dir, docs_dir / "pz命令总览.md"),
+    )
+
+
+def render_project_agents_block(project_dir: Path) -> str:
+    return f"{_AGENTS_START_MARKER}\n{render_project_agents_content(project_dir).strip()}\n{_AGENTS_END_MARKER}\n"
+
+
+def render_project_agents_file_text(project_dir: Path) -> str:
+    path = project_dir / "AGENTS.md"
+    existing = path.read_text(encoding="utf-8") if path.exists() else None
+    return render_upserted_managed_block(
+        existing,
+        start_marker=_AGENTS_START_MARKER,
+        end_marker=_AGENTS_END_MARKER,
+        content=render_project_agents_content(project_dir),
+    )
+
+
+def write_project_agents_file(project_dir: Path) -> None:
+    path = project_dir / "AGENTS.md"
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(render_project_agents_file_text(project_dir), encoding="utf-8")
+
+
+def refresh_project_agents_file(project_dir: Path) -> ProjectAgentsRefreshResult:
+    path = project_dir / "AGENTS.md"
+    existed_before = path.exists()
+    write_project_agents_file(project_dir)
+    return ProjectAgentsRefreshResult(path=path, created=not existed_before)
+
+
+def reset_project_agents_file(project_dir: Path) -> ProjectAgentsRefreshResult:
+    path = project_dir / "AGENTS.md"
+    existed_before = path.exists()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(render_project_agents_block(project_dir), encoding="utf-8")
+    return ProjectAgentsRefreshResult(path=path, created=not existed_before)
+
+
+def project_init_files(project_dir: Path) -> list[ScaffoldFile]:
+    project_name = derive_default_local_app_slug(project_dir)
+    return [
+        ScaffoldFile(
+            project_dir / "pyproject.toml",
+            project_pyproject_template(project_name),
+        ),
+        ScaffoldFile(project_dir / "main.py", main_py_template()),
+        ScaffoldFile(project_dir / "README.md", project_readme_template()),
+        ScaffoldFile(project_dir / "pz.jsonc", pz_jsonc_template()),
+        ScaffoldFile(project_dir / "pz.develop.jsonc", pz_env_jsonc_template("develop")),
+        ScaffoldFile(project_dir / "pz.test.jsonc", pz_env_jsonc_template("test")),
+        ScaffoldFile(project_dir / "pz.product.jsonc", pz_env_jsonc_template("product")),
+        ScaffoldFile(project_dir / ".env", project_env_template()),
+        ScaffoldFile(project_dir / ".env.develop", pz_env_env_template("develop")),
+        ScaffoldFile(project_dir / ".env.test", pz_env_env_template("test")),
+        ScaffoldFile(project_dir / ".env.product", pz_env_env_template("product")),
+        ScaffoldFile(project_dir / "apps" / "__init__.py", app_package_init_template()),
+        ScaffoldFile(project_dir / "apps" / ".gitkeep", root_gitkeep_template()),
+    ]
+
+
+def app_files(project_dir: Path, app_id: str, *, target_dir: Path | None = None) -> list[ScaffoldFile]:
+    package_root = (target_dir or (project_dir / "apps")) / app_id
+    module_root = package_root / app_id
+    return [
+        ScaffoldFile(package_root / "pyproject.toml", app_pyproject_template(app_id)),
+        ScaffoldFile(package_root / "README.md", app_readme_template(app_id)),
+        ScaffoldFile(module_root / "__init__.py", app_package_init_template()),
+        ScaffoldFile(module_root / "apps.py", app_apps_template(app_id)),
+        ScaffoldFile(module_root / "public.py", app_public_template()),
+        ScaffoldFile(module_root / "auth" / "__init__.py", app_auth_package_init_template()),
+        ScaffoldFile(module_root / "auth" / "README.md", app_auth_readme_template(app_id)),
+        ScaffoldFile(module_root / "configs" / "__init__.py", app_configs_package_init_template()),
+        ScaffoldFile(module_root / "configs" / "default.jsonc", app_default_jsonc_template()),
+        ScaffoldFile(module_root / "configs" / "default.env", app_default_env_template(app_id)),
+        ScaffoldFile(module_root / "settings.py", app_settings_template()),
+        ScaffoldFile(module_root / "models.py", app_models_template()),
+        ScaffoldFile(module_root / "views.py", app_views_template(app_id)),
+        ScaffoldFile(module_root / "api.py", app_api_template(app_id)),
+        ScaffoldFile(module_root / "urls.py", app_urls_template(app_id)),
+        ScaffoldFile(module_root / "pages" / "__init__.py", app_package_init_template()),
+        ScaffoldFile(module_root / "pages" / "README.md", app_pages_readme_template(app_id)),
+        ScaffoldFile(module_root / "pages" / "base.jsonc", app_pages_base_template(app_id)),
+        ScaffoldFile(module_root / "pages" / app_id / "base.jsonc", app_pages_namespace_base_template(app_id)),
+        ScaffoldFile(module_root / "pages" / app_id / "key.jsonc", app_pages_key_template(app_id)),
+        ScaffoldFile(module_root / "template_config" / "__init__.py", app_package_init_template()),
+        ScaffoldFile(module_root / "template_config" / app_id / "__init__.py", app_package_init_template()),
+        ScaffoldFile(module_root / "template_config" / app_id / f"{app_id}_index.json", app_template_config_page_template(app_id)),
+        ScaffoldFile(module_root / "templates" / "__init__.py", app_package_init_template()),
+        ScaffoldFile(module_root / "templates" / app_id / "__init__.py", app_package_init_template()),
+        ScaffoldFile(module_root / "templates" / app_id / "index.html", app_template_index_html_template(app_id)),
+        ScaffoldFile(module_root / "templates" / "README.md", app_templates_readme_template(app_id)),
+        ScaffoldFile(module_root / "static" / "__init__.py", app_package_init_template()),
+        ScaffoldFile(module_root / "static" / app_id / "__init__.py", app_package_init_template()),
+        ScaffoldFile(module_root / "static" / app_id / "app.js", app_static_app_js_template(app_id)),
+        ScaffoldFile(module_root / "static" / "README.md", app_static_readme_template(app_id)),
+        ScaffoldFile(module_root / "locales" / "__init__.py", app_package_init_template()),
+        ScaffoldFile(module_root / "locales" / "README.md", app_locales_readme_template(app_id)),
+        ScaffoldFile(module_root / "migrations" / "__init__.py", app_package_init_template()),
+        ScaffoldFile(module_root / "migrations" / "README.md", app_migrations_readme_template(app_id)),
+        ScaffoldFile(module_root / "migrations" / app_id / "__init__.py", app_package_init_template()),
+    ]
+
+
+def write_missing_files(entries: list[ScaffoldFile]) -> list[Path]:
+    created: list[Path] = []
+    seen: set[Path] = set()
+    for entry in entries:
+        if entry.path in seen:
+            raise PzError(
+                code="PZ_SCAFFOLD_TARGET_DUPLICATE",
+                message=f"duplicate scaffold target declared: {entry.path}",
+                stage="cli",
+                owner="pz_core.authoring",
+                action="write_missing_files",
+            )
+        seen.add(entry.path)
+        if entry.path.exists():
+            continue
+        entry.path.parent.mkdir(parents=True, exist_ok=True)
+        entry.path.write_text(entry.content, encoding="utf-8")
+        created.append(entry.path)
+    return created
+
+
+def ensure_apps_container_readme(project_dir: Path) -> None:
+    append_or_create_file(project_dir / "apps" / "README.md", apps_container_readme_template())
+
+
+def write_project_scaffold(project_dir: Path, *, action: str) -> None:
+    write_files(project_init_files(project_dir), action=action)
+    write_project_agents_file(project_dir)
+    ensure_apps_container_readme(project_dir)
+
+
+def ensure_project_scaffold(project_dir: Path) -> ProjectScaffoldResult:
+    created = bool(write_missing_files(project_init_files(project_dir)))
+    write_project_agents_file(project_dir)
+    ensure_apps_container_readme(project_dir)
+    return ProjectScaffoldResult(created=created)
+
+
+def discover_local_app_ids(project_dir: Path) -> set[str]:
+    apps_root = project_dir / "apps"
+    if not apps_root.is_dir():
+        return set()
+    app_ids: set[str] = set()
+    for child in apps_root.iterdir():
+        if not child.is_dir() or child.name.startswith("."):
+            continue
+        if (child / "pyproject.toml").is_file():
+            app_ids.add(child.name)
+    return app_ids
+
+
+def ensure_default_local_app(
+    project_dir: Path,
+    *,
+    app_name: str | None,
+    scaffold_created: bool,
+    action: str,
+) -> LocalAppScaffoldResult:
+    slug = normalize_app_slug(app_name or derive_default_local_app_slug(project_dir), action=action)
+    default_app_id = build_app_id(slug)
+    existing_local_apps = discover_local_app_ids(project_dir)
+    should_ensure_default_app = (
+        scaffold_created
+        or default_app_id in existing_local_apps
+        or not existing_local_apps
+        or isinstance(app_name, str)
+    )
+    if not should_ensure_default_app:
+        return LocalAppScaffoldResult(app_id=None, created=False)
+    created = bool(write_missing_files(app_files(project_dir, default_app_id)))
+    ensure_apps_container_readme(project_dir)
+    return LocalAppScaffoldResult(app_id=default_app_id, created=created)