xgic-wagtail-cli 0.1.0__py3-none-any.whl

xgic/cli/wagtail/__init__.py

@@ -0,0 +1,5 @@
+"""XGIC CLI Wagtail module (``xgic.cli.wagtail``)."""
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

xgic/cli/wagtail/commands/__init__.py

@@ -0,0 +1 @@
+"""Wagtail CLI command handlers."""

xgic/cli/wagtail/commands/dev.py

@@ -0,0 +1,99 @@
+"""``xgic wagtail dev`` — foreground Django/Wagtail runserver."""
+
+from __future__ import annotations
+
+import os
+import signal
+import socket
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+from xgic.cli.app import CommandContext
+from xgic.cli.utils.output import print_info, print_warning
+from xgic.cli.wagtail.project import is_wagtail_project_complete
+
+_SIGINT_EXIT_CODES = {130, -signal.SIGINT, 128 + signal.SIGINT}
+
+
+def _wait_for_postgres(host: str, port: int, timeout: float = 60.0) -> bool:
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        try:
+            with socket.create_connection((host, port), 2.0):
+                return True
+        except OSError:
+            time.sleep(0.5)
+    return False
+
+
+def _manage_py(root: Path) -> Path:
+    return root / "manage.py"
+
+
+def run_dev(ctx: CommandContext) -> int:
+    """Migrate (idempotent) and run ``manage.py runserver 0.0.0.0:8000``."""
+    quiet = bool(getattr(ctx.args, "quiet", False))
+    root = Path.cwd()
+    if not is_wagtail_project_complete(root):
+        print_warning(
+            "No Wagtail site in this workspace. Run: xgic wagtail setup"
+        )
+        return 2
+
+    manage = _manage_py(root)
+    host = os.environ.get("POSTGRES_HOST", "postgres")
+    port = int(os.environ.get("POSTGRES_PORT", "5432"))
+    if not _wait_for_postgres(host, port):
+        print_warning(
+            f"PostgreSQL is not reachable at {host}:{port}. "
+            "Start Compose postgres, then retry: xgic wagtail dev"
+        )
+        return 1
+
+    python = sys.executable
+    if not quiet:
+        print_info("Running: python manage.py migrate --noinput")
+    migrate = subprocess.run(
+        [python, str(manage), "migrate", "--noinput"],
+        cwd=str(root),
+        check=False,
+    )
+    if migrate.returncode != 0:
+        print_warning("migrate failed. Fix the database, then retry: xgic wagtail dev")
+        return int(migrate.returncode)
+
+    bind = os.environ.get("WAGTAIL_DEV_BIND", "0.0.0.0:8000")
+    if not quiet:
+        print_info(f"Launching: python manage.py runserver {bind}")
+        print_info("Stop with Ctrl+C.")
+
+    try:
+        proc = subprocess.Popen(
+            [python, str(manage), "runserver", bind],
+            cwd=str(root),
+            stdin=sys.stdin,
+            stdout=sys.stdout,
+            stderr=sys.stderr,
+        )
+    except OSError as exc:
+        print_warning(f"Could not start runserver: {exc}")
+        return 1
+
+    try:
+        returncode = int(proc.wait())
+    except KeyboardInterrupt:
+        proc.send_signal(signal.SIGINT)
+        try:
+            returncode = int(proc.wait(timeout=15))
+        except subprocess.TimeoutExpired:
+            proc.kill()
+            proc.wait(timeout=5)
+            returncode = 130
+
+    if returncode in _SIGINT_EXIT_CODES:
+        if not quiet:
+            print_info("Development server stopped by user (Ctrl+C).")
+        return 0
+    return returncode

xgic/cli/wagtail/commands/info.py

@@ -0,0 +1,34 @@
+"""``xgic wagtail info`` — module status."""
+
+from __future__ import annotations
+
+import argparse
+import json
+
+from xgic.cli.utils.output import print_info, print_success
+from xgic.cli.wagtail import __version__
+
+
+def run_info(ctx: argparse.Namespace) -> int:
+    """Print Wagtail CLI module identity and capabilities."""
+    args = getattr(ctx, "args", ctx)
+    payload = {
+        "module": "xgic.cli.wagtail",
+        "package": "xgic-wagtail-cli",
+        "version": __version__,
+        "status": "experimental",
+        "commands": ["info", "setup", "schema", "dev"],
+        "repository": "https://github.com/xgic/wagtail-cli",
+        "template": "https://github.com/xgic/wagtail",
+        "producer": "https://github.com/xgic/wagtail-dev",
+    }
+    if getattr(args, "json", False):
+        print(json.dumps(payload, indent=2))
+        return 0
+
+    print_success(f"XGIC Wagtail CLI {__version__} (experimental)")
+    print_info("Namespace: xgic.cli.wagtail")
+    print_info("Repo: https://github.com/xgic/wagtail-cli")
+    print_info("Commands: info, setup, schema, dev")
+    print_info("Template: https://github.com/xgic/wagtail")
+    return 0

