# Strura - The Architect's CLI

**Constructing solid foundations for your code.**

Strura is a high-performance code generation and scaffolding tool inspired by the elegance of `php artisan`. It is designed for developers who want to build robust applications using FastAPI, SQLAlchemy, and Pydantic without wasting time on repetitive boilerplate.

> "Architecture is not just about how a project looks, but how it stands. Strura builds the foundation for you."

---

## Key Features

-   **DDD-First Scaffolding**: Create project structures based on Domain-Driven Design and Clean Architecture.
-   **Bounded Contexts**: Generate isolated contexts with specific layers for Application, Domain, and Infrastructure.
-   **Type-Safe by Default**: Generated code is 100% compliant with Pydantic v2 and FastAPI best practices.
-   **Powered by uv**: Extremely fast dependency management and project initialization.
-   **Artisanal Code**: Every file follows strict industry conventions, Pep8 standards, and structural best practices.

---

## Philosophy

Strura follows the principles of:
- **Domain-Driven Design (DDD)**
- **Hexagonal Architecture** (Ports & Adapters)
- **Strict layer separation**

The core domain does not depend on external frameworks; Strura focuses on building the structural foundation.

## Integrations

Strura can optionally integrate with:
- **FastAPI**
- **SQLAlchemy**
- **core_api** (auth, users, etc.)

## Customization

The generated code is designed to be:
- **Editable**: No hidden logic; what you see is what you own.
- **Extensible**: Easily adapt the structure as your project grows.
- **Independent**: Once generated, the code does not depend on the scaffolder.

---

## Installation

### One-liner (installs `uv` + `strura` automatically)

```bash
curl -LsSf https://raw.githubusercontent.com/m4ck-y/strura/main/install.sh | bash
```

### With `uv` (if already installed)

```bash
uv tool install strura
```

### With `pipx`

```bash
pipx install strura
```

### With `pip`

```bash
pip install strura
```

### Verify the installation

```bash
strura --help
```

### Upgrade to latest version

```bash
uv add strura --upgrade-package strura
```

---

## Quick Start

### Initialize a new project

```bash
strura init my-awesome-api
```

### Or scaffold the current directory

```bash
mkdir my-api && cd my-api
strura init .
```

---

## Usage & Commands

Strura uses an intuitive `verb:subject` syntax to keep your workflow fluid and readable.

-   **Initialize a Project**
    Set up a professional DDD structure. Supports creating a new folder (Mode A) or formatting the current one (Mode B).
    ```bash
    strura init my-awesome-api
    ```
-   **Generate a Bounded Context**
    Create a new isolated context with Application, Domain, and Infrastructure layers.
    ```bash
    strura gen:context billing
    ```

### Roadmap (Coming Soon)
-   `strura gen:schema <context>.<entity>`: Pydantic DTOs for input/output.
-   `strura gen:api <context>.<resource>`: Full CRUD endpoints.

---

## The Strura Directory Standard

Running `strura init` implements a production-ready directory structure designed for scalability:

```
.
├── app/
│   ├── contexts/                # Isolated bounded contexts (DDD)
│   ├── settings/                # Environment and Database config
│   ├── shared/                  # Common code across contexts
│   └── main.py                  # FastAPI entry point
├── tests/                       # Unit and integration test suites
├── docs/                        # Command-specific documentation
├── .agent/                      # AI Agent workflows and rules
├── pyproject.toml               # Dependency management (uv)
└── README.md
```

---

## Customization

Tailor the code generation to your needs by creating a `.strura.yaml` file in your project root:

```yaml
framework: fastapi
database: postgresql
orm: sqlalchemy
indentation: 4
naming_convention: snake_case
templates: ./custom_templates
```

---

## Development & Publishing

### 1. Testing
To add dependencies and run tests:
```bash
uv add --dev pytest
uv run pytest -vv
```

### 2. Publishing
To develop locally, build, and publish:
```bash
# Install in editable mode
uv pip install -e .

# Clean previous builds (Crucial to avoid 400 errors)
rm -rf dist/*

# Build the package
uv build

# Publish to PyPI (requires API Token)
uv publish
```

### AI-Agent Workflows

This project is specialized for **Agentic Development**. We maintain strict standards for AI agents in the `.agent/` directory:

-   **[Workflows](.agents/workflows/)**: Standardized processes for documentation, Git, and automation.
-   **[Rules](.agents/rules/)**: Best practices for FastAPI, Pydantic, and SQLAlchemy.

For more details, check [**.agents/workflows/WRITING.md**](.agents/workflows/WRITING.md).

---

## Contributing

Looking to improve Strura? We welcome architects of all levels!

1.  Fork the project.
2.  Create your feature branch: `git checkout -b feature/amazing-logic`.
3.  Commit your changes: `git commit -m 'Add some amazing feature'`.
4.  Push to the branch: `git push origin feature/amazing-logic`.
5.  Open a Pull Request.
