djux 0.1.0__tar.gz

djux-0.1.0/PKG-INFO

@@ -0,0 +1,172 @@
+Metadata-Version: 2.4
+Name: djux
+Version: 0.1.0
+Summary: Django app installer and registry CLI
+Author: Djux contributors
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/djuxhq/djux
+Project-URL: Repository, https://github.com/djuxhq/djux
+Project-URL: Issues, https://github.com/djuxhq/djux/issues
+Project-URL: Roadmap, https://github.com/djuxhq/djux/blob/main/APP_ROADMAP.md
+Keywords: django,cli,scaffold,templates,registry
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Framework :: Django
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: click>=8.1
+Requires-Dist: requests>=2.31
+Requires-Dist: rich>=13.0
+
+# djux
+
+**djux** is a CLI and registry for adding production-ready Django app templates to a project in one command. It handles the repetitive setup work: app files, Django settings, URL wiring, pip dependencies, and migrations.
+
+```bash
+pip install djux
+
+djux new myproject
+cd myproject
+
+djux add auth
+```
+
+Think of it as a Django app installer where the installed code is copied into your project so you can own it, edit it, and ship it like normal Django code.
+
+## Vision
+
+Djux aims to make reusable Django app templates easier to discover, install, inspect, and customize. The project is intentionally open to community feedback: the registry should grow around apps Django developers actually want, with a safe update story for vendored app code.
+
+Current focus:
+
+- Core app templates such as `auth`, `users`, `api-keys`, and `files`.
+- AI-ready templates such as `ai-models`, `ai-prompts`, `ai-chat`, `ai-usage`, and `ai-rag`.
+- A safer update workflow for copied app code: `djux outdated` and `djux update <app>`.
+
+See [APP_ROADMAP.md](APP_ROADMAP.md) for the full roadmap.
+
+## Installation
+
+Requires Python 3.10+.
+
+```bash
+pip install djux
+```
+
+Verify:
+
+```bash
+djux --version
+```
+
+## Quick start
+
+```bash
+# 1. Create a new project
+djux new myproject
+cd myproject
+
+# 2. Set up your environment
+python -m venv .venv
+source .venv/bin/activate    # Windows: .venv\Scripts\activate
+pip install -r requirements.txt
+cp .env.example .env
+
+# 3. Run initial migrations and start the server
+python manage.py migrate
+python manage.py runserver
+
+# 4. Add apps
+djux add auth
+```
+
+See [docs/getting-started.md](docs/getting-started.md) for a full walkthrough.
+
+## Available apps
+
+| Name | Description | Tags |
+|---|---|---|
+| `auth` | JWT authentication: register, login, logout, refresh, me | `auth` `jwt` `api` |
+| `users` | User profiles, avatars, preferences | planned |
+| `api-keys` | API keys, scopes, rotation, revocation | planned |
+| `ai-chat` | Basic chat API with conversation history | planned `ai` |
+| `ai-models` | Provider/model registry and model selection | planned `ai` |
+
+```bash
+djux list
+```
+
+## How it works
+
+`djux add <app>` currently:
+
+1. Looks up the app in the registry.
+2. Downloads and extracts the app zip from GitHub.
+3. Validates the `djux.json` manifest.
+4. Copies the `app/` folder into your project's `apps/` directory.
+5. Patches `config/settings.py` with `INSTALLED_APPS` entries and settings blocks.
+6. Patches `config/urls.py` with the route include.
+7. Runs `pip install` for declared dependencies.
+8. Runs `python manage.py migrate` if the app has migrations.
+9. Records the installed app in `djux.project.json`.
+
+Installed apps are vendored into the project. That means developers fully own the copied code after install.
+
+## Project layout
+
+```text
+myproject/
+|-- config/
+|   |-- settings.py        # djux patches INSTALLED_APPS here
+|   `-- urls.py            # djux adds URL includes here
+|-- apps/                  # all Django apps land here
+|-- templates/
+|-- static/
+|-- manage.py
+|-- djux.project.json      # tracks installed apps
+`-- requirements.txt
+```
+
+## Documentation
+
+| Document | Contents |
+|---|---|
+| [Getting started](docs/getting-started.md) | Install, scaffold, first app, what changed |
+| [CLI reference](docs/cli-reference.md) | Commands, options, errors |
+| [Creating apps](docs/creating-apps.md) | Build and publish a djux app |
+| [Manifest spec](docs/manifest-spec.md) | `djux.json` contract and versioning rules |
+| [App conventions](docs/app-conventions.md) | Naming, layout, settings, migrations |
+| [Update design](docs/update-design.md) | Planned `djux outdated` and `djux update <app>` flow |
+| [Smoke test checklist](docs/smoke-test-checklist.md) | Quality checklist for official apps |
+| [Registry](docs/registry.md) | Registry format, caching, custom registries |
+
+## Repositories
+
+| Repo | Purpose |
+|---|---|
+| [djuxhq/djux](https://github.com/djuxhq/djux) | CLI and project template |
+| [djuxhq/djux-registry](https://github.com/djuxhq/djux-registry) | Registry index |
+| [djuxhq/djux-app-auth](https://github.com/djuxhq/djux-app-auth) | Official auth app |
+
+## Contributing
+
+Contributors and testers are welcome. Useful ways to help:
+
+- Build official app templates.
+- Test Djux in real Django projects.
+- Improve the CLI and update workflow.
+- Review app manifests and registry entries.
+- Improve documentation.
+
+Start with [CONTRIBUTING.md](CONTRIBUTING.md), then check the roadmap and open issues.
+
+## License
+
+MIT

djux-0.1.0/README.md

@@ -0,0 +1,145 @@
+# djux
+
+**djux** is a CLI and registry for adding production-ready Django app templates to a project in one command. It handles the repetitive setup work: app files, Django settings, URL wiring, pip dependencies, and migrations.
+
+```bash
+pip install djux
+
+djux new myproject
+cd myproject
+
+djux add auth
+```
+
+Think of it as a Django app installer where the installed code is copied into your project so you can own it, edit it, and ship it like normal Django code.
+
+## Vision
+
+Djux aims to make reusable Django app templates easier to discover, install, inspect, and customize. The project is intentionally open to community feedback: the registry should grow around apps Django developers actually want, with a safe update story for vendored app code.
+
+Current focus:
+
+- Core app templates such as `auth`, `users`, `api-keys`, and `files`.
+- AI-ready templates such as `ai-models`, `ai-prompts`, `ai-chat`, `ai-usage`, and `ai-rag`.
+- A safer update workflow for copied app code: `djux outdated` and `djux update <app>`.
+
+See [APP_ROADMAP.md](APP_ROADMAP.md) for the full roadmap.
+
+## Installation
+
+Requires Python 3.10+.
+
+```bash
+pip install djux
+```
+
+Verify:
+
+```bash
+djux --version
+```
+
+## Quick start
+
+```bash
+# 1. Create a new project
+djux new myproject
+cd myproject
+
+# 2. Set up your environment
+python -m venv .venv
+source .venv/bin/activate    # Windows: .venv\Scripts\activate
+pip install -r requirements.txt
+cp .env.example .env
+
+# 3. Run initial migrations and start the server
+python manage.py migrate
+python manage.py runserver
+
+# 4. Add apps
+djux add auth
+```
+
+See [docs/getting-started.md](docs/getting-started.md) for a full walkthrough.
+
+## Available apps
+
+| Name | Description | Tags |
+|---|---|---|
+| `auth` | JWT authentication: register, login, logout, refresh, me | `auth` `jwt` `api` |
+| `users` | User profiles, avatars, preferences | planned |
+| `api-keys` | API keys, scopes, rotation, revocation | planned |
+| `ai-chat` | Basic chat API with conversation history | planned `ai` |
+| `ai-models` | Provider/model registry and model selection | planned `ai` |
+
+```bash
+djux list
+```
+
+## How it works
+
+`djux add <app>` currently:
+
+1. Looks up the app in the registry.
+2. Downloads and extracts the app zip from GitHub.
+3. Validates the `djux.json` manifest.
+4. Copies the `app/` folder into your project's `apps/` directory.
+5. Patches `config/settings.py` with `INSTALLED_APPS` entries and settings blocks.
+6. Patches `config/urls.py` with the route include.
+7. Runs `pip install` for declared dependencies.
+8. Runs `python manage.py migrate` if the app has migrations.
+9. Records the installed app in `djux.project.json`.
+
+Installed apps are vendored into the project. That means developers fully own the copied code after install.
+
+## Project layout
+
+```text
+myproject/
+|-- config/
+|   |-- settings.py        # djux patches INSTALLED_APPS here
+|   `-- urls.py            # djux adds URL includes here
+|-- apps/                  # all Django apps land here
+|-- templates/
+|-- static/
+|-- manage.py
+|-- djux.project.json      # tracks installed apps
+`-- requirements.txt
+```
+
+## Documentation
+
+| Document | Contents |
+|---|---|
+| [Getting started](docs/getting-started.md) | Install, scaffold, first app, what changed |
+| [CLI reference](docs/cli-reference.md) | Commands, options, errors |
+| [Creating apps](docs/creating-apps.md) | Build and publish a djux app |
+| [Manifest spec](docs/manifest-spec.md) | `djux.json` contract and versioning rules |
+| [App conventions](docs/app-conventions.md) | Naming, layout, settings, migrations |
+| [Update design](docs/update-design.md) | Planned `djux outdated` and `djux update <app>` flow |
+| [Smoke test checklist](docs/smoke-test-checklist.md) | Quality checklist for official apps |
+| [Registry](docs/registry.md) | Registry format, caching, custom registries |
+
+## Repositories
+
+| Repo | Purpose |
+|---|---|
+| [djuxhq/djux](https://github.com/djuxhq/djux) | CLI and project template |
+| [djuxhq/djux-registry](https://github.com/djuxhq/djux-registry) | Registry index |
+| [djuxhq/djux-app-auth](https://github.com/djuxhq/djux-app-auth) | Official auth app |
+
+## Contributing
+
+Contributors and testers are welcome. Useful ways to help:
+
+- Build official app templates.
+- Test Djux in real Django projects.
+- Improve the CLI and update workflow.
+- Review app manifests and registry entries.
+- Improve documentation.
+
+Start with [CONTRIBUTING.md](CONTRIBUTING.md), then check the roadmap and open issues.
+
+## License
+
+MIT

djux-0.1.0/djux/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

djux-0.1.0/djux/cli.py

@@ -0,0 +1,30 @@
+import os
+import sys
+
+# Ensure UTF-8 output on Windows (required for Rich/Unicode characters)
+if sys.platform == "win32":
+    os.environ.setdefault("PYTHONUTF8", "1")
+    if hasattr(sys.stdout, "reconfigure"):
+        sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+    if hasattr(sys.stderr, "reconfigure"):
+        sys.stderr.reconfigure(encoding="utf-8", errors="replace")
+
+import click
+from djux.commands.new import new
+from djux.commands.add import add
+from djux.commands.remove import remove
+from djux.commands.list import list_apps
+from djux.commands.publish import publish
+
+
+@click.group()
+@click.version_option(package_name="djux")
+def main():
+    """djux — add production-ready Django apps in one command."""
+
+
+main.add_command(new)
+main.add_command(add)
+main.add_command(remove)
+main.add_command(list_apps, name="list")
+main.add_command(publish)

djux-0.1.0/djux/commands/add.py

@@ -0,0 +1,207 @@
+import json
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+import click
+from rich.console import Console
+
+from djux.core.downloader import download_and_extract
+from djux.core.manifest import InvalidManifestError, parse_manifest
+from djux.core.patcher import (
+    patch_installed_apps,
+    patch_settings_block,
+    patch_urls,
+)
+from djux.core.registry import REGISTRY_URL, fetch_registry, get_app
+
+console = Console()
+
+
+def _find_project_root() -> Path | None:
+    current = Path.cwd()
+    for parent in [current, *current.parents]:
+        if (parent / "djux.project.json").exists():
+            return parent
+    return None
+
+
+def _read_project_json(root: Path) -> dict:
+    return json.loads((root / "djux.project.json").read_text(encoding="utf-8"))
+
+
+def _write_project_json(root: Path, data: dict) -> None:
+    (root / "djux.project.json").write_text(
+        json.dumps(data, indent=2), encoding="utf-8"
+    )
+
+
+@click.command()
+@click.argument("app_name")
+@click.option("--registry", "registry_url", default=REGISTRY_URL, help="Custom registry URL.")
+def add(app_name: str, registry_url: str):
+    """Download and install a djux app into the current project."""
+
+    # 1. Find project root
+    root = _find_project_root()
+    if root is None:
+        console.print("✗ No djux project found. Run this inside a djx project.")
+        raise SystemExit(1)
+
+    # 2. Check if already installed
+    project_data = _read_project_json(root)
+    if app_name in project_data.get("installed_apps", []):
+        console.print(f"⚠  App '[bold]{app_name}[/bold]' is already installed.")
+        raise SystemExit(0)
+
+    # 3. Fetch registry
+    with console.status("Fetching registry..."):
+        try:
+            registry = fetch_registry(registry_url)
+        except RuntimeError as e:
+            console.print(f"✗ {e}")
+            raise SystemExit(1)
+
+    app_entry = get_app(registry, app_name)
+    if app_entry is None:
+        console.print(
+            f"✗ App '[bold]{app_name}[/bold]' not found in registry.\n"
+            "  Run [cyan]djux list[/cyan] to see available apps."
+        )
+        raise SystemExit(1)
+
+    console.print(f"✓ Found [bold]{app_name}[/bold] v{app_entry.get('version', '?')}")
+
+    # 4-5. Download and extract
+    with console.status("Downloading..."):
+        try:
+            extracted = download_and_extract(app_entry["download"], app_name)
+        except Exception as e:
+            console.print(f"✗ Download failed: {e}")
+            raise SystemExit(1)
+
+    console.print("✓ Downloaded")
+
+    # 6. Validate manifest
+    try:
+        manifest = parse_manifest(extracted)
+    except InvalidManifestError as e:
+        console.print(f"✗ {e}")
+        raise SystemExit(1)
+
+    # 7. Check required apps
+    requires = manifest.get("requires_apps", [])
+    installed = project_data.get("installed_apps", [])
+    for dep in requires:
+        if dep not in installed:
+            console.print(
+                f"✗ App '[bold]{app_name}[/bold]' requires "
+                f"'[bold]{dep}[/bold]' to be installed first.\n"
+                f"  Run: [cyan]djux add {dep}[/cyan]"
+            )
+            raise SystemExit(1)
+
+    # 8. Copy app code
+    app_src = extracted / "app"
+    if not app_src.exists():
+        console.print("✗ App package is missing the 'app/' directory.")
+        raise SystemExit(1)
+
+    install_name = app_name
+    app_dest = root / "apps" / install_name
+
+    if app_dest.exists():
+        console.print(
+            f"\n[yellow]Warning:[/yellow] Directory 'apps/{install_name}' already exists."
+        )
+        while True:
+            new_name = click.prompt(
+                "  Enter a new name to install as (or leave empty to cancel)",
+                default="",
+                show_default=False,
+            ).strip()
+
+            if not new_name:
+                console.print("Cancelled.")
+                raise SystemExit(0)
+
+            import re as _re
+            if not _re.match(r"^[a-z][a-z0-9_]*$", new_name):
+                console.print(
+                    "  [red]Invalid name.[/red] Use lowercase letters, digits, and underscores only."
+                )
+                continue
+
+            app_dest = root / "apps" / new_name
+            if app_dest.exists():
+                console.print(f"  [red]Directory 'apps/{new_name}' also exists.[/red] Try another name.")
+                continue
+
+            install_name = new_name
+            console.print(f"  Installing as '[bold]{install_name}[/bold]'")
+            break
+
+    shutil.copytree(app_src, app_dest)
+    console.print(f"✓ App files copied to apps/{install_name}/")
+
+    # 9. Patch settings.py
+    settings_path = root / "config" / "settings.py"
+    patch_installed_apps(settings_path, manifest["installed_apps"])
+
+    settings_patch = manifest.get("settings_patch")
+    if settings_patch:
+        patch_settings_block(settings_path, settings_patch)
+
+    console.print("✓ settings.py updated")
+
+    # 10. Patch urls.py — use install_name so the URL include matches the folder
+    urls_path = root / "config" / "urls.py"
+    patch_urls(urls_path, install_name, manifest["url_prefix"])
+    console.print("✓ urls.py updated")
+
+    # 11. Install pip dependencies
+    deps = manifest.get("dependencies", [])
+    if deps:
+        with console.status("Installing dependencies..."):
+            result = subprocess.run(
+                [sys.executable, "-m", "pip", "install", *deps],
+                capture_output=True,
+                text=True,
+            )
+            if result.returncode != 0:
+                console.print(f"✗ pip install failed:\n{result.stderr}")
+                raise SystemExit(1)
+        console.print("✓ Dependencies installed")
+
+    # 12. Run migrations
+    if manifest.get("migrations", False):
+        with console.status("Running migrations..."):
+            result = subprocess.run(
+                [sys.executable, "manage.py", "migrate"],
+                cwd=root,
+                capture_output=True,
+                text=True,
+            )
+            if result.returncode != 0:
+                console.print(f"✗ migrate failed:\n{result.stderr}")
+                raise SystemExit(1)
+        console.print("✓ Migrations applied")
+
+    # 13. Update djux.project.json
+    project_data.setdefault("installed_apps", []).append(install_name)
+    _write_project_json(root, project_data)
+
+    # 14. Print success
+    label = f"{app_name}" if install_name == app_name else f"{app_name} (as '{install_name}')"
+    console.print(f"\n[green]✓ {label} added successfully![/green]")
+
+    env_vars = manifest.get("env_vars", [])
+    if env_vars:
+        console.print("\nRequired environment variables:")
+        for var in env_vars:
+            console.print(f"  • [yellow]{var}[/yellow]")
+
+    notes = manifest.get("notes")
+    if notes:
+        console.print(f"\nNotes: {notes}")

djux-0.1.0/djux/commands/list.py

@@ -0,0 +1,45 @@
+import click
+from rich.console import Console
+from rich.table import Table
+
+from djux.core.registry import REGISTRY_URL, fetch_registry
+
+console = Console()
+
+
+@click.command()
+@click.option("--registry", "registry_url", default=REGISTRY_URL, help="Custom registry URL.")
+@click.option("--refresh", is_flag=True, help="Bypass cache and fetch fresh registry.")
+def list_apps(registry_url: str, refresh: bool):
+    """Show all apps available in the djux registry."""
+    with console.status("Fetching registry..."):
+        try:
+            registry = fetch_registry(registry_url, force_refresh=refresh)
+        except RuntimeError as e:
+            console.print(f"✗ {e}")
+            raise SystemExit(1)
+
+    apps = registry.get("apps", {})
+    if not apps:
+        console.print("No apps found in registry.")
+        return
+
+    table = Table(title="Available djux Apps", border_style="blue")
+    table.add_column("Name", style="bold cyan", no_wrap=True)
+    table.add_column("Version", style="green")
+    table.add_column("Description")
+    table.add_column("Tags", style="dim")
+
+    for name, info in apps.items():
+        tags = ", ".join(info.get("tags", []))
+        official = " [yellow]★[/yellow]" if info.get("official") else ""
+        table.add_row(
+            f"{name}{official}",
+            info.get("version", "?"),
+            info.get("description", ""),
+            tags,
+        )
+
+    console.print(table)
+    console.print("\n  Install any app:  [bold cyan]djux add <name>[/bold cyan]")
+    console.print("  [yellow]★[/yellow] = official djux app")

djux-0.1.0/djux/commands/new.py

@@ -0,0 +1,51 @@
+import shutil
+from pathlib import Path
+
+import click
+from rich.console import Console
+from rich.panel import Panel
+
+console = Console()
+
+TEMPLATE_DIR = Path(__file__).parent.parent / "templates" / "project_template"
+
+
+def _replace_in_file(path: Path, project_name: str) -> None:
+    try:
+        text = path.read_text(encoding="utf-8")
+        path.write_text(text.replace("{{project_name}}", project_name), encoding="utf-8")
+    except (UnicodeDecodeError, PermissionError):
+        pass  # skip binary files
+
+
+@click.command()
+@click.argument("project_name")
+def new(project_name: str):
+    """Scaffold a new djux Django project."""
+    target = Path.cwd() / project_name
+
+    if target.exists():
+        console.print(f"✗ Directory '[bold]{project_name}[/bold]' already exists.")
+        raise SystemExit(1)
+
+    console.print(f"Creating project: [bold]{project_name}[/bold]\n")
+
+    shutil.copytree(TEMPLATE_DIR, target)
+
+    for file_path in target.rglob("*"):
+        if file_path.is_file():
+            _replace_in_file(file_path, project_name)
+
+    panel_content = (
+        f"[green]✓[/green] Project created: [bold]{project_name}/[/bold]\n\n"
+        f"  [cyan]cd {project_name}[/cyan]\n"
+        f"  [cyan]python -m venv .venv[/cyan]\n"
+        f"  [cyan]source .venv/bin/activate[/cyan]  [dim]# Windows: .venv\\Scripts\\activate[/dim]\n"
+        f"  [cyan]pip install -r requirements.txt[/cyan]\n"
+        f"  [cyan]cp .env.example .env[/cyan]\n"
+        f"  [cyan]python manage.py migrate[/cyan]\n"
+        f"  [cyan]python manage.py runserver[/cyan]\n\n"
+        f"  Then add apps:  [bold cyan]djux add auth[/bold cyan]"
+    )
+
+    console.print(Panel(panel_content, title="Ready", border_style="green"))