xgic/cli/wagtail/commands/schema.py

@@ -0,0 +1,23 @@
+"""``xgic wagtail schema`` — write create-wagtail-config JSON Schema."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from xgic.cli.app import CommandContext
+from xgic.cli.utils.output import print_success, print_warning
+from xgic.cli.wagtail.config import DEFAULT_SCHEMA_FILE
+from xgic.cli.wagtail.schema import write_schema
+
+
+def run_schema(ctx: CommandContext) -> int:
+    """Write JSON Schema for create-wagtail-config.json."""
+    override = getattr(ctx.args, "output", None)
+    path = Path(override) if override else DEFAULT_SCHEMA_FILE
+    try:
+        written = write_schema(path)
+    except OSError as exc:
+        print_warning(f"Could not write {path}: {exc}")
+        return 1
+    print_success(f"Wrote {written} (IntelliSense for create-wagtail-config.json)")
+    return 0

xgic/cli/wagtail/commands/setup.py

@@ -0,0 +1,12 @@
+"""``xgic wagtail setup`` — ensure Wagtail site with PostgreSQL."""
+
+from __future__ import annotations
+
+from xgic.cli.app import CommandContext
+from xgic.cli.wagtail.project import ensure_wagtail_project
+
+
+def run_setup(ctx: CommandContext) -> int:
+    """Idempotent Wagtail project ensure (PostgreSQL default)."""
+    quiet = bool(getattr(ctx.args, "quiet", False))
+    return ensure_wagtail_project(quiet=quiet)

xgic/cli/wagtail/config.py

@@ -0,0 +1,112 @@
+"""Wagtail product defaults and create-wagtail-config.json readers."""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any
+
+DEFAULT_CONFIG_FILE = Path(".devcontainer/create-wagtail-config.json")
+DEFAULT_SCHEMA_FILE = Path(".devcontainer/create-wagtail-config.schema.json")
+DEFAULT_COMPOSE_FILE = Path(".devcontainer/docker-compose.yml")
+DEFAULT_PROJECT_NAME = "mysite"
+DEFAULT_COMPOSE_PROJECT = "xgic-wagtail"
+DEFAULT_DB_ADAPTER = "postgres"
+DEFAULT_DB_NAME = "wagtail"
+DEFAULT_DB_USER = "wagtail"
+ALLOWED_DB_ADAPTERS = frozenset({DEFAULT_DB_ADAPTER})
+
+
+def _is_compose_safe_name(name: str) -> bool:
+    if not name or not name[0].isalnum():
+        return False
+    return all(c.isalnum() or c in "_-" for c in name) and len(name) <= 63
+
+
+def load_create_wagtail_config(
+    config_path: Path = DEFAULT_CONFIG_FILE,
+) -> dict[str, Any]:
+    """Load create-wagtail-config.json or return XGIC defaults."""
+    defaults: dict[str, Any] = {
+        "projectName": DEFAULT_PROJECT_NAME,
+        "composeProjectName": DEFAULT_COMPOSE_PROJECT,
+        "dbAdapter": DEFAULT_DB_ADAPTER,
+        "dbName": DEFAULT_DB_NAME,
+        "dbUser": DEFAULT_DB_USER,
+    }
+    if not config_path.is_file():
+        return defaults
+    try:
+        data = json.loads(config_path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        return defaults
+    if not isinstance(data, dict):
+        return defaults
+    for key, value in data.items():
+        if key == "$schema":
+            continue
+        if value is not None:
+            defaults[key] = value
+    return defaults
+
+
+def get_project_name(config: dict[str, Any] | None = None) -> str:
+    """Return Django/Wagtail project package name."""
+    cfg = config if config is not None else load_create_wagtail_config()
+    name = cfg.get("projectName")
+    if isinstance(name, str) and name.strip():
+        return name.strip()
+    return DEFAULT_PROJECT_NAME
+
+
+def get_db_adapter(config: dict[str, Any] | None = None) -> str:
+    """Return database adapter (XGIC default: postgres)."""
+    cfg = config if config is not None else load_create_wagtail_config()
+    adapter = str(cfg.get("dbAdapter") or DEFAULT_DB_ADAPTER).strip().lower()
+    if adapter in {"postgresql", "psql"}:
+        return DEFAULT_DB_ADAPTER
+    return adapter or DEFAULT_DB_ADAPTER
+
+
+def get_db_config(config: dict[str, Any] | None = None) -> tuple[str, str]:
+    """Return ``(dbName, dbUser)``."""
+    cfg = config if config is not None else load_create_wagtail_config()
+    db_name = str(cfg.get("dbName") or DEFAULT_DB_NAME).strip() or DEFAULT_DB_NAME
+    db_user = str(cfg.get("dbUser") or DEFAULT_DB_USER).strip() or DEFAULT_DB_USER
+    return db_name, db_user
+
+
+def get_compose_project_name(config: dict[str, Any] | None = None) -> str:
+    """Return Docker Compose project name.
+
+    Precedence: ``XGIC_COMPOSE_PROJECT``, config ``composeProjectName``,
+    Compose file ``name:``, then ``DEFAULT_COMPOSE_PROJECT``.
+    """
+    env_name = os.environ.get("XGIC_COMPOSE_PROJECT", "").strip().lower()
+    if env_name and _is_compose_safe_name(env_name):
+        return env_name
+    cfg = config if config is not None else load_create_wagtail_config()
+    named = str(cfg.get("composeProjectName") or "").strip().lower()
+    if named and _is_compose_safe_name(named):
+        return named
+    compose_name = _compose_name_from_file(DEFAULT_COMPOSE_FILE)
+    if compose_name:
+        return compose_name
+    return DEFAULT_COMPOSE_PROJECT
+
+
+def _compose_name_from_file(compose_path: Path) -> str | None:
+    if not compose_path.is_file():
+        return None
+    try:
+        for line in compose_path.read_text(encoding="utf-8").splitlines():
+            stripped = line.strip()
+            if stripped.startswith("#") or not stripped.startswith("name:"):
+                continue
+            raw = stripped.split(":", 1)[1].strip().strip("\"'")
+            if raw and _is_compose_safe_name(raw.lower()):
+                return raw.lower()
+    except OSError:
+        return None
+    return None

xgic/cli/wagtail/env_helpers.py

@@ -0,0 +1,69 @@
+"""Compose ``.devcontainer/.env`` helpers for Wagtail + PostgreSQL."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from xgic.cli.wagtail.config import (
+    DEFAULT_CONFIG_FILE,
+    get_db_config,
+    load_create_wagtail_config,
+)
+
+ENV_FILE = Path(".devcontainer/.env")
+
+
+def parse_dotenv(content: str) -> dict[str, str]:
+    """Parse KEY=value assignments from .env text (last key wins)."""
+    values: dict[str, str] = {}
+    for line in content.splitlines():
+        stripped = line.strip()
+        if not stripped or stripped.startswith("#") or "=" not in stripped:
+            continue
+        key, _, value = stripped.partition("=")
+        key = key.strip()
+        if not key:
+            continue
+        values[key] = value.strip().strip('"').strip("'")
+    return values
+
+
+def generate_env_content(
+    *,
+    config: dict[str, Any] | None = None,
+    preserve: dict[str, str] | None = None,
+) -> str:
+    """Return compose .env content for PostgreSQL.
+
+    First-run uses a stable local password when none is preserved so an
+    already-started Compose Postgres with the template default still matches.
+    """
+    cfg = config if config is not None else load_create_wagtail_config()
+    db_name, db_user = get_db_config(cfg)
+    kept = preserve or {}
+    password = kept.get("POSTGRES_PASSWORD") or "wagtail"
+    return (
+        f"POSTGRES_USER={db_user}\n"
+        f"POSTGRES_PASSWORD={password}\n"
+        f"POSTGRES_DB={db_name}\n"
+        f"PGUSER={db_user}\n"
+        f"PGDATABASE={db_name}\n"
+        f"POSTGRES_HOST=postgres\n"
+        f"POSTGRES_PORT=5432\n"
+        f"DATABASE_URL=postgres://{db_user}:{password}@postgres:5432/{db_name}\n"
+    )
+
+
+def ensure_devcontainer_env(
+    *,
+    config_path: Path = DEFAULT_CONFIG_FILE,
+    env_file: Path = ENV_FILE,
+) -> bool:
+    """Create ``.devcontainer/.env`` when missing. Return True if written."""
+    if env_file.is_file():
+        return False
+    cfg = load_create_wagtail_config(config_path)
+    env_file.parent.mkdir(parents=True, exist_ok=True)
+    env_file.write_text(generate_env_content(config=cfg), encoding="utf-8")
+    return True

