puerto 0.21.0

Puerto — Rust full-stack DDD framework CLI. Scaffolds Clean Architecture projects with auto-wired DI, SQLx support, and zero manual wiring. Formerly puerto-framework.
use crate::generators::layout;
use std::path::Path;

use crate::generators::conflict::{OverwritePolicy, guard_entity_overwrite};
use crate::generators::{
    application::write_application_files,
    domain::write_domain_files,
    infrastructure::write_repository_files,
    migration::run_create_table_migration,
    naming::{crud_use_cases, pascal_to_snake, to_pascal_case},
    presentation::write_presentation_files,
    web::write_web_files,
};
use crate::puerto_toml::{Field, ValueObjectDefinition};

/// Low-level scaffold: the four crates of the entity's context (ADR-0023), its web slice, its
/// `[[entidad]]` block and the regenerated wiring. Always the five CRUD use cases.
pub fn run(
    name: &str,
    base: &Path,
    db: bool,
    fields: &[Field],
    shared_vos: &[ValueObjectDefinition],
) -> Result<(), Box<dyn std::error::Error>> {
    let pascal = to_pascal_case(name);
    let snake = pascal_to_snake(&pascal);
    let web = crate::puerto_toml::read(base).is_ok_and(|c| c.project.web);

    write_domain_files(&pascal, &snake, base, fields, shared_vos)?;
    write_application_files(&pascal, &snake, base, fields, shared_vos)?;
    write_repository_files(&pascal, &snake, base, db, fields, shared_vos)?;
    write_presentation_files(&pascal, &snake, base, fields)?;
    if web {
        write_web_files(&pascal, base, fields)?;
    }

    crate::puerto_toml::add_entity(base, &pascal, crud_use_cases(&snake), db, fields.to_vec())?;
    crate::patchers::routes_rs::patch_routes_from_manifest(base, &pascal, &snake)?;
    crate::generators::bootstrap::regenerate_bootstrap(base)?;

    let repo_name = if db {
        format!("Repositorio{pascal}Postgres")
    } else {
        format!("Repositorio{pascal}EnMemoria")
    };
    let dir = layout::context_dir(&snake);
    println!("✓ {dir}/dominio/         — model, errors, repository port, Madre{pascal}");
    println!("✓ {dir}/aplicacion/      — create, get, list, update, delete");
    println!("✓ {dir}/infraestructura/ — {repo_name}");
    println!("✓ {dir}/rest/            — routes, dto, responses, errors");
    if web {
        println!("✓ web/ — list, detail and form screens, HTTP repository");
    }
    println!("✓ Done. Zero manual wiring.");
    if web {
        println!(
            "\nThe API changed. Next: make web/sync   (exports the spec, regenerates the web types)"
        );
    }

    Ok(())
}

/// `--publico` and `--rol` of `puerto generar scaffold` in an auth project (ADR-0021 § 4): the
/// CRUD use cases whose routes take no `BearerAuth`, and the roles a route requires.
#[derive(Debug, Default, Clone)]
pub struct ScaffoldAccess {
    pub public: Vec<String>,
    pub roles: std::collections::BTreeMap<String, Vec<String>>,
}

impl ScaffoldAccess {
    /// `--publico list_products,get_product` and `--rol create_product=admin,…` as the CLI got them.
    pub fn from_args(public: &[String], roles: &[String]) -> Result<Self, String> {
        let mut access = Self {
            public: public.to_vec(),
            ..Default::default()
        };
        for arg in roles {
            let (use_case, role) = arg.split_once('=').ok_or_else(|| {
                format!(
                    "invalid --rol '{arg}'. Expected <use_case>=<role>, e.g. borrar_product=admin"
                )
            })?;
            let roles = access.roles.entry(use_case.to_string()).or_default();
            if !roles.iter().any(|r| r == role) {
                roles.push(role.to_string());
            }
        }
        Ok(access)
    }

    fn is_empty(&self) -> bool {
        self.public.is_empty() && self.roles.is_empty()
    }
}

