xgic-payload-cms-cli 0.2.0__py3-none-any.whl

xgic/cli/payload/__init__.py

@@ -0,0 +1,40 @@
+"""XGIC CLI Payload CMS module (``xgic.cli.payload``)."""
+
+from xgic.cli.payload.config import (
+    DEFAULT_COMPOSE_PROJECT,
+    DEFAULT_CONFIG_FILE,
+    DEFAULT_PRIMARY_SERVICE,
+    db_ready,
+    get_db_config,
+    get_db_profile,
+    get_payload_project_name,
+    make_payload_docker_controller,
+)
+from xgic.cli.payload.env_helpers import (
+    generate_fresh_env_content,
+    perform_env_regenerate,
+)
+from xgic.cli.payload.project import (
+    build_create_payload_command,
+    ensure_payload_project,
+    load_create_payload_config,
+)
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "DEFAULT_COMPOSE_PROJECT",
+    "DEFAULT_CONFIG_FILE",
+    "DEFAULT_PRIMARY_SERVICE",
+    "build_create_payload_command",
+    "db_ready",
+    "ensure_payload_project",
+    "generate_fresh_env_content",
+    "get_db_config",
+    "get_db_profile",
+    "get_payload_project_name",
+    "load_create_payload_config",
+    "make_payload_docker_controller",
+    "perform_env_regenerate",
+    "__version__",
+]

xgic/cli/payload/commands/__init__.py

@@ -0,0 +1 @@
+"""CLI command handlers for ``xgic.cli.payload``."""

xgic/cli/payload/commands/dev.py

@@ -0,0 +1,87 @@
+"""``xgic payload dev`` — smart Payload CMS development server start."""
+
+from __future__ import annotations
+
+import subprocess
+
+from xgic.cli.app import CommandContext
+from xgic.cli.core.environment import EnvironmentType
+from xgic.cli.payload.config import (
+    DEFAULT_PRIMARY_SERVICE,
+    db_ready,
+    get_db_profile,
+    get_payload_project_name,
+    make_payload_docker_controller,
+)
+from xgic.cli.utils.output import print_info, print_success, print_warning
+
+
+def run_dev(ctx: CommandContext) -> int:
+    """Start services if needed and launch the Payload CMS app dev server."""
+    env = ctx.env
+    docker = make_payload_docker_controller(env)
+    print_info("Starting Payload CMS development server...")
+
+    profile = get_db_profile()
+    if not docker.services_running():
+        print_warning("Services not running. Attempting to bring them up...")
+        docker.up(profile=profile)
+        print_success("Services started. Proceeding...")
+
+    payload_project = get_payload_project_name()
+
+    if db_ready(docker):
+        print_success("Database is ready")
+    else:
+        print_warning(
+            "Database not ready yet. You may need a reset / wait for DB startup."
+        )
+
+    print_info(f"Target Payload CMS project: {payload_project}")
+
+    if env.env_type == EnvironmentType.DEV_CONTAINER:
+        try:
+            print_info(f"Launching pnpm dev inside {payload_project}...")
+            project_dir = f"/workspace/{payload_project}"
+            result = subprocess.run(
+                ["sh", "-c", 'trap "exit 0" INT TERM; exec pnpm dev'],
+                cwd=project_dir,
+                check=False,
+            )
+            if result.returncode in (130, -2, 2):
+                print_info("Development server stopped by user (Ctrl+C).")
+                return 0
+            if result.returncode != 0:
+                print_warning(f"pnpm dev exited with code {result.returncode}.")
+                print_info(
+                    f"Fallback: cd {payload_project} && pnpm dev "
+                    "(or xgic shell --service …)."
+                )
+                return result.returncode or 1
+            print_info("Development server exited cleanly.")
+            return 0
+        except KeyboardInterrupt:
+            print_info("Development server stopped by user (Ctrl+C).")
+            return 0
+
+    try:
+        print_info(
+            f"Launching pnpm dev inside {payload_project} (via container)..."
+        )
+        docker.exec(
+            DEFAULT_PRIMARY_SERVICE,
+            "sh",
+            "-c",
+            f"cd /workspace/{payload_project} && "
+            "sh -c 'trap \"exit 0\" INT TERM; exec pnpm dev'",
+            check=False,
+        )
+    except Exception as e:
+        print_warning(f"Failed to launch pnpm dev: {e}")
+        print_info(
+            f"Fallback: cd {payload_project} && pnpm dev (or xgic shell)."
+        )
+
+    print_success("Environment ready for development.")
+    print_info("Environment context: " + env.describe())
+    return 0

xgic/cli/payload/commands/payload_env.py