xgic/cli/wagtail/plugin.py

@@ -0,0 +1,89 @@
+"""Register ``xgic.cli.wagtail`` subcommands on the core ``xgic`` CLI.
+
+Product commands live under the ``wagtail`` group::
+
+    xgic wagtail
+    xgic wagtail info
+    xgic wagtail setup
+    xgic wagtail schema
+    xgic wagtail dev
+    xgic wagtail --help
+
+Missing ACTION prints full usage (not a short argparse required-args error).
+"""
+
+from __future__ import annotations
+
+import argparse
+
+from xgic.cli.wagtail.commands.dev import run_dev
+from xgic.cli.wagtail.commands.info import run_info
+from xgic.cli.wagtail.commands.schema import run_schema
+from xgic.cli.wagtail.commands.setup import run_setup
+
+
+def register(
+    subparsers: argparse._SubParsersAction[argparse.ArgumentParser],
+) -> None:
+    """Entry point: ``xgic.cli.commands`` → Wagtail product commands."""
+    wagtail = subparsers.add_parser(
+        "wagtail",
+        help="Wagtail product commands",
+        description="Wagtail CMS commands for the modular XGIC CLI.",
+    )
+    wagtail_sub = wagtail.add_subparsers(
+        dest="wagtail_command",
+        help="Wagtail action",
+        metavar="ACTION",
+        required=False,
+    )
+
+    def _missing_action(_args: argparse.Namespace) -> int:
+        wagtail.print_help()
+        return 2
+
+    wagtail.set_defaults(func=_missing_action)
+
+    info = wagtail_sub.add_parser(
+        "info",
+        help="Show Wagtail CLI module version and status",
+    )
+    info.add_argument(
+        "--json",
+        action="store_true",
+        help="Output as JSON",
+    )
+    info.set_defaults(func=run_info)
+
+    setup = wagtail_sub.add_parser(
+        "setup",
+        help="Ensure Wagtail site with PostgreSQL (idempotent)",
+    )
+    setup.add_argument(
+        "--quiet",
+        action="store_true",
+        help="Suppress non-error output",
+    )
+    setup.set_defaults(func=run_setup)
+
+    schema = wagtail_sub.add_parser(
+        "schema",
+        help="Write create-wagtail-config JSON Schema (editor IntelliSense)",
+    )
+    schema.add_argument(
+        "--output",
+        metavar="PATH",
+        help="Override schema output path",
+    )
+    schema.set_defaults(func=run_schema)
+
+    dev = wagtail_sub.add_parser(
+        "dev",
+        help="Migrate and run the Wagtail/Django development server",
+    )
+    dev.add_argument(
+        "--quiet",
+        action="store_true",
+        help="Suppress non-error output",
+    )
+    dev.set_defaults(func=run_dev)

