codex-django-cli 0.2.0__tar.gz

codex_django_cli-0.2.0/.gitignore

@@ -0,0 +1,12 @@
+.venv/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.uv-cache/
+build/
+dist/
+site/
+coverage.xml
+.coverage
+__pycache__/
+*.py[cod]

codex_django_cli-0.2.0/PKG-INFO

@@ -0,0 +1,66 @@
+Metadata-Version: 2.4
+Name: codex-django-cli
+Version: 0.2.0
+Summary: Standalone CLI and blueprint scaffolding package for codex-django
+Project-URL: Homepage, https://github.com/codexdlc/codex-django-cli
+Project-URL: Documentation, https://codexdlc.github.io/codex-django-cli/
+Project-URL: Repository, https://github.com/codexdlc/codex-django-cli
+Project-URL: Issues, https://github.com/codexdlc/codex-django/issues
+Author: CodexDLC
+License: Apache-2.0
+Keywords: blueprints,cli,codex,django,scaffold
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.12
+Requires-Dist: jinja2>=3.1
+Requires-Dist: questionary>=2.0.0
+Requires-Dist: rich>=13.0
+Provides-Extra: dev
+Requires-Dist: bandit>=1.7; extra == 'dev'
+Requires-Dist: codex-core<0.3.0,>=0.2.2; extra == 'dev'
+Requires-Dist: detect-secrets>=1.5; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pip-audit>=2.7; extra == 'dev'
+Requires-Dist: pre-commit>=3.0; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mike>=2.0; extra == 'docs'
+Requires-Dist: mkdocs-include-markdown-plugin; extra == 'docs'
+Requires-Dist: mkdocs-material>=9.0; extra == 'docs'
+Requires-Dist: mkdocs>=1.5; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.24; extra == 'docs'
+Description-Content-Type: text/markdown
+
+# codex-django-cli
+
+Standalone CLI package for `codex-django`.
+
+It owns the interactive `codex-django` command, blueprint rendering engine, scaffold commands, and CLI-focused tests/docs. The generated project code may still import `codex_django.*` runtime modules from `codex-django`; that compatibility is intentional.
+
+## Install
+
+```bash
+pip install codex-django-cli
+```
+
+For local development alongside the sibling runtime repository:
+
+```bash
+uv sync --extra dev
+uv run pytest tests/unit/cli tests/integration/cli
+uv build --no-sources
+```
+
+## Scope
+
+- `codex_django_cli.main`: entrypoint and menu flow
+- `codex_django_cli.engine`: blueprint rendering and file generation
+- `codex_django_cli.commands.*`: scaffold/init/deploy helpers
+- `codex_django_cli.blueprints`: packaged templates, static files, and scaffold assets
+
+The runtime library remains in `codex-django`.

codex_django_cli-0.2.0/README.md

@@ -0,0 +1,28 @@
+# codex-django-cli
+
+Standalone CLI package for `codex-django`.
+
+It owns the interactive `codex-django` command, blueprint rendering engine, scaffold commands, and CLI-focused tests/docs. The generated project code may still import `codex_django.*` runtime modules from `codex-django`; that compatibility is intentional.
+
+## Install
+
+```bash
+pip install codex-django-cli
+```
+
+For local development alongside the sibling runtime repository:
+
+```bash
+uv sync --extra dev
+uv run pytest tests/unit/cli tests/integration/cli
+uv build --no-sources
+```
+
+## Scope
+
+- `codex_django_cli.main`: entrypoint and menu flow
+- `codex_django_cli.engine`: blueprint rendering and file generation
+- `codex_django_cli.commands.*`: scaffold/init/deploy helpers
+- `codex_django_cli.blueprints`: packaged templates, static files, and scaffold assets
+
+The runtime library remains in `codex-django`.

codex_django_cli-0.2.0/docs/changelog.md

@@ -0,0 +1 @@
+{% include "../CHANGELOG.md" %}