@@ -0,0 +1,65 @@
+"""``xgic payload env`` — product-aware env status and credential regenerate.
+
+Nested under the ``payload`` domain group so it does not clash with the
+generic ``xgic env`` command in ``xgic.cli.dev``.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from xgic.cli.app import CommandContext
+from xgic.cli.payload.config import (
+    get_payload_project_name,
+    make_payload_docker_controller,
+)
+from xgic.cli.payload.env_helpers import ENV_FILE, perform_env_regenerate
+from xgic.cli.utils.output import print_info, print_success
+
+
+def run_payload_env(ctx: CommandContext) -> int:
+    """Inspect Payload CMS env status or regenerate credentials."""
+    if getattr(ctx.args, "regenerate", False):
+        return perform_env_regenerate(
+            dry_run=bool(getattr(ctx.args, "dry_run", False)),
+            yes=bool(getattr(ctx.args, "yes", False)),
+            env_file=Path(getattr(ctx.args, "env_file", None) or ENV_FILE),
+        )
+
+    docker = make_payload_docker_controller(ctx.env)
+    env_file_exists = ENV_FILE.exists()
+    services_ok = docker.services_running()
+    payload_project = get_payload_project_name()
+    use_json = bool(getattr(ctx.args, "json", False))
+
+    if use_json:
+        print(
+            json.dumps(
+                {
+                    "env_file_exists": env_file_exists,
+                    "env_file": str(ENV_FILE),
+                    "services_running": services_ok,
+                    "payload_project": payload_project,
+                    "environment": ctx.env.describe(),
+                },
+                indent=2,
+            )
+        )
+        return 0
+
+    print_info("Payload CMS development environment status:")
+    if env_file_exists:
+        print_success(f".env file exists at {ENV_FILE}")
+    else:
+        print_info(
+            f".env file not found at {ENV_FILE} "
+            "(use: xgic payload env --regenerate --yes)"
+        )
+    if services_ok:
+        print_success("Compose services: appear to be running")
+    else:
+        print_info("Compose services: not detected as running")
+    print_info(f"Configured Payload CMS project: {payload_project}")
+    print_info("Environment context: " + ctx.env.describe())
+    return 0

xgic/cli/payload/commands/reset.py

@@ -0,0 +1,108 @@
+"""``xgic payload reset`` — fast targeted project + DB volume reset."""
+
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+
+from xgic.cli.app import CommandContext
+from xgic.cli.payload.config import (
+    get_db_config,
+    get_db_profile,
+    get_payload_project_name,
+    make_payload_docker_controller,
+)
+from xgic.cli.payload.env_helpers import perform_env_regenerate
+from xgic.cli.payload.project import ensure_payload_project
+from xgic.cli.utils.output import print_info, print_success, print_warning
+
+
+def run_reset(ctx: CommandContext) -> int:
+    """Delete generated project folder and reset the active DB volume.
+
+    Credentials in ``.env`` are left alone unless ``--rotate-credentials``.
+    """
+    dry_run = bool(getattr(ctx.args, "dry_run", False))
+    yes = bool(getattr(ctx.args, "yes", False))
+    rotate = bool(getattr(ctx.args, "rotate_credentials", False))
+
+    docker = make_payload_docker_controller(ctx.env)
+    payload_project = get_payload_project_name()
+    project_path = Path(payload_project)
+    db_service = get_db_profile()
+    db_volume = docker.db_volume_name(db_service)
+
+    print_info("Planned actions for reset:")
+    print_info(f"  - Delete directory: {project_path}")
+    print_info(f"  - Remove Docker volume: {db_volume}")
+    if rotate:
+        print_warning("  - ALSO rotate database credentials (DANGEROUS)")
+
+    if dry_run:
+        print_success("Dry run complete. No changes were made.")
+        return 0
+
+    if not yes:
+        print_warning(
+            "This operation is destructive. Re-run with --yes to proceed."
+        )
+        return 1
+
+    print_info("Performing reset...")
+
+    if project_path.exists():
+        shutil.rmtree(project_path)
+        print_success(f"Deleted project directory: {project_path}")
+    else:
+        print_info(f"Project directory {project_path} did not exist.")
+
+    docker.rm_service(db_service, force=True, stop=True, remove_volumes=False)
+
+    if docker.remove_volume(db_volume):
+        print_success(f"Removed volume: {db_volume}")
+    else:
+        print_warning(
+            f"Could not remove volume {db_volume} (may not exist or in use)"
+        )
+
+    db_name, db_user = get_db_config()
+    try:
+        docker.up(services=[db_service], profile=db_service)
+        print_info(f"{db_service.capitalize()} service recreated.")
+
+        if db_service == "postgres":
+            sql = f"CREATE DATABASE IF NOT EXISTS {db_name} OWNER {db_user};"
+            docker.exec(
+                "postgres",
+                "sh",
+                "-c",
+                f'psql -U {db_user} -d postgres -c "{sql}" 2>/dev/null || true',
+                check=False,
+            )
+            print_success(f"Ensured database '{db_name}' exists.")
+        else:
+            print_info(
+                "MongoDB service recreated. DB will be initialized by the app "
+                "on first use."
+            )
+
+        ensure_payload_project()
+    except Exception as e:
+        print_warning(
+            f"Issue recreating {db_service} or DB: {e}. "
+            "Manual `xgic up --profile …` may be needed."
+        )
+
+    if rotate:
+        print_info("Rotating credentials (--rotate-credentials)...")
+        rc = perform_env_regenerate(yes=True)
+        if rc == 0:
+            print_success("Credentials rotated in .env.")
+        else:
+            print_warning("Credential rotation had issues (check .env).")
+
+    print_success(
+        "Reset complete. Project ensured. Next: `xgic payload dev` "
+        "(or `xgic up --profile …`)."
+    )
+    return 0

xgic/cli/payload/commands/schema.py

@@ -0,0 +1,38 @@
+"""``xgic payload schema`` — generate create-payload-config JSON schema."""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+from pathlib import Path
+
+from xgic.cli.app import CommandContext
+from xgic.cli.utils.output import print_info, print_success, print_warning
+
+GENERATOR = Path(".devcontainer/config/generate_schema.py")
+
+
+def run_schema(ctx: CommandContext) -> int:
+    """Generate (or refresh) the create-payload-config schema when present."""
+    script = Path(getattr(ctx.args, "generator", None) or GENERATOR)
+    if not script.exists():
+        print_warning(f"Generator not found: {script}")
+        print_info(
+            "This command expects a Payload CMS Dev Containers template "
+            "with .devcontainer/config/generate_schema.py"
+        )
+        return 1
+
+    print_info("Generating create-payload-config JSON schema...")
+    try:
+        subprocess.check_call([sys.executable, str(script)])
+        print_success(
+            "Schema written. IntelliSense updated for create-payload-config.json"
+        )
+        return 0
+    except subprocess.CalledProcessError as e:
+        print_warning(f"Generator exited with code {e.returncode}")
+        return e.returncode or 1
+    except Exception as e:
+        print_warning(f"Failed to run generator: {e}")
+        return 1

xgic/cli/payload/commands/setup.py

@@ -0,0 +1,12 @@
+"""``xgic payload setup`` — ensure Payload CMS project directory."""
+
+from __future__ import annotations
+
+from xgic.cli.app import CommandContext
+from xgic.cli.payload.project import ensure_payload_project
+
+
+def run_setup_payloadcms(ctx: CommandContext) -> int:
+    """Idempotent Payload CMS project ensure."""
+    quiet = bool(getattr(ctx.args, "quiet", False))
+    return ensure_payload_project(quiet=quiet)

xgic/cli/payload/config.py

@@ -0,0 +1,136 @@
+"""Payload CMS product defaults and config readers.
+
+Used with ``xgic.cli.dev.DockerComposeController`` for the public Payload CMS
+Dev Containers template. Core and dev-cli stay free of these product names.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from xgic.cli.core.environment import EnvironmentContext
+from xgic.cli.dev.docker import DockerComposeController
+
+DEFAULT_COMPOSE_PROJECT = "xgic-payload-cms-dev-containers"
+DEFAULT_PRIMARY_SERVICE = "xgic-payload-cms-dev-containers"
+DEFAULT_CONFIG_FILE = Path(".devcontainer/create-payload-config.json")
+DEFAULT_COMPOSE_FILE = ".devcontainer/docker-compose.yml"
+
+
+def get_payload_project_name(
+    config_file: Path = DEFAULT_CONFIG_FILE,
+) -> str:
+    """Return the name of the generated Payload CMS project folder."""
+    if config_file.exists():
+        try:
+            with open(config_file, encoding="utf-8") as f:
+                data: dict[str, Any] = json.load(f)
+            if name := data.get("projectName"):
+                return str(name)
+        except (json.JSONDecodeError, OSError):
+            pass
+    return "my-payload-cms"
+
+
+def get_db_config(
+    config_file: Path = DEFAULT_CONFIG_FILE,
+) -> tuple[str, str]:
+    """Return (db_name, db_user) from create-payload-config.json."""
+    default_db = "payload_db"
+    default_user = "payload"
+    if not config_file.exists():
+        return default_db, default_user
+    try:
+        with config_file.open(encoding="utf-8") as f:
+            cfg: dict[str, Any] = json.load(f)
+        db_name = cfg.get("dbName") or default_db
+        db_user = cfg.get("dbUser") or default_user
+        db_uri = cfg.get("dbUri") or ""
+        if db_uri and (db_name == default_db or db_user == default_user):
+            try:
+                if "://" in db_uri:
+                    after = db_uri.split("://", 1)[1]
+                    if "@" in after and db_user == default_user:
+                        creds = after.split("@", 1)[0]
+                        if ":" in creds:
+                            db_user = creds.split(":", 1)[0] or db_user
+                    if "/" in after and db_name == default_db:
+                        after_host = after.split("@", 1)[-1]
+                        path = after_host.split("/", 1)[-1].split("?")[0]
+                        if path:
+                            db_name = path or db_name
+            except Exception:
+                pass
+        return db_name, db_user
+    except Exception:
+        return default_db, default_user
+
+
+def get_db_profile(config_file: Path = DEFAULT_CONFIG_FILE) -> str:
+    """Return compose profile for the active DB adapter (postgres|mongodb)."""
+    if not config_file.exists():
+        return "postgres"
+    try:
+        with config_file.open(encoding="utf-8") as f:
+            cfg: dict[str, Any] = json.load(f)
+        adapter = str(cfg.get("dbAdapter", "postgres")).lower()
+        if adapter == "mongodb":
+            return "mongodb"
+        return "postgres"
+    except Exception:
+        return "postgres"
+
+
+def make_payload_docker_controller(
+    env: EnvironmentContext,
+) -> DockerComposeController:
+    """Build a Compose controller with Payload CMS template defaults."""
+    return DockerComposeController(
+        env=env,
+        compose_file=DEFAULT_COMPOSE_FILE,
+        project_name=DEFAULT_COMPOSE_PROJECT,
+        primary_service=DEFAULT_PRIMARY_SERVICE,
+    )
+
+
+def db_ready(
+    docker: DockerComposeController,
+    *,
+    config_file: Path = DEFAULT_CONFIG_FILE,
+) -> bool:
+    """Return True if the active DB service accepts connections."""
+    service = get_db_profile(config_file)
+    if service == "mongodb":
+        try:
+            result = docker._run_compose(  # noqa: SLF001 — intentional thin probe
+                "exec",
+                "-T",
+                service,
+                "mongosh",
+                "--quiet",
+                "--eval",
+                "db.runCommand({ping: 1})",
+                capture_output=True,
+                check=False,
+            )
+            return result.returncode == 0
+        except Exception:
+            return False
+
+    _, db_user = get_db_config(config_file)
+    try:
+        result = docker._run_compose(  # noqa: SLF001
+            "exec",
+            "-T",
+            "postgres",
+            "pg_isready",
+            "-U",
+            db_user,
+            capture_output=True,
+            check=False,
+        )
+        return result.returncode == 0
+    except Exception:
+        return False