xgic/cli/wagtail/project.py

@@ -0,0 +1,268 @@
+"""Idempotent Wagtail project ensure (PostgreSQL default)."""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import shutil
+import subprocess
+from pathlib import Path
+from typing import Any
+
+from xgic.cli.utils.output import print_info, print_success, print_warning
+from xgic.cli.wagtail.config import (
+    ALLOWED_DB_ADAPTERS,
+    DEFAULT_CONFIG_FILE,
+    DEFAULT_DB_ADAPTER,
+    DEFAULT_SCHEMA_FILE,
+    get_db_adapter,
+    get_project_name,
+    load_create_wagtail_config,
+)
+from xgic.cli.wagtail.env_helpers import ensure_devcontainer_env
+from xgic.cli.wagtail.schema import write_schema
+
+POSTGRES_DATABASES_BLOCK = """DATABASES = {
+    "default": {
+        "ENGINE": "django.db.backends.postgresql",
+        "NAME": os.environ.get("POSTGRES_DB", "wagtail"),
+        "USER": os.environ.get("POSTGRES_USER", "wagtail"),
+        "PASSWORD": os.environ.get("POSTGRES_PASSWORD", ""),
+        "HOST": os.environ.get("POSTGRES_HOST", "postgres"),
+        "PORT": os.environ.get("POSTGRES_PORT", "5432"),
+        "CONN_MAX_AGE": 600,
+    }
+}"""
+
+_DATABASES_RE = re.compile(
+    r"DATABASES\s*=\s*\{(?:[^{}]|\{[^{}]*\})*\}",
+    re.DOTALL,
+)
+
+
+def is_wagtail_project_complete(root: Path | None = None) -> bool:
+    """Return True when ``manage.py`` and a Django settings package exist."""
+    base = Path.cwd() if root is None else root
+    if not (base / "manage.py").is_file():
+        return False
+    return find_settings_base(base) is not None
+
+
+def find_settings_base(root: Path | None = None) -> Path | None:
+    """Locate ``settings/base.py`` under the workspace (skip virtualenvs)."""
+    base = Path.cwd() if root is None else root
+    skip = {".venv", "venv", "node_modules", ".git"}
+    for path in base.rglob("settings/base.py"):
+        if skip.intersection(path.relative_to(base).parts):
+            continue
+        return path
+    return None
+
+
+def ensure_import_os(text: str) -> str:
+    """Ensure ``import os`` is present in a Django settings module."""
+    if re.search(r"(?m)^import os\s*$", text):
+        return text
+    if re.search(r"(?m)^from pathlib import Path\s*$", text):
+        return re.sub(
+            r"(?m)^(from pathlib import Path\s*)$",
+            r"\1\nimport os",
+            text,
+            count=1,
+        )
+    return "import os\n" + text
+
+
+def patch_databases(text: str) -> tuple[str, bool]:
+    """Replace SQLite DATABASES with env-driven PostgreSQL. Return (text, changed)."""
+    if 'django.db.backends.postgresql' in text and "os.environ.get(\"POSTGRES_DB\"" in text:
+        return text, False
+    match = _DATABASES_RE.search(text)
+    if match is None:
+        return text, False
+    updated = text[: match.start()] + POSTGRES_DATABASES_BLOCK + text[match.end() :]
+    updated = ensure_import_os(updated)
+    return updated, updated != text
+
+
+# Inserted into the generated project's settings/base.py INSTALLED_APPS,
+# immediately before django.contrib.admin (Wagtail start template).
+_POSTGRES_APP_INSERT = (
+    '"django.contrib.postgres",  '
+    "# Wagtail postgres search (SearchVectorField / GinIndex)\n"
+    '    "django.contrib.admin"'
+)
+
+
+def ensure_postgres_installed_apps(text: str) -> tuple[str, bool]:
+    """Insert ``django.contrib.postgres`` into generated ``INSTALLED_APPS``.
+
+    **Where:** ``<project>/settings/base.py`` created by ``wagtail start``,
+    in the Django contrib block, immediately before ``django.contrib.admin``.
+    Not added to the thin GitHub template itself.
+
+    **Why:** Wagtail's default database search backend on PostgreSQL uses
+    ``SearchVectorField`` and ``GinIndex``. Without this app, ``migrate``
+    fails with ``postgres.E005``. The stock ``wagtail start`` template omits
+    it because it defaults to SQLite.
+    """
+    if "django.contrib.postgres" in text:
+        return text, False
+    needle = '"django.contrib.admin"'
+    if needle not in text:
+        return text, False
+    updated = text.replace(needle, _POSTGRES_APP_INSERT, 1)
+    return updated, updated != text
+
+
+def patch_settings_base(settings_base: Path) -> bool:
+    """Patch generated ``settings/base.py``: PostgreSQL DATABASES + INSTALLED_APPS."""
+    original = settings_base.read_text(encoding="utf-8")
+    updated, db_changed = patch_databases(original)
+    updated, apps_changed = ensure_postgres_installed_apps(updated)
+    if not db_changed and not apps_changed:
+        return False
+    settings_base.write_text(updated, encoding="utf-8")
+    return True
+
+
+def remove_generated_docker_files(root: Path) -> list[str]:
+    """Remove Wagtail start Dockerfile artifacts (template consumes GHCR)."""
+    removed: list[str] = []
+    for name in ("Dockerfile", ".dockerignore"):
+        path = root / name
+        if path.is_file():
+            path.unlink()
+            removed.append(name)
+    return removed
+
+
+def default_config_document(project_name: str) -> dict[str, Any]:
+    """Return a new create-wagtail-config.json document."""
+    return {
+        "$schema": "./create-wagtail-config.schema.json",
+        "projectName": project_name,
+        "composeProjectName": "xgic-wagtail",
+        "dbAdapter": DEFAULT_DB_ADAPTER,
+        "dbName": "wagtail",
+        "dbUser": "wagtail",
+    }
+
+
+def ensure_config_file(
+    path: Path = DEFAULT_CONFIG_FILE,
+    *,
+    project_name: str | None = None,
+) -> bool:
+    """Write create-wagtail-config.json when missing. Return True if written."""
+    if path.is_file():
+        return False
+    name = project_name or get_project_name()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(
+        json.dumps(default_config_document(name), indent=2) + "\n",
+        encoding="utf-8",
+    )
+    return True
+
+
+def run_wagtail_start(project_name: str, dest: Path) -> int:
+    """Run ``wagtail start <name> .`` in *dest*. Return process exit code."""
+    exe = shutil.which("wagtail")
+    if exe is None:
+        print_warning(
+            "wagtail is not on PATH. Reopen in the Dev Container image "
+            "(ghcr.io/xgic/wagtail-dev) or install Wagtail 8.0."
+        )
+        return 1
+    result = subprocess.run(
+        [exe, "start", project_name, "."],
+        cwd=str(dest),
+        check=False,
+    )
+    return int(result.returncode)
+
+
+def ensure_wagtail_project(
+    *,
+    quiet: bool = False,
+    root: Path | None = None,
+) -> int:
+    """Idempotent first-run: config, env, wagtail start, PostgreSQL settings."""
+    base = Path.cwd() if root is None else root
+    orig = Path.cwd()
+    os.chdir(base)
+    try:
+        return _ensure_wagtail_project(quiet=quiet, root=base)
+    finally:
+        os.chdir(orig)
+
+
+def _ensure_wagtail_project(*, quiet: bool, root: Path) -> int:
+    cfg = load_create_wagtail_config(root / DEFAULT_CONFIG_FILE)
+    adapter = get_db_adapter(cfg)
+    if adapter not in ALLOWED_DB_ADAPTERS:
+        print_warning(
+            f"dbAdapter {adapter!r} is not supported. "
+            "XGIC default is PostgreSQL (set dbAdapter to 'postgres')."
+        )
+        return 1
+
+    project_name = get_project_name(cfg)
+    wrote_schema = False
+    schema_path = root / DEFAULT_SCHEMA_FILE
+    if not schema_path.is_file():
+        write_schema(schema_path)
+        wrote_schema = True
+    wrote_config = ensure_config_file(
+        root / DEFAULT_CONFIG_FILE,
+        project_name=project_name,
+    )
+    wrote_env = ensure_devcontainer_env(
+        config_path=root / DEFAULT_CONFIG_FILE,
+        env_file=root / ".devcontainer" / ".env",
+    )
+    if not quiet:
+        if wrote_schema:
+            print_info(f"Wrote {DEFAULT_SCHEMA_FILE}")
+        if wrote_config:
+            print_info(f"Wrote {DEFAULT_CONFIG_FILE}")
+        if wrote_env:
+            print_info("Wrote .devcontainer/.env (Compose Postgres credentials)")
+
+    if is_wagtail_project_complete(root):
+        settings_base = find_settings_base(root)
+        changed = patch_settings_base(settings_base) if settings_base else False
+        if not quiet:
+            if changed:
+                print_success("Django DATABASES now use Compose PostgreSQL.")
+            else:
+                print_success("Wagtail project already present (PostgreSQL settings).")
+        return 0
+
+    if not quiet:
+        print_info(f"Running: wagtail start {project_name} .")
+    rc = run_wagtail_start(project_name, root)
+    if rc != 0:
+        return rc
+
+    removed = remove_generated_docker_files(root)
+    if removed and not quiet:
+        print_info(
+            "Removed generated "
+            + ", ".join(removed)
+            + " (template consumes ghcr.io/xgic/wagtail-dev)."
+        )
+
+    settings_base = find_settings_base(root)
+    if settings_base is None:
+        print_warning("wagtail start finished but settings/base.py was not found.")
+        return 1
+    patch_settings_base(settings_base)
+    if not quiet:
+        print_success(
+            "Wagtail site scaffolded with PostgreSQL "
+            "(POSTGRES_HOST=postgres). Next: python manage.py migrate"
+        )
+    return 0