codex_django_cli-0.2.0/docs/en/api/cli.md

@@ -0,0 +1,21 @@
+<!-- DOC_TYPE: API -->
+
+# CLI Public API
+
+The CLI package provides the interactive `codex-django` entrypoint plus the blueprint-rendering machinery used by scaffold commands.
+
+## Main entrypoints
+
+- `codex_django_cli.main` for launching the interactive CLI.
+- `codex_django_cli.engine.CLIEngine` for lower-level template rendering and scaffold generation.
+- compatibility imports from `codex_django.cli.*` remain available via shim modules in `codex-django`.
+
+## Example
+
+```python
+from codex_django_cli.main import main
+
+raise SystemExit(main())
+```
+
+For prompt helpers, command handlers, and the lower-level scaffold engine modules, open [CLI internals](internal/cli.md).

codex_django_cli-0.2.0/docs/en/api/internal/cli.md

@@ -0,0 +1,25 @@
+<!-- DOC_TYPE: API -->
+
+# CLI Internal Modules
+
+::: codex_django_cli.main
+
+::: codex_django_cli.engine
+
+::: codex_django_cli.prompts
+
+::: codex_django_cli.utils
+
+::: codex_django_cli.commands.add_app
+
+::: codex_django_cli.commands.booking
+
+::: codex_django_cli.commands.client_cabinet
+
+::: codex_django_cli.commands.deploy
+
+::: codex_django_cli.commands.init
+
+::: codex_django_cli.commands.notifications
+
+::: codex_django_cli.commands.quality

codex_django_cli-0.2.0/docs/en/architecture/cli/README.md

@@ -0,0 +1,19 @@
+<!-- DOC_TYPE: INDEX -->
+
+# CLI Architecture
+
+## Pages
+
+- [CLI Module](./module.md)
+- [Entrypoints](./entrypoints.md)
+- [Blueprints](./blueprints.md)
+- [Engine](./engine.md)
+- [Commands](./commands.md)
+- [Project Output](./project-output.md)
+
+## Scope
+
+- How the CLI is entered
+- How it renders blueprints
+- How commands orchestrate scaffolding
+- What structure appears in generated projects

codex_django_cli-0.2.0/docs/en/architecture/cli/blueprints.md

