xgic-payload-cms-cli 0.2.0__tar.gz → 0.2.1__tar.gz

xgic_payload_cms_cli-0.2.1/PKG-INFO

@@ -0,0 +1,222 @@
+Metadata-Version: 2.5
+Name: xgic-payload-cms-cli
+Version: 0.2.1
+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)](LICENSE)
+[![PyPI](https://img.shields.io/pypi/v/xgic-payload-cms-cli.svg)](https://pypi.org/project/xgic-payload-cms-cli/)
+[![Python](https://img.shields.io/pypi/pyversions/xgic-payload-cms-cli.svg)](https://pypi.org/project/xgic-payload-cms-cli/)
+[![CI](https://github.com/xgic/payload-cms-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/xgic/payload-cms-cli/actions/workflows/ci.yml)
+[![Release](https://img.shields.io/github/v/release/xgic/payload-cms-cli)](https://github.com/xgic/payload-cms-cli/releases)
+[![Producer](https://img.shields.io/github/v/release/xgic/payload-cms-dev?label=payload-cms-dev)](https://github.com/xgic/payload-cms-dev/releases)
+
+**Payload CMS product commands for the modular [XGIC CLI](https://github.com/xgic/cli).**
+
+Namespace: **`xgic.cli.payload`** · Console group: **`xgic payload …`** · 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)
+
+---
+
+## Vision
+
+Payload application teams—and the AI agents that help them—need a **small, stable command surface** for project ensure, environment status, smart dev start, and safe reset. This module owns that **product** surface. Generic Compose lifecycle stays in [dev-cli](https://github.com/xgic/dev-cli); the Dev Container **image** is built in [payload-cms-dev](https://github.com/xgic/payload-cms-dev); applications start from [payload-cms](https://github.com/xgic/payload-cms).
+
+One brand (`xgic`), clear ownership, and dry-run-friendly destructive paths.
+
+---
+
+## Why this module exists
+
+| Benefit | Detail |
+|---------|--------|
+| **Domain clarity** | Nested under `xgic payload`—no clash with generic `xgic up` / `down` |
+| **AI + human parity** | Same commands in READMEs and [AGENTS.md](AGENTS.md) |
+| **Safe operations** | Reset and regenerate paths support explicit confirmation / dry-run patterns |
+| **Composable stack** | Depends on `xgic-cli` + `xgic-dev-cli`; ships on PyPI for image and host installs |
+| **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`) |
+| [xgic/dev-cli](https://github.com/xgic/dev-cli) | Dev Container / Docker Compose lifecycle |
+| **This repo** | Payload CMS product module (`xgic.cli.payload`) |
+| [xgic/payload-cms-dev](https://github.com/xgic/payload-cms-dev) | Dev Container **image producer** (`ghcr.io/xgic/payload-cms-dev`) |
+| [xgic/payload-cms](https://github.com/xgic/payload-cms) | End-user **template** (recommended app start) |
+
+---
+
+## Quick start
+
+### Install (PyPI)
+
+```bash
+uv pip install \
+  "xgic-cli>=0.2.0,<0.3" \
+  "xgic-dev-cli>=0.2.0,<0.3" \
+  "xgic-payload-cms-cli>=0.2.1,<0.3"
+xgic payload --help
+```
+
+### Development (editable)
+
+```bash
+uv pip install -e ../cli
+uv pip install -e ../dev-cli
+uv pip install -e ".[dev]"
+xgic payload --help
+```
+
+### Typical Payload session (inside a Dev Container)
+
+```bash
+xgic check
+xgic payload env --regenerate --yes   # once
+xgic payload setup                    # scaffold app (layout from config)
+xgic up --profile postgres            # DB if needed
+xgic payload dev
+```
+
+Prefer the end-user template for application work: [payload-cms](https://github.com/xgic/payload-cms).
+
+---
+
+## Console commands
+
+All product commands nest under **`xgic payload`**:
+
+| Command | Purpose |
+|---------|---------|
+| `xgic payload dev` | **Primary daily command** — smart start (up if needed, DB check, `pnpm dev`) |
+| `xgic payload setup [--quiet]` | Ensure Payload project directory (idempotent) |
+| `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 + active DB volume) |
+
+**Generic lifecycle** (`xgic up` / `down` / `check` / `env`) lives in **dev-cli**. Use **`xgic payload env`** for Payload credentials and product status.
+
+### Setup: automatic vs manual
+
+| Mode | Guidance |
+|------|----------|
+| **Automatic** | Producer/image `postStart` may call `xgic payload setup` via a thin shell wrapper (idempotent). |
+| **Manual / testing** | After `xgic payload reset --yes`, or when validating scaffold config—not a “daily” app ritual. |
+
+Always prefer **`xgic payload reset --dry-run`** before destructive reset.
+
+### Historical command map (`xde` → XGIC CLI)
+
+Living brand is **XGIC CLI only**. Historical map for agents migrating old notes:
+
+| Historical (`xde`) | XGIC CLI |
+|--------------------|----------|
+| `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,
+)
+```
+
+---
+
+## Requirements
+
+- Python **3.14+**
+- `xgic-cli` ≥ 0.2.0
+- `xgic-dev-cli` ≥ 0.2.0
+
+---
+
+## Publishing
+
+Follow [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.
+
+---
+
+## Working with AI assistants
+
+High-signal prompts:
+
+- “Run `xgic payload env` (no secrets) and recommend whether to start Postgres.”  
+- “Start with `xgic payload dev` and report the listen URL.”  
+- “Show `xgic payload reset --dry-run` before any reset.”  
+
+Ownership:
+
+| Change | Repository |
+|--------|------------|
+| `xgic payload …` behavior | **This repo** |
+| `xgic up` / `down` / `check` | [dev-cli](https://github.com/xgic/dev-cli) |
+| Image / Dockerfile | [payload-cms-dev](https://github.com/xgic/payload-cms-dev) |
+| App template pin / docs | [payload-cms](https://github.com/xgic/payload-cms) |
+
+Public-safe gate: [BASE-STANDARDS](https://github.com/xgic/ai/blob/main/docs/BASE-STANDARDS-FOR-ORCHESTRATED-REPOS.md).
+
+---
+
+## Contributing
+
+PRs with human UI review only. Conventional Commits; labels required. See [CONTRIBUTING.md](CONTRIBUTING.md) and [AGENTS.md](AGENTS.md).
+
+---
+
+## License
+
+Apache License 2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE).  
+Copyright form: `Copyright 2026 XGIC`.
+
+---
+
+**XGIC** — Modular CLI for open-source platforms: thin core, domain modules, and AI-operable Payload workflows.

xgic_payload_cms_cli-0.2.1/README.md

@@ -0,0 +1,187 @@
+# XGIC Payload CMS CLI
+
+[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
+[![PyPI](https://img.shields.io/pypi/v/xgic-payload-cms-cli.svg)](https://pypi.org/project/xgic-payload-cms-cli/)
+[![Python](https://img.shields.io/pypi/pyversions/xgic-payload-cms-cli.svg)](https://pypi.org/project/xgic-payload-cms-cli/)
+[![CI](https://github.com/xgic/payload-cms-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/xgic/payload-cms-cli/actions/workflows/ci.yml)
+[![Release](https://img.shields.io/github/v/release/xgic/payload-cms-cli)](https://github.com/xgic/payload-cms-cli/releases)
+[![Producer](https://img.shields.io/github/v/release/xgic/payload-cms-dev?label=payload-cms-dev)](https://github.com/xgic/payload-cms-dev/releases)
+
+**Payload CMS product commands for the modular [XGIC CLI](https://github.com/xgic/cli).**
+
+Namespace: **`xgic.cli.payload`** · Console group: **`xgic payload …`** · 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)
+
+---
+
+## Vision
+
+Payload application teams—and the AI agents that help them—need a **small, stable command surface** for project ensure, environment status, smart dev start, and safe reset. This module owns that **product** surface. Generic Compose lifecycle stays in [dev-cli](https://github.com/xgic/dev-cli); the Dev Container **image** is built in [payload-cms-dev](https://github.com/xgic/payload-cms-dev); applications start from [payload-cms](https://github.com/xgic/payload-cms).
+
+One brand (`xgic`), clear ownership, and dry-run-friendly destructive paths.
+
+---
+
+## Why this module exists
+
+| Benefit | Detail |
+|---------|--------|
+| **Domain clarity** | Nested under `xgic payload`—no clash with generic `xgic up` / `down` |
+| **AI + human parity** | Same commands in READMEs and [AGENTS.md](AGENTS.md) |
+| **Safe operations** | Reset and regenerate paths support explicit confirmation / dry-run patterns |
+| **Composable stack** | Depends on `xgic-cli` + `xgic-dev-cli`; ships on PyPI for image and host installs |
+| **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`) |
+| [xgic/dev-cli](https://github.com/xgic/dev-cli) | Dev Container / Docker Compose lifecycle |
+| **This repo** | Payload CMS product module (`xgic.cli.payload`) |
+| [xgic/payload-cms-dev](https://github.com/xgic/payload-cms-dev) | Dev Container **image producer** (`ghcr.io/xgic/payload-cms-dev`) |
+| [xgic/payload-cms](https://github.com/xgic/payload-cms) | End-user **template** (recommended app start) |
+
+---
+
+## Quick start
+
+### Install (PyPI)
+
+```bash
+uv pip install \
+  "xgic-cli>=0.2.0,<0.3" \
+  "xgic-dev-cli>=0.2.0,<0.3" \
+  "xgic-payload-cms-cli>=0.2.1,<0.3"
+xgic payload --help
+```
+
+### Development (editable)
+
+```bash
+uv pip install -e ../cli
+uv pip install -e ../dev-cli
+uv pip install -e ".[dev]"
+xgic payload --help
+```
+
+### Typical Payload session (inside a Dev Container)
+
+```bash
+xgic check
+xgic payload env --regenerate --yes   # once
+xgic payload setup                    # scaffold app (layout from config)
+xgic up --profile postgres            # DB if needed
+xgic payload dev
+```
+
+Prefer the end-user template for application work: [payload-cms](https://github.com/xgic/payload-cms).
+
+---
+
+## Console commands
+
+All product commands nest under **`xgic payload`**:
+
+| Command | Purpose |
+|---------|---------|
+| `xgic payload dev` | **Primary daily command** — smart start (up if needed, DB check, `pnpm dev`) |
+| `xgic payload setup [--quiet]` | Ensure Payload project directory (idempotent) |
+| `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 + active DB volume) |
+
+**Generic lifecycle** (`xgic up` / `down` / `check` / `env`) lives in **dev-cli**. Use **`xgic payload env`** for Payload credentials and product status.
+
+### Setup: automatic vs manual
+
+| Mode | Guidance |
+|------|----------|
+| **Automatic** | Producer/image `postStart` may call `xgic payload setup` via a thin shell wrapper (idempotent). |
+| **Manual / testing** | After `xgic payload reset --yes`, or when validating scaffold config—not a “daily” app ritual. |
+
+Always prefer **`xgic payload reset --dry-run`** before destructive reset.
+
+### Historical command map (`xde` → XGIC CLI)
+
+Living brand is **XGIC CLI only**. Historical map for agents migrating old notes:
+
+| Historical (`xde`) | XGIC CLI |
+|--------------------|----------|
+| `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,
+)
+```
+
+---
+
+## Requirements
+
+- Python **3.14+**
+- `xgic-cli` ≥ 0.2.0
+- `xgic-dev-cli` ≥ 0.2.0
+
+---
+
+## Publishing
+
+Follow [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.
+
+---
+
+## Working with AI assistants
+
+High-signal prompts:
+
+- “Run `xgic payload env` (no secrets) and recommend whether to start Postgres.”  
+- “Start with `xgic payload dev` and report the listen URL.”  
+- “Show `xgic payload reset --dry-run` before any reset.”  
+
+Ownership:
+
+| Change | Repository |
+|--------|------------|
+| `xgic payload …` behavior | **This repo** |
+| `xgic up` / `down` / `check` | [dev-cli](https://github.com/xgic/dev-cli) |
+| Image / Dockerfile | [payload-cms-dev](https://github.com/xgic/payload-cms-dev) |
+| App template pin / docs | [payload-cms](https://github.com/xgic/payload-cms) |
+
+Public-safe gate: [BASE-STANDARDS](https://github.com/xgic/ai/blob/main/docs/BASE-STANDARDS-FOR-ORCHESTRATED-REPOS.md).
+
+---
+
+## Contributing
+
+PRs with human UI review only. Conventional Commits; labels required. See [CONTRIBUTING.md](CONTRIBUTING.md) and [AGENTS.md](AGENTS.md).
+
+---
+
+## License
+
+Apache License 2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE).  
+Copyright form: `Copyright 2026 XGIC`.
+
+---
+
+**XGIC** — Modular CLI for open-source platforms: thin core, domain modules, and AI-operable Payload workflows.

{xgic_payload_cms_cli-0.2.0 → xgic_payload_cms_cli-0.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "xgic-payload-cms-cli"
-version = "0.2.0"
+version = "0.2.1"
 description = "XGIC CLI Payload CMS module - product commands and helpers (xgic.cli.payload)."
 readme = "README.md"
 license = { text = "Apache-2.0" }

xgic_payload_cms_cli-0.2.1/src/xgic/cli/payload/commands/dev.py

@@ -0,0 +1,137 @@
+"""``xgic payload dev`` — smart Payload CMS development server start."""
+
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+from xgic.cli.app import CommandContext
+from xgic.cli.core.environment import EnvironmentType
+from xgic.cli.payload.config import (
+    DEFAULT_COMPOSE_PROJECT,
+    DEFAULT_PRIMARY_SERVICE,
+    db_ready,
+    get_db_profile,
+    make_payload_docker_controller,
+)
+from xgic.cli.payload.layout import display_project_location, resolve_project_dir
+from xgic.cli.payload.project import (
+    ensure_db_services,
+    is_payload_project_complete,
+    load_create_payload_config,
+)
+from xgic.cli.utils.output import print_info, print_success, print_warning
+
+
+def _app_cwd(project_dir: Path) -> Path:
+    if project_dir == Path("."):
+        return Path.cwd()
+    return (Path.cwd() / project_dir).resolve()
+
+
+def run_dev(ctx: CommandContext) -> int:
+    """Start DB if needed and launch the Payload CMS app dev server."""
+    env = ctx.env
+    cfg = load_create_payload_config()
+    project_dir = resolve_project_dir(cfg)
+
+    if not is_payload_project_complete(project_dir):
+        print_warning(
+            "Payload CMS app is not set up yet at "
+            f"{display_project_location(project_dir)}."
+        )
+        print_info("Run first:  xgic payload env --regenerate --yes")
+        print_info("Then:       xgic payload setup")
+        print_info("Then:       xgic payload dev")
+        return 1
+
+    print_info("Starting Payload CMS development server...")
+    print_info(f"App location: {display_project_location(project_dir)}")
+
+    docker = make_payload_docker_controller(env)
+    docker.project_name = DEFAULT_COMPOSE_PROJECT
+    profile = get_db_profile()
+
+    # Never recreate the primary Dev Container service; only ensure DB.
+    if not db_ready(docker):
+        print_warning(
+            f"Database ({profile}) not ready. Starting DB service only..."
+        )
+        db_rc = ensure_db_services(quiet=False)
+        if db_rc != 0:
+            print_warning(
+                "Could not start database. Fix Compose/DB, then re-run "
+                "xgic payload dev."
+            )
+            return db_rc
+    else:
+        print_success("Database is ready")
+
+    app_cwd = _app_cwd(project_dir)
+    if not (app_cwd / "package.json").is_file():
+        print_warning(f"No package.json under {app_cwd}")
+        return 1
+
+    if env.env_type in (
+        EnvironmentType.DEV_CONTAINER,
+        EnvironmentType.GENERIC_CONTAINER,
+    ):
+        try:
+            print_info(f"Launching pnpm dev in {app_cwd}...")
+            result = subprocess.run(
+                ["sh", "-c", 'trap "exit 0" INT TERM; exec pnpm dev'],
+                cwd=str(app_cwd),
+                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 {display_project_location(project_dir)} "
+                    "&& pnpm dev"
+                )
+                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
+        except FileNotFoundError:
+            print_warning(
+                "pnpm not found. Run inside the Dev Container image "
+                "(or install pnpm on PATH)."
+            )
+            return 1
+
+    # Host: try docker exec into primary service (optional path)
+    rel = (
+        "."
+        if project_dir == Path(".")
+        else project_dir.as_posix().strip("/")
+    )
+    try:
+        print_info(
+            f"Launching pnpm dev via container service "
+            f"{DEFAULT_PRIMARY_SERVICE!r}..."
+        )
+        docker.exec(
+            DEFAULT_PRIMARY_SERVICE,
+            "sh",
+            "-c",
+            f"cd /workspace/{rel} && "
+            "sh -c 'trap \"exit 0\" INT TERM; exec pnpm dev'",
+            check=False,
+        )
+    except Exception as e:
+        print_warning(f"Failed to launch pnpm dev from host: {e}")
+        print_info(
+            "Prefer: Dev Containers → Reopen in Container, then "
+            "xgic payload dev"
+        )
+        return 1
+
+    print_success("Environment ready for development.")
+    print_info("Environment context: " + env.describe())
+    return 0

{xgic_payload_cms_cli-0.2.0 → xgic_payload_cms_cli-0.2.1}/src/xgic/cli/payload/commands/payload_env.py

@@ -57,9 +57,9 @@ def run_payload_env(ctx: CommandContext) -> int:
             "(use: xgic payload env --regenerate --yes)"
         )
     if services_ok:
-        print_success("Compose services: appear to be running")
+        print_success("Docker Compose services: appear to be running")
     else:
-        print_info("Compose services: not detected as running")
+        print_info("Docker 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_payload_cms_cli-0.2.0 → xgic_payload_cms_cli-0.2.1}/src/xgic/cli/payload/config.py

@@ -13,8 +13,9 @@ 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"
+# Match producer + thin template Compose service names (not legacy *-dev-containers).
+DEFAULT_COMPOSE_PROJECT = "xgic-payload-cms-dev"
+DEFAULT_PRIMARY_SERVICE = "xgic-payload-cms-dev"
 DEFAULT_CONFIG_FILE = Path(".devcontainer/create-payload-config.json")
 DEFAULT_COMPOSE_FILE = ".devcontainer/docker-compose.yml"
 
@@ -22,7 +23,7 @@ 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."""
+    """Return projectName identity (npm/display; not always the filesystem path)."""
     if config_file.exists():
         try:
             with open(config_file, encoding="utf-8") as f:
@@ -34,6 +35,16 @@ def get_payload_project_name(
     return "my-payload-cms"
 
 
+def get_payload_project_dir(
+    config_file: Path = DEFAULT_CONFIG_FILE,
+) -> Path:
+    """Return resolved app directory Path (see layout.resolve_project_dir)."""
+    from xgic.cli.payload.layout import resolve_project_dir
+    from xgic.cli.payload.project import load_create_payload_config
+
+    return resolve_project_dir(load_create_payload_config(config_file))
+
+
 def get_db_config(
     config_file: Path = DEFAULT_CONFIG_FILE,
 ) -> tuple[str, str]:
@@ -86,7 +97,7 @@ def get_db_profile(config_file: Path = DEFAULT_CONFIG_FILE) -> str:
 def make_payload_docker_controller(
     env: EnvironmentContext,
 ) -> DockerComposeController:
-    """Build a Compose controller with Payload CMS template defaults."""
+    """Build a Docker Compose controller with Payload CMS template defaults."""
     return DockerComposeController(
         env=env,
         compose_file=DEFAULT_COMPOSE_FILE,