xgic/cli/wagtail/schema.py

@@ -0,0 +1,62 @@
+"""JSON Schema for ``create-wagtail-config.json`` (editor IntelliSense)."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from xgic.cli.wagtail.config import DEFAULT_SCHEMA_FILE
+
+WAGTAIL_CONFIG_SCHEMA: dict[str, object] = {
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "title": "XGIC Wagtail create-wagtail-config",
+    "description": (
+        "Workspace config for xgic wagtail setup. "
+        "XGIC default database is PostgreSQL. SQLite is not supported."
+    ),
+    "type": "object",
+    "additionalProperties": False,
+    "required": ["projectName", "dbAdapter"],
+    "properties": {
+        "$schema": {"type": "string"},
+        "projectName": {
+            "type": "string",
+            "pattern": "^[A-Za-z][A-Za-z0-9_]*$",
+            "description": (
+                "Django project package name passed to `wagtail start` "
+                "(letters, digits, underscore)."
+            ),
+            "examples": ["mysite", "website"],
+        },
+        "composeProjectName": {
+            "type": "string",
+            "pattern": "^[a-z0-9][a-z0-9_-]{0,62}$",
+            "description": "Docker Compose project name for this workspace.",
+            "examples": ["xgic-wagtail"],
+        },
+        "dbAdapter": {
+            "type": "string",
+            "enum": ["postgres"],
+            "description": "Database adapter. XGIC default and only supported value is postgres.",
+        },
+        "dbName": {
+            "type": "string",
+            "minLength": 1,
+            "description": "PostgreSQL database name (Compose POSTGRES_DB).",
+            "examples": ["wagtail"],
+        },
+        "dbUser": {
+            "type": "string",
+            "minLength": 1,
+            "description": "PostgreSQL role (Compose POSTGRES_USER / PGUSER).",
+            "examples": ["wagtail"],
+        },
+    },
+}
+
+
+def write_schema(path: Path = DEFAULT_SCHEMA_FILE) -> Path:
+    """Write the schema JSON file and return the path."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(WAGTAIL_CONFIG_SCHEMA, indent=2) + "\n", encoding="utf-8")
+    return path