xgic/cli/payload/env_helpers.py

@@ -0,0 +1,91 @@
+"""Payload CMS product env file generation (credentials + secrets)."""
+
+from __future__ import annotations
+
+import json
+import secrets
+from pathlib import Path
+
+from xgic.cli.payload.config import DEFAULT_CONFIG_FILE, get_db_config
+from xgic.cli.utils.output import print_info, print_success, print_warning
+
+ENV_FILE = Path(".devcontainer/.env")
+
+
+def generate_fresh_env_content(
+    *,
+    config_file: Path = DEFAULT_CONFIG_FILE,
+) -> str:
+    """Pure: return .env content with fresh secrets + db from config."""
+    db_name, db_user = get_db_config(config_file)
+    payload_secret = secrets.token_hex(32)
+
+    adapter = "postgres"
+    if config_file.exists():
+        try:
+            with config_file.open(encoding="utf-8") as f:
+                cfg = json.load(f)
+            adapter = str(cfg.get("dbAdapter", "postgres")).lower()
+        except Exception:
+            pass
+
+    if adapter == "mongodb":
+        mongo_pass = secrets.token_hex(16)
+        return f"""MONGO_INITDB_ROOT_USERNAME={db_user}
+MONGO_INITDB_ROOT_PASSWORD={mongo_pass}
+MONGO_INITDB_DATABASE={db_name}
+PAYLOAD_SECRET={payload_secret}
+DATABASE_URI=mongodb://{db_user}:{mongo_pass}@mongodb:27017/{db_name}?authSource=admin
+"""
+
+    pg_pass = secrets.token_hex(16)
+    return f"""POSTGRES_USER={db_user}
+POSTGRES_PASSWORD={pg_pass}
+POSTGRES_DB={db_name}
+PAYLOAD_SECRET={payload_secret}
+DATABASE_URI=postgres://{db_user}:{pg_pass}@postgres:5432/{db_name}
+"""
+
+
+def perform_env_regenerate(
+    *,
+    dry_run: bool = False,
+    yes: bool = False,
+    env_file: Path = ENV_FILE,
+    config_file: Path = DEFAULT_CONFIG_FILE,
+) -> int:
+    """Regenerate .env with fresh credentials (guarded by --yes / dry-run)."""
+    if dry_run:
+        content = generate_fresh_env_content(config_file=config_file)
+        print_info("Dry run: would write fresh credentials to .env")
+        print_info(f"  (content length: {len(content)} chars)")
+        return 0
+
+    if not yes:
+        print_warning("This will overwrite .env with new random credentials.")
+        print_warning("Re-run with --yes to proceed.")
+        return 1
+
+    content = generate_fresh_env_content(config_file=config_file)
+    try:
+        env_file.parent.mkdir(parents=True, exist_ok=True)
+        with env_file.open("w", encoding="utf-8") as f:
+            f.write(content)
+        db_name, db_user = get_db_config(config_file)
+        adapter = "postgres"
+        if config_file.exists():
+            try:
+                with config_file.open(encoding="utf-8") as f:
+                    cfg = json.load(f)
+                adapter = str(cfg.get("dbAdapter", "postgres")).lower()
+            except Exception:
+                pass
+        print_success(f"Generated fresh credentials in {env_file}")
+        if adapter == "mongodb":
+            print_info(f"  (MONGO DB for {db_name})")
+        else:
+            print_info(f"  (POSTGRES_DB={db_name}, POSTGRES_USER={db_user})")
+        return 0
+    except Exception as e:
+        print_warning(f"Failed to write {env_file}: {e}")
+        return 1