@@ -0,0 +1,153 @@
+<!-- DOC_TYPE: CONCEPT -->
+
+# CLI Blueprints
+
+## Purpose
+
+The `blueprints/` directory is the generation knowledge base of the CLI.
+If `CLIEngine` is the renderer, blueprints are the architectural source material it renders.
+
+They define not only file contents, but also the intended output topology of a generated project.
+Because of that, blueprints are closer to a declarative construction system than to a simple templates folder.
+
+## Why Blueprints Matter
+
+The most important thing about the CLI is not the menu itself.
+It is the fact that project structure, feature additions, and deployment files are all driven from reusable blueprint trees.
+
+This means the CLI architecture is fundamentally template-centric:
+
+- commands choose a blueprint
+- the engine renders it with context
+- the generated tree becomes part of the target project
+
+So understanding the CLI means understanding how blueprints are partitioned.
+
+## Top-Level Blueprint Families
+
+The current blueprint space is split into five main families:
+
+- `repo`
+- `project`
+- `apps`
+- `features`
+- `deploy`
+
+These are not arbitrary folders.
+They correspond to different layers of output responsibility.
+
+### `repo`
+
+`repo/` contains repository-level scaffolding.
+This is the outer shell around a generated project and includes files such as:
+
+- `pyproject.toml`
+- `README.md`
+- `.env.example`
+- `.gitignore`
+- repo-level docs and tools
+
+This layer answers:
+"What files belong to the repository as a whole, regardless of the internal Django app tree?"
+
+### `project`
+
+`project/` contains the base Django project scaffold that lands in `src/<project_name>/`.
+This includes the initial structure for:
+
+- `core`
+- `system`
+- `cabinet`
+- `features`
+- `templates`
+- `static`
+- `manage.py`
+
+This is the central blueprint family because it defines the starting runtime architecture of a fresh codex-django project.
+
+### `apps`
+
+`apps/` contains reusable blueprints for adding a standard feature app to an existing project.
+The current default app blueprint creates a `features/<app_name>/` structure with the expected internal layout for admin, forms, models, services, templates, tests, and views.
+
+This layer answers:
+"How do we add one regular app in the canonical codex-django shape?"
+
+### `features`
+
+`features/` contains advanced or compound feature scaffolds such as:
+
+- `booking`
+- `client_cabinet`
+- `notifications`
+
+These blueprints are more architectural than `apps/default` because they often modify several target areas at once.
+
+For example:
+
+- booking touches `booking/`, `system/`, `cabinet/`, and public templates
+- notifications splits output between a feature area and ARQ infrastructure
+- client cabinet injects both cabinet and system-side code
+
+So `features/` is the layer where the CLI expresses cross-cutting feature bundles rather than isolated apps.
+
+### `deploy`
+
+`deploy/` contains deployment-specific scaffolding such as Docker files.
+This layer is intentionally separated from `project/` because deployment output has a different lifecycle than runtime application code.
+
+It answers:
+"What operational infrastructure should be generated around the project?"
+
+## Architectural Pattern
+
+The blueprint hierarchy reveals an implicit generation model:
+
+1. generate repository shell
+2. generate base project
+3. optionally add cross-cutting features
+4. optionally add standard apps
+5. optionally generate deployment support
+
+This is not just a file-copy pipeline.
+It is a staged project-construction model.
+
+## Jinja And Structural Semantics
+
+Blueprints are not only raw files:
+
+- `.j2` files are rendered with context
+- non-template files are copied as-is
+- folder placement encodes where generated code should live
+
+This means the blueprint tree carries two kinds of meaning at once:
+
+- content semantics: what each file should contain
+- placement semantics: where in the output architecture it belongs
+
+## Runtime Flow
+
+```mermaid
+flowchart TD
+    A["CLI command"] --> B["select blueprint family"]
+    B --> C["CLIEngine.scaffold(...)"]
+    C --> D["walk blueprint tree"]
+    D --> E["render .j2 files with context"]
+    D --> F["copy static files"]
+    E --> G["target project structure"]
+    F --> G
+```
+
+## Role In The CLI
+
+Blueprints are the most durable part of the CLI architecture.
+Menus, commands, and prompts may evolve, but the blueprint families define the long-term contract of what the tool generates.
+
+That is why blueprint documentation is important even if the CLI later becomes its own package:
+the blueprints encode the actual shape of the generated ecosystem.
+
+## See Also
+
+- [CLI module](./module.md)
+- [cabinet overview](../cabinet.md)
+- [booking overview](../booking.md)

codex_django_cli-0.2.0/docs/en/architecture/cli/commands.md