xgic_wagtail_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,148 @@
+Metadata-Version: 2.5
+Name: xgic-wagtail-cli
+Version: 0.1.0
+Summary: XGIC CLI Wagtail module - Wagtail product commands (xgic.cli.wagtail).
+Project-URL: Homepage, https://github.com/xgic/wagtail-cli
+Project-URL: Repository, https://github.com/xgic/wagtail-cli
+Project-URL: Issues, https://github.com/xgic/wagtail-cli/issues
+Project-URL: Documentation, https://github.com/xgic/wagtail-cli#readme
+Project-URL: Changelog, https://github.com/xgic/wagtail-cli/releases
+Author: XGIC
+License: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Keywords: cli,cms,django,wagtail,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.1
+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 Wagtail CLI
+
+[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
+[![CI](https://github.com/xgic/wagtail-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/xgic/wagtail-cli/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/xgic-wagtail-cli.svg)](https://pypi.org/project/xgic-wagtail-cli/)
+[![Python](https://img.shields.io/badge/python-3.14+-blue?logo=python&logoColor=white)](https://www.python.org/)
+[![Release](https://img.shields.io/github/v/release/xgic/wagtail-cli?include_prereleases)](https://github.com/xgic/wagtail-cli/releases)
+[![Producer](https://img.shields.io/github/v/release/xgic/wagtail-dev?label=wagtail-dev)](https://github.com/xgic/wagtail-dev/releases)
+[![GHCR image](https://img.shields.io/badge/GHCR-wagtail--dev-blue?logo=github)](https://github.com/users/xgic/packages/container/package/wagtail-dev)
+
+**Wagtail product commands for the modular [XGIC CLI](https://github.com/xgic/cli)—ops under
+`xgic wagtail …`.**
+
+Namespace: **`xgic.cli.wagtail`** · Console group: **`xgic wagtail …`** · Brand: **XGIC CLI only**
+([ADR-0005](https://github.com/xgic/ai/blob/main/docs/adr/0005-modular-xgic-cli-and-retirement-of-xde.md))
+
+Standards hub: [xgic/ai](https://github.com/xgic/ai) ·
+[README standards](https://github.com/xgic/ai/blob/main/docs/readme-standards.md) ·
+Default CMS: [ADR-0006](https://github.com/xgic/ai/blob/main/docs/adr/0006-adopt-wagtail.md)
+
+---
+
+## Vision
+
+Wagtail is the default CMS for new XGIC work. This module owns the **Wagtail product**
+namespace under `xgic` so humans and agents share one command map. The thin site
+template lives in [xgic/wagtail](https://github.com/xgic/wagtail); the Dev Container
+**producer** (`ghcr.io/xgic/wagtail-dev`) lives in [xgic/wagtail-dev](https://github.com/xgic/wagtail-dev).
+
+---
+
+## Why this module exists
+
+| Benefit | Detail |
+|---------|--------|
+| **Domain clarity** | Nested under `xgic wagtail`—no clash with core or other CMS modules |
+| **Composable stack** | Depends on `xgic-cli` only |
+| **Usage UX** | Missing ACTION prints **full usage**, matching top-level `xgic` |
+| **AI + human parity** | Same command map in README and [AGENTS.md](AGENTS.md) |
+| **Open-source rigor** | Apache-2.0, Python 3.14+, RC → TestPyPI → PyPI |
+
+---
+
+## Ecosystem
+
+| Package / repo | Role |
+|----------------|------|
+| [xgic/cli](https://github.com/xgic/cli) | Thin core framework (`xgic`) |
+| **This repo** | Wagtail product module (`xgic.cli.wagtail`) |
+| [xgic/wagtail-dev](https://github.com/xgic/wagtail-dev) | Official image pins + contributor Compose |
+| [xgic/wagtail](https://github.com/xgic/wagtail) | End-user site **template** |
+
+Architecture: [ADR-0001](https://github.com/xgic/ai/blob/main/docs/adr/0001-xgic-gitlab-architecture-and-repository-naming.md)
+· [ADR-0005](https://github.com/xgic/ai/blob/main/docs/adr/0005-modular-xgic-cli-and-retirement-of-xde.md)
+· [ADR-0006](https://github.com/xgic/ai/blob/main/docs/adr/0006-adopt-wagtail.md).
+
+---
+
+## Quick start
+
+### Development (editable)
+
+```bash
+uv pip install -e ../cli
+uv pip install -e ".[dev]"
+xgic wagtail
+xgic wagtail info
+xgic wagtail setup
+xgic wagtail dev
+```
+
+`xgic wagtail` with no action prints full usage and exits `2`.
+`xgic wagtail dev` waits for PostgreSQL, runs `migrate --noinput`, then
+`python manage.py runserver 0.0.0.0:8000`. Requires a site from `setup`.
+`xgic wagtail setup` is idempotent: config JSON, Compose `.env`, `wagtail start` when missing, Django `DATABASES` on **PostgreSQL**, and `django.contrib.postgres` in the generated `<project>/settings/base.py` `INSTALLED_APPS` (immediately before `django.contrib.admin`, for Wagtail search `SearchVectorField` / `GinIndex`). SQLite is not an XGIC default. The thin GitHub template does not vendor that settings file.
+
+### Install (PyPI)
+
+```bash
+uv pip install "xgic-cli>=0.2.1" "xgic-wagtail-cli>=0.1.0"
+xgic wagtail --help
+xgic wagtail info
+xgic wagtail setup
+xgic wagtail dev
+```
+
+PyPI publish follows the hub
+[python-package-release.md](https://github.com/xgic/ai/blob/main/docs/python-package-release.md)
+path (RC → TestPyPI → PyPI).
+
+---
+
+## Commands
+
+| Command | Purpose |
+|---------|---------|
+| `xgic wagtail` | Full usage (missing ACTION) |
+| `xgic wagtail info` | Module identity (`--json` for machine output) |
+| `xgic wagtail setup [--quiet]` | First-run: config JSON, `.devcontainer/.env`, `wagtail start` if needed, PostgreSQL `DATABASES` + `django.contrib.postgres` in generated `settings/base.py` |
+| `xgic wagtail schema [--output PATH]` | Write JSON Schema for `create-wagtail-config.json` (IntelliSense) |
+| `xgic wagtail --help` | Same usage listing |
+
+`dbAdapter` is **postgres** only. Dev-server helpers remain planned.
+
+---
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). Human review in the GitHub UI before merge.
+Labels required. Public-safe content only.
+
+## License
+
+Apache License 2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE).

xgic_wagtail_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+xgic/cli/wagtail/__init__.py,sha256=FBXwZDIZ16Iaug4upMCvRueghYG8TuhemkD6LgC2F6c,104
+xgic/cli/wagtail/config.py,sha256=IkeKgRi87ER0mzAkKfSoa3VB8pn4HmaLxxpIUhwDQEU,4088
+xgic/cli/wagtail/env_helpers.py,sha256=HD5v3kF2M4t8V8g1cJf_hwnqHIUKTEoSZYkmMU_cC2I,2159
+xgic/cli/wagtail/plugin.py,sha256=pCV4rJdpGSupPzUTKoyNpKYJaZFoOFPQuxQVBniuxhI,2387
+xgic/cli/wagtail/project.py,sha256=J0rnhtWcCCJdLf28Jx71qXwCtoKMdd-0tCKXy7e8RbQ,8955
+xgic/cli/wagtail/schema.py,sha256=e_U5ZJXaYN01lwpRiTS8bOm-rx-7G0gKTu7hrdWfOPA,2144
+xgic/cli/wagtail/commands/__init__.py,sha256=bH-Z7dLseNZPFZ1mWCufp6zZWX6-Kz0lDL66BqQn0Fs,36
+xgic/cli/wagtail/commands/dev.py,sha256=QzLjVmlPfD5PN4MfrHMIPBorw4X_3A-mQHEUKnxJSDs,2976
+xgic/cli/wagtail/commands/info.py,sha256=t69q4tHIkck6Rpr-we53CcIEC5vznlNsKmhUTm1-TPs,1157
+xgic/cli/wagtail/commands/schema.py,sha256=XlehTr9V8VS90SEQ5T6977sGhnalKLk2SJmvYeR6MkM,807
+xgic/cli/wagtail/commands/setup.py,sha256=a825GWjsabUiCNXJ-BrfJ_1WNCOfz6OSUjqN5u65zQ0,417
+xgic_wagtail_cli-0.1.0.dist-info/METADATA,sha256=TSUngguJwMUPm0Te079D3g1WaHs4Esq3fUGqIFiwxRA,6332
+xgic_wagtail_cli-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+xgic_wagtail_cli-0.1.0.dist-info/entry_points.txt,sha256=gS09xQPHkyNcE2gtUSWFta-prxSvNfXzx9ziOz7q5bE,63
+xgic_wagtail_cli-0.1.0.dist-info/licenses/LICENSE,sha256=zR7vJ5cGf_9LgWHYDAugptsXPsV0_78I9kvVnf7VRk0,11335
+xgic_wagtail_cli-0.1.0.dist-info/licenses/NOTICE,sha256=0WFLslt_X2suv9rdABKWpPjeT_GpvOS5mQBp83423eY,208
+xgic_wagtail_cli-0.1.0.dist-info/RECORD,,

xgic_wagtail_cli-0.1.0.dist-info/WHEEL

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

xgic_wagtail_cli-0.1.0.dist-info/entry_points.txt

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

xgic_wagtail_cli-0.1.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_wagtail_cli-0.1.0.dist-info/licenses/NOTICE

@@ -0,0 +1,8 @@
+XGIC Wagtail 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.