/// Checks `access` against the entity's CRUD use cases and writes it to its `[[entidad]]` block,
/// before any file is rendered: the generators read it back from there. A re-scaffold without
/// flags keeps what the block says.
fn record_access(
    base: &Path,
    pascal: &str,
    db: bool,
    fields: &[Field],
    access: &ScaffoldAccess,
) -> Result<(), Box<dyn std::error::Error>> {
    let mut config = crate::puerto_toml::read(base)?;
    if !config.project.has_auth() {
        if !access.is_empty() {
            return Err(
                "--publico and --rol need an auth project (`puerto nuevo --auth oidc`)".into(),
            );
        }
        return Ok(());
    }
    let snake = pascal_to_snake(pascal);
    let checked = crate::puerto_toml::Entity {
        name: pascal.to_string(),
        use_cases: crud_use_cases(&snake),
        public: access.public.clone(),
        roles: access.roles.clone(),
        ..Default::default()
    };
    let errors = crate::validation::validate_entity_access(&checked);
    if !errors.is_empty() {
        return Err(format!("{pascal}: {}", errors.join("\n  ")).into());
    }
    match config.entity.iter_mut().find(|e| e.name == pascal) {
        // A re-scaffold: the routes are rewritten as the block already says.
        Some(_) if access.is_empty() => return Ok(()),
        Some(entity) => {
            entity.public = checked.public;
            entity.roles = checked.roles;
        }
        None => config.entity.push(crate::puerto_toml::Entity {
            db,
            fields: fields.to_vec(),
            ..checked
        }),
    }
    crate::puerto_toml::write(base, &config)
}

/// `puerto generar scaffold <Name>` without `--publico` / `--rol`.
/// Reads `project.db` from `puerto.toml`, always generates full CRUD.
/// `cli_fields` are fields passed from the CLI (e.g. `title:String price:i64`).
///
/// Refuses to overwrite an already-generated entity unless `--forzar`; see `conflict.rs`.
#[cfg(test)]
pub fn run_scaffold(
    name: &str,
    base: &Path,
    cli_fields: &[Field],
    overwrite: OverwritePolicy,
) -> Result<(), Box<dyn std::error::Error>> {
    run_scaffold_with_access(
        name,
        base,
        cli_fields,
        overwrite,
        &ScaffoldAccess::default(),
    )
}

/// [`run_scaffold`] with `--publico` / `--rol`. In an auth project every CRUD route takes
/// `BearerAuth` except the `public` ones; outside one, `access` must be empty.
pub fn run_scaffold_with_access(
    name: &str,
    base: &Path,
    cli_fields: &[Field],
    overwrite: OverwritePolicy,
    access: &ScaffoldAccess,
) -> Result<(), Box<dyn std::error::Error>> {
    let config = crate::puerto_toml::read(base)?;
    let db = config.project.db;
    let shared_vos = config.value_object.clone();
    let pascal = to_pascal_case(name);
    let fields = if !cli_fields.is_empty() {
        cli_fields.to_vec()
    } else {
        config
            .entity
            .iter()
            .find(|e| e.name == pascal)
            .map(|e| e.fields.clone())
            .unwrap_or_default()
    };

    // Checked before the first byte is written — a half-overwritten project is worse than a
    // refused command.
    crate::validation::validate_entity_name(&pascal)?;
    if config.project.has_auth() {
        crate::validation::validate_auth_entity_name(&pascal)?;
    }
    crate::validation::validate_unique_field_names(&fields)?;
    if db {
        for f in &fields {
            crate::validation::validate_sql_field_name(&f.name)?;
        }
    }
    let vo_conflicts = crate::validation::validate_vo_coherence(&fields, &shared_vos);
    if !vo_conflicts.is_empty() {
        return Err(vo_conflicts.join("\n  ").into());
    }
    crate::validation::validate_references_before_writing(&pascal, &fields, &config, base)?;
    guard_entity_overwrite(
        base,
        &pascal_to_snake(&pascal),
        db,
        config.project.web,
        overwrite,
    )?;
    record_access(base, &pascal, db, &fields, access)?;

    run(name, base, db, &fields, &shared_vos)?;
    if db {
        let snake = pascal_to_snake(&pascal);
        let migration_sql = crate::generators::infrastructure::create_table_sql(&snake, &fields);
        run_create_table_migration(&snake, base, &migration_sql)?;
    }
    Ok(())
}

/// CLI entry point for `puerto generar objeto-valor <Name> <type>`.
///
/// Validated here, at the command that writes it: an invalid declaration used to land in
/// puerto.toml and only surface later, in `puerto validar` or as uncompilable generated code.
pub fn run_value_object(
    name: &str,
    inner_type: &str,
    base: &Path,
) -> Result<(), Box<dyn std::error::Error>> {
    let inner_type = &crate::puerto_toml::expand_type(inner_type);
    crate::validation::validate_vo_name(name)?;
    crate::validation::validate_shared_vo_inner_type(inner_type)?;

    let config = crate::puerto_toml::read(base)?;
    if config.value_object.iter().any(|vo| vo.name == name) {
        return Err(
            format!("shared value object '{name}' is already declared in puerto.toml").into(),
        );
    }
    crate::puerto_toml::add_value_object(base, name, inner_type)?;
    println!("✓ Shared value object '{name}' added to puerto.toml");
    Ok(())
}