xgic/cli/payload/plugin.py

@@ -0,0 +1,121 @@
+"""Register ``xgic.cli.payload`` subcommands on the core ``xgic`` CLI.
+
+All product commands live under the ``payload`` group for domain ownership::
+
+    xgic payload dev
+    xgic payload setup
+    xgic payload env
+    xgic payload schema
+    xgic payload reset
+"""
+
+from __future__ import annotations
+
+import argparse
+
+from xgic.cli.payload.commands.dev import run_dev
+from xgic.cli.payload.commands.payload_env import run_payload_env
+from xgic.cli.payload.commands.reset import run_reset
+from xgic.cli.payload.commands.schema import run_schema
+from xgic.cli.payload.commands.setup import run_setup_payloadcms
+
+
+def register(
+    subparsers: argparse._SubParsersAction[argparse.ArgumentParser],
+) -> None:
+    """Entry point: ``xgic.cli.commands`` → Payload CMS product commands."""
+    payload = subparsers.add_parser(
+        "payload",
+        help="Payload CMS product commands",
+    )
+    payload_sub = payload.add_subparsers(
+        dest="payload_command",
+        help="Payload CMS action",
+        metavar="ACTION",
+        required=True,
+    )
+
+    # Smart daily command (maps from transitional `xde dev`)
+    dev = payload_sub.add_parser(
+        "dev",
+        help="Start Payload CMS app dev server (smart: up + db check + pnpm dev)",
+    )
+    dev.set_defaults(func=run_dev)
+
+    # Ensure project directory
+    setup = payload_sub.add_parser(
+        "setup",
+        help="Ensure Payload CMS project exists (idempotent)",
+    )
+    setup.add_argument(
+        "--quiet",
+        action="store_true",
+        help="Suppress non-error output",
+    )
+    setup.set_defaults(func=run_setup_payloadcms)
+
+    # Product env (distinct from generic `xgic env` in xgic.cli.dev)
+    penv = payload_sub.add_parser(
+        "env",
+        help="Payload CMS env status and credential regenerate",
+    )
+    penv.add_argument(
+        "--json",
+        action="store_true",
+        help="Output status as JSON",
+    )
+    penv.add_argument(
+        "--regenerate",
+        action="store_true",
+        help="Write fresh credentials to .devcontainer/.env",
+    )
+    penv.add_argument(
+        "--yes",
+        action="store_true",
+        help="Confirm regenerate without prompt",
+    )
+    penv.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Preview regenerate without writing",
+    )
+    penv.add_argument(
+        "--env-file",
+        metavar="PATH",
+        help="Override path to .env (default .devcontainer/.env)",
+    )
+    penv.set_defaults(func=run_payload_env)
+
+    # Schema generator for create-payload-config
+    schema = payload_sub.add_parser(
+        "schema",
+        help="Generate create-payload-config JSON schema (template helper)",
+    )
+    schema.add_argument(
+        "--generator",
+        metavar="PATH",
+        help="Override path to generate_schema.py",
+    )
+    schema.set_defaults(func=run_schema)
+
+    # Targeted reset (project dir + DB volume)
+    reset = payload_sub.add_parser(
+        "reset",
+        help="Fast targeted reset (project folder + active DB volume)",
+    )
+    reset.add_argument(
+        "--yes",
+        action="store_true",
+        help="Skip confirmation and proceed",
+    )
+    reset.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Show planned actions without making changes",
+    )
+    reset.add_argument(
+        "--rotate-credentials",
+        action="store_true",
+        help="Also regenerate .devcontainer/.env credentials",
+    )
+    reset.set_defaults(func=run_reset)

xgic/cli/payload/project.py

@@ -0,0 +1,212 @@
+"""Payload CMS project setup / ensure helpers."""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import os
+import re
+import subprocess
+from pathlib import Path
+from typing import Any
+
+from xgic.cli.payload.config import DEFAULT_CONFIG_FILE
+from xgic.cli.utils.output import print_info, print_success, print_warning
+
+
+def load_create_payload_config(
+    config_path: Path = DEFAULT_CONFIG_FILE,
+) -> dict[str, Any]:
+    """Load create-payload-config.json (or sensible defaults)."""
+    defaults: dict[str, Any] = {
+        "projectName": "my-payload-cms",
+        "template": "website",
+        "dbAdapter": "postgres",
+        "agent": "none",
+        "dbUri": "",
+    }
+    if not config_path.exists():
+        return defaults
+    try:
+        with config_path.open(encoding="utf-8") as f:
+            data: dict[str, Any] = json.load(f)
+        for k, v in data.items():
+            if v is not None:
+                defaults[k] = v
+        return defaults
+    except (json.JSONDecodeError, OSError):
+        return defaults
+
+
+def get_project_name(config: dict[str, Any]) -> str:
+    """Extract projectName with safe default."""
+    name = config.get("projectName")
+    if isinstance(name, str) and name.strip():
+        return name.strip()
+    return "my-payload-cms"
+
+
+def is_payload_project_complete(project_dir: Path) -> bool:
+    """Return True if project_dir looks like a finished Payload CMS app."""
+    if not project_dir.is_dir():
+        return False
+    candidates = [
+        project_dir / "payload.config.ts",
+        project_dir / "payload.config.js",
+        project_dir / "src" / "payload.config.ts",
+        project_dir / "src" / "payload.config.js",
+    ]
+    return any(p.exists() for p in candidates)
+
+
+def build_create_payload_command(
+    project_name: str,
+    *,
+    template: str = "website",
+    db_adapter: str = "postgres",
+    db_connection_string: str | None = None,
+    agent: str = "none",
+) -> list[str]:
+    """Return the argv list for a non-interactive create-payload-app run."""
+    cmd = [
+        "pnpx",
+        "create-payload-app@latest",
+        project_name,
+        "-t",
+        template,
+        "--use-pnpm",
+    ]
+
+    if db_connection_string:
+        cmd.extend(
+            ["--db", db_adapter, "--db-connection-string", db_connection_string]
+        )
+    else:
+        cmd.extend(["--db", db_adapter, "--db-accept-recommended"])
+
+    if agent and str(agent).lower() not in ("", "none"):
+        cmd.extend(["--agent", str(agent)])
+    else:
+        cmd.append("--no-agent")
+
+    return cmd
+
+
+def resolve_db_connection_string(
+    json_db_uri: str, live_db_uri: str
+) -> str | None:
+    """Prefer live env DB URI over config JSON."""
+    return live_db_uri or json_db_uri or None
+
+
+def compute_synced_project_env_content(
+    original_content: str, live_db_uri: str, live_payload_secret: str
+) -> str:
+    """Return .env content with live DATABASE_URL / PAYLOAD_SECRET."""
+    content = original_content
+    if live_db_uri:
+        content = re.sub(
+            r"^DATABASE_URL=.*$",
+            f"DATABASE_URL={live_db_uri}",
+            content,
+            flags=re.MULTILINE,
+        )
+    if live_payload_secret:
+        content = re.sub(
+            r"^PAYLOAD_SECRET=.*$",
+            f"PAYLOAD_SECRET={live_payload_secret}",
+            content,
+            flags=re.MULTILINE,
+        )
+    return content
+
+
+def _sync_live_env_into_project(
+    project_dir: Path, live_db_uri: str, live_payload_secret: str
+) -> None:
+    """Best-effort sync of live credentials into the generated project's .env."""
+    gen_env = project_dir / ".env"
+    if not gen_env.is_file():
+        return
+
+    try:
+        content = gen_env.read_text(encoding="utf-8")
+        new_content = compute_synced_project_env_content(
+            content, live_db_uri, live_payload_secret
+        )
+        if new_content != content:
+            gen_env.write_text(new_content, encoding="utf-8")
+    except Exception:
+        pass
+
+
+def ensure_payload_project(*, quiet: bool = False) -> int:
+    """Ensure the Payload CMS project directory exists and is usable."""
+    cfg = load_create_payload_config()
+    project_name = get_project_name(cfg)
+    project_dir = Path(project_name)
+
+    if is_payload_project_complete(project_dir):
+        return 0
+
+    if project_dir.exists() and not quiet:
+        print_warning(
+            f"Directory '{project_name}' exists but does not appear to be "
+            "a complete Payload CMS project. Creation may overwrite or fail."
+        )
+
+    template = str(cfg.get("template") or "website")
+    db_adapter = str(cfg.get("dbAdapter") or "postgres")
+    json_db_uri = str(cfg.get("dbUri") or "")
+    agent = str(cfg.get("agent") or "none")
+
+    live_db_uri = os.environ.get("DATABASE_URI", "")
+    live_secret = os.environ.get("PAYLOAD_SECRET", "")
+
+    db_uri_for_cli: str | None = resolve_db_connection_string(
+        json_db_uri, live_db_uri
+    )
+
+    with contextlib.suppress(Exception):
+        subprocess.run(
+            ["corepack", "pnpm", "approve-builds", "@swc/core"],
+            check=False,
+            capture_output=True,
+        )
+
+    cmd = build_create_payload_command(
+        project_name,
+        template=template,
+        db_adapter=db_adapter,
+        db_connection_string=db_uri_for_cli,
+        agent=agent,
+    )
+
+    if not quiet:
+        print_info(
+            f"Starting Payload CMS project creation for '{project_name}' "
+            f"(template: {template}, db: {db_adapter})..."
+        )
+
+    try:
+        result = subprocess.run(cmd, check=False)
+    except FileNotFoundError as e:
+        print_warning(f"Required tool not found for project creation: {e}")
+        return 1
+
+    if result.returncode == 0:
+        if not quiet:
+            print_success("Payload CMS project created successfully.")
+        if project_dir.is_dir():
+            _sync_live_env_into_project(project_dir, live_db_uri, live_secret)
+        return 0
+
+    if not quiet:
+        print_warning(
+            f"create-payload-app exited with status {result.returncode}."
+        )
+        print_info(
+            "This is often harmless. Check the project directory. "
+            "Re-run with the Payload CMS CLI module when available."
+        )
+    return 0

xgic_payload_cms_cli-0.2.0.dist-info/METADATA

@@ -0,0 +1,113 @@
+Metadata-Version: 2.4
+Name: xgic-payload-cms-cli
+Version: 0.2.0
+Summary: XGIC CLI Payload CMS module - product commands and helpers (xgic.cli.payload).
+Project-URL: Homepage, https://github.com/xgic/payload-cms-cli
+Project-URL: Repository, https://github.com/xgic/payload-cms-cli
+Project-URL: Issues, https://github.com/xgic/payload-cms-cli/issues
+Project-URL: Documentation, https://github.com/xgic/payload-cms-cli#readme
+Project-URL: Changelog, https://github.com/xgic/payload-cms-cli/releases
+Author: XGIC
+License: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Keywords: cli,orchestration,payload-cms,xgic
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.14
+Requires-Dist: rich>=13.7
+Requires-Dist: xgic-cli>=0.2.0
+Requires-Dist: xgic-dev-cli>=0.2.0
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.4.0; extra == 'dev'
+Provides-Extra: test
+Requires-Dist: pytest>=8.0.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# XGIC Payload CMS CLI
+
+[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+
+**XGIC Payload CMS CLI** (`xgic.cli.payload`) provides **Payload CMS–specific** helpers and **`xgic payload …` subcommands** for the modular [XGIC CLI](https://github.com/xgic/cli).
+
+Architecture: [ADR-0005](https://github.com/xgic/ai/blob/main/docs/adr/0005-modular-xgic-cli-and-retirement-of-xde.md).
+
+**Publishing to PyPI:** [python-package-release.md](https://github.com/xgic/ai/blob/main/docs/python-package-release.md)  
+(publish **after** `xgic-cli` and `xgic-dev-cli` for stack releases). Tags: `vX.Y.ZrcN` → TestPyPI; `vX.Y.Z` → PyPI.
+
+| Package | Role |
+|---------|------|
+| [xgic/cli](https://github.com/xgic/cli) | Thin core framework (`xgic`) |
+| [xgic/dev-cli](https://github.com/xgic/dev-cli) | Dev Container / Compose + generic lifecycle |
+| **This repo** | Payload CMS product module (`xgic.cli.payload`) |
+
+## Status
+
+**0.2.0 — B4 product commands.** Library helpers + nested `xgic payload` command group. Transitional in-tree `xde` may still ship until hard cutover (B5).
+
+## Requirements
+
+- Python **3.14+**
+- `xgic-cli` ≥ 0.2.0
+- `xgic-dev-cli` ≥ 0.2.0
+
+## Install (development)
+
+```bash
+python -m pip install -e ../cli
+python -m pip install -e ../dev-cli
+python -m pip install -e ".[dev]"
+xgic payload --help
+```
+
+## Console commands
+
+All product commands are nested under **`xgic payload`** (domain ownership; no clash with generic lifecycle).
+
+| Command | Purpose |
+|---------|---------|
+| `xgic payload dev` | Smart start: compose up if needed, DB check, `pnpm dev` |
+| `xgic payload setup [--quiet]` | Ensure Payload CMS project directory |
+| `xgic payload env [--json]` | Product env status (project name, .env, services) |
+| `xgic payload env --regenerate --yes` | Fresh credentials in `.devcontainer/.env` |
+| `xgic payload schema` | Run template schema generator when present |
+| `xgic payload reset` | Fast targeted reset (project folder + DB volume) |
+
+**Note:** Generic lifecycle (`xgic up` / `down` / `check` / `env`) lives in **dev-cli**.  
+Use `xgic payload env` for Payload CMS credentials and product status.
+
+### Command map (transitional `xde` → XGIC CLI)
+
+| Today (`xde`) | Target |
+|---------------|--------|
+| `xde dev` | `xgic payload dev` |
+| `xde setup payloadcms` | `xgic payload setup` |
+| `xde schema` | `xgic payload schema` |
+| `xde env --regenerate` | `xgic payload env --regenerate --yes` |
+| `xde reset` | `xgic payload reset` |
+| `xde up` / `down` / … | `xgic up` / `down` / … (dev-cli) |
+
+## Library API
+
+```python
+from xgic.cli.payload import (
+    ensure_payload_project,
+    generate_fresh_env_content,
+    make_payload_docker_controller,
+    get_payload_project_name,
+)
+```
+
+## License
+
+Apache License 2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE).  
+Copyright form: `Copyright 2026 XGIC`.

xgic_payload_cms_cli-0.2.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+xgic/cli/payload/__init__.py,sha256=04HBEfBv1336cp3qvErfPRzgWsB0WKD833j7B1WtcDs,980
+xgic/cli/payload/config.py,sha256=agxzSwuBrdHZvMER_25mkIHNlVBGJUwyl773GJvwXzk,4532
+xgic/cli/payload/env_helpers.py,sha256=7J0n5_7Z7BQnZnHQVVWrz70yOkqaEI5c_9xjlgplJK0,3033
+xgic/cli/payload/plugin.py,sha256=vYRxfNtzX_jD8XWyjxPSX-gfq9tnE-jwEiYUPqqxNLI,3499
+xgic/cli/payload/project.py,sha256=qwzcTypmod0N_58SEOXsZA48p-X8QY8Lefsd-liEijQ,6265
+xgic/cli/payload/commands/__init__.py,sha256=2XjZS1iYhUw5QO7JrG0lCaeLd-66HFW5_jSyb_soYS8,53
+xgic/cli/payload/commands/dev.py,sha256=yznAHsJh70Vw-RHDyNNSYDuTN8--YhdXPKUWtQzIGME,3019
+xgic/cli/payload/commands/payload_env.py,sha256=IBTCTIcd7Q6Krg5z-nps6Ymvq4NdUKORsUpurbvCQgI,2232
+xgic/cli/payload/commands/reset.py,sha256=0vgU18nNrC6he5bpIqyDl0LkjsVSvRuIttREtihltG0,3576
+xgic/cli/payload/commands/schema.py,sha256=wLK3QLOrUCdkKxDOoFO3q2l-Fv1behsV69nhtwU4Sq0,1320
+xgic/cli/payload/commands/setup.py,sha256=YbgjhZYc4u1kGAOu1WwFcOFbAuT3y9U-zbusAAZyGoc,412
+xgic_payload_cms_cli-0.2.0.dist-info/METADATA,sha256=q_GADmO6pmYvdPm0m0hZTbCZHCh3gkTeiIwi-WWTp0w,4344
+xgic_payload_cms_cli-0.2.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+xgic_payload_cms_cli-0.2.0.dist-info/entry_points.txt,sha256=5nTFyPIAAgwc8PZyc_wRu9gfYq6CCwlVi1oCSKBC02Q,63
+xgic_payload_cms_cli-0.2.0.dist-info/licenses/LICENSE,sha256=zR7vJ5cGf_9LgWHYDAugptsXPsV0_78I9kvVnf7VRk0,11335
+xgic_payload_cms_cli-0.2.0.dist-info/licenses/NOTICE,sha256=KcqsVZjszSfr06TJjV7mdutBiCXlvqtlLhnI4Pj8Jzs,212
+xgic_payload_cms_cli-0.2.0.dist-info/RECORD,,

xgic_payload_cms_cli-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

xgic_payload_cms_cli-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[xgic.cli.commands]
+payload = xgic.cli.payload.plugin:register

xgic_payload_cms_cli-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,202 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 XGIC
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+

xgic_payload_cms_cli-0.2.0.dist-info/licenses/NOTICE

@@ -0,0 +1,8 @@
+XGIC Payload CMS CLI
+Copyright 2026 XGIC
+
+This product includes software and documentation developed at XGIC
+(https://xgic.net).
+
+Licensed under the Apache License, Version 2.0.
+See the LICENSE file for details.