@@ -0,0 +1,157 @@
+<!-- DOC_TYPE: CONCEPT -->
+
+# CLI Commands
+
+## Purpose
+
+The `commands/` package is the orchestration layer of the CLI.
+If `main.py` routes user intent and `CLIEngine` executes rendering, commands translate specific user actions into concrete scaffold operations.
+
+They are not low-level file generators.
+They are scenario handlers.
+
+This means each command answers a high-level question such as:
+
+- how to initialize a new project
+- how to add a standard app
+- how to inject a booking bundle
+- how to scaffold notification infrastructure
+- how to generate deployment files
+
+## Architectural Role
+
+Commands sit between two different worlds:
+
+- the input world of menus, arguments, and user intent
+- the output world of blueprints, generated files, and post-generation instructions
+
+Their role is to:
+
+- choose the right blueprint subtree
+- assemble the rendering context
+- decide target paths
+- coordinate multi-step scaffold flows
+- present next steps to the developer
+
+So commands are not just wrappers around `engine.scaffold(...)`.
+They encode the semantic meaning of each CLI action.
+
+## Command Families
+
+The current commands already form several architectural groups.
+
+### Project Initialization
+
+`init.py` is the highest-level scaffold operation.
+It creates the main project skeleton and may also include optional feature bundles such as:
+
+- cabinet
+- booking
+- notifications
+
+This command is special because it coordinates several blueprint families in sequence:
+
+- `repo`
+- `deploy`
+- `project`
+- optional feature blueprints
+
+So `init` is not one scaffold action, but a project-construction workflow.
+
+### Standard App Scaffolding
+
+`add_app.py` handles the creation of a regular feature app inside `features/<app_name>/`.
+It uses the default app blueprint and assumes the generated project already exists.
+
+This command is the canonical "grow the project by one standard app" path.
+
+### Feature Bundle Commands
+
+Some commands scaffold more than one isolated folder because the feature they represent cuts across several layers of the generated project.
+
+Examples:
+
+- `booking.py`
+- `client_cabinet.py`
+- `notifications.py`
+
+These commands operate more like feature installers than like simple file generators.
+
+For example:
+
+- booking touches booking code, system settings, cabinet integration, and public templates
+- notifications splits output between feature code and ARQ infrastructure
+- client cabinet injects cabinet-facing code and system-side profile models
+
+This is an important distinction:
+the CLI supports both app scaffolding and architectural feature injection.
+
+### Quality Commands
+
+`quality.py` is not about application structure.
+It generates developer workflow support such as `.pre-commit-config.yaml` and related baseline files.
+
+This means the commands package does not only build runtime code.
+It also scaffolds developer tooling around the project.
+
+### Deployment Commands
+
+`deploy.py` handles operational infrastructure generation, currently around Docker-based deployment files.
+Like quality tooling, this command sits outside the main runtime app tree while still being part of the generated project ecosystem.
+
+## Common Command Pattern
+
+Despite their differences, the commands share one common architectural pattern:
+
+1. receive intent and parameters
+2. compute destination paths
+3. assemble context
+4. call `CLIEngine`
+5. print actionable next steps
+
+This gives the CLI a consistent mental model.
+Each command defines what is being added, but the flow of command execution stays stable.
+
+## Runtime Flow
+
+```mermaid
+flowchart TD
+    A["User intent from menu or args"] --> B["command handler"]
+    B --> C["resolve target path"]
+    B --> D["build render context"]
+    B --> E["choose blueprint subtree"]
+    C --> F["CLIEngine"]
+    D --> F
+    E --> F
+    F --> G["generated project files"]
+    B --> H["next-step instructions"]
+```
+
+## Why Commands Need Documentation
+
+Without command-level documentation, CLI can look like a flat list of actions.
+But in reality the commands encode the supported project-evolution model:
+
+- initialize a base project
+- expand it with standard apps
+- inject bigger architectural features
+- add project tooling
+- add deployment support
+
+So documenting commands helps explain not only what the CLI can do, but how the repository expects projects to grow over time.
+
+## Relationship To Other CLI Layers
+
+- `main.py` chooses which command handler should run
+- `prompts.py` provides the interactive inputs that feed commands
+- `CLIEngine` performs the actual file generation requested by commands
+- `blueprints/` provides the structural source material consumed by commands
+
+Commands are therefore the semantic center of the CLI:
+they interpret intent and convert it into generation work.
+
+## See Also
+
+- [CLI module](./module.md)
+- [CLI engine](./engine.md)
+- [CLI blueprints](./blueprints.md)

codex_django_cli-0.2.0/docs/en/architecture/cli/engine.md

@@ -0,0 +1,143 @@
+<!-- DOC_TYPE: CONCEPT -->
+
+# CLI Engine
+
+## Purpose
+
+`CLIEngine` is the execution core of the CLI scaffolding system.
+If commands decide what should be generated, `CLIEngine` decides how that generation actually happens on disk.
+
+Its responsibility is narrow but central:
+
+- locate blueprint trees
+- render Jinja templates
+- copy non-template assets
+- materialize the generated structure into a target directory
+
+This makes it the operational bridge between abstract blueprint intent and concrete project files.
+
+## Architectural Role
+
+The engine is intentionally separated from:
+
+- interactive prompts
+- command selection
+- feature-specific business decisions
+
+That separation matters because it keeps the generation mechanism stable even as menus, commands, and blueprint families evolve.
+
+In other words:
+
+- prompts collect decisions
+- commands assemble context and choose blueprints
+- the engine performs rendering and file emission
+
+This is a classic execution-core pattern.
+
+## Main Responsibilities
+
+### Blueprint Resolution
+
+The engine treats blueprints as a named tree rooted in `cli/blueprints`.
+Every scaffold operation begins by resolving a blueprint family such as:
+
+- `repo`
+- `project`
+- `apps/default`
+- `features/booking`
+- `deploy`
+
+This makes the engine path-driven rather than command-driven.
+Commands remain thin because the engine can operate on any blueprint subtree as long as the path and context are valid.
+
+### Template Rendering
+
+Files ending in `.j2` are rendered through a Jinja2 environment.
+The engine loads them relative to the blueprint root and injects the context provided by the command handler.
+
+This means the engine is not tied to specific variables like `project_name` or `app_name`.
+It simply renders whatever the selected blueprint expects.
+
+### Static File Copying
+
+Files that are not templates are copied as-is.
+This is important because generated projects need both:
+
+- dynamic files derived from context
+- static assets and support files that should remain unchanged
+
+So the engine acts as a mixed-mode emitter rather than a pure template renderer.
+
+### Directory Materialization
+
+The engine walks the source blueprint tree recursively and reproduces its structure under the target directory.
+That means folder layout in the blueprint tree is treated as part of the contract of generation, not as incidental organization.
+
+The CLI therefore preserves architectural placement through filesystem structure.
+
+### Overwrite Policy
+
+The engine also enforces a simple overwrite policy:
+
+- if a destination file exists and overwrite is disabled, it is skipped
+- if overwrite is enabled, it is replaced
+
+This gives commands a predictable and reusable file-conflict behavior without implementing that logic repeatedly in each handler.
+
+## Why The Engine Matters
+
+Without `CLIEngine`, every command would need to know how to:
+
+- walk directories
+- detect templates
+- render files
+- copy assets
+- manage destination paths
+
+By isolating this into one class, the CLI architecture gains:
+
+- less duplication
+- one consistent rendering model
+- one consistent scaffold policy
+- easier future extraction into a standalone CLI package
+
+## Runtime Flow
+
+```mermaid
+flowchart TD
+    A["Command handler"] --> B["prepare context"]
+    B --> C["CLIEngine.scaffold(...)"]
+    C --> D["resolve blueprint path"]
+    D --> E["walk files recursively"]
+    E --> F["render .j2 template"]
+    E --> G["copy static file"]
+    F --> H["write target file"]
+    G --> H
+```
+
+## Design Tradeoffs
+
+The engine is deliberately simple.
+It does not currently try to become:
+
+- a dependency graph manager
+- a merge-aware patcher
+- a semantic project migration tool
+
+Instead, it focuses on reliable tree-based generation.
+That simplicity is a strength for scaffolding, because commands can layer more specialized behavior above it when needed.
+
+## Relationship To Other CLI Layers
+
+- `main.py` decides when scaffolding should happen
+- `prompts.py` helps collect the user choices that feed command context
+- `commands/` decides which blueprint subtree to render and which context to pass
+- `blueprints/` contains the structural source material the engine consumes
+
+So the engine sits exactly in the middle of the CLI architecture:
+above raw files, below command semantics.
+
+## See Also
+
+- [CLI module](./module.md)
+- [CLI blueprints](./blueprints.md)