Changelog
[0.21.0] - 2026-11-16
Section titled “[0.21.0] - 2026-11-16”One crate per context and layer, and everything Puerto generates in Spanish (PLAN Phase 19,
ADR-0023,
ADR-0024; the vocabulary is
docs/glosario.md). Puerto’s own source code, its website, README and CLI
messages stay in English; the frontend (web/) keeps its internal vocabulary until its own phase,
and follows the API’s contract (JSON fields, routes, error codes).
Breaking
Section titled “Breaking”- Layout:
business/,infrastructure/,presentation/are gone. Each entity is a context,contextos/<c>/{dominio,aplicacion,infraestructura,rest}with the cratesdominio_<c>,aplicacion_<c>,infra_<c>,rest_<c>;nucleoholds the shared value objects;presentacion/{cableado,api,worker}the wiring and the binaries;migraciones/+migradorevery migration and the oneMIGRADORthe Postgres tests run on. A use case is one file (contract + implementation); doubles live next to their trait (dobles, featurepruebas) puerto.tomlin Spanish:[proyecto] nombre,[[entidad]] nombre casos_de_uso publicos roles eventos,[[entidad.campos]] nombre tipo unico objeto_valor clase_objeto_valor variantes referencia,[[objeto_valor]],[[consumidor]],[[correo]] tras- The CLI in Spanish:
puerto nuevo,puerto validar,puerto listar,puerto generar scaffold|dominio|aplicacion|repositorio|presentacion|caso-de-uso|objeto-valor|migracion|evento|consumidor|correo|bootstrap|web|snippets;--nombre,--destino,--forzar,--permitir-faltantes,--sin-db,--sin-web,--sin-demo,--eventos,--publico,--rol,--tras,--para - The runtime crates:
puerto-core→puerto-nucleo,puerto-events→puerto-eventos,puerto-mail→puerto-correo, and every crate’s API, tables and messages in Spanish (ErrorRepositorio,PeticionPagina,Pagina { elementos, total, limite, desplazamiento },RespuestaError { codigo, mensaje },ManejadorEvento,EnviadorCorreo,Autenticador,#[requiere_rol],ConfigKafka::asegurar_topics…) - Generated code in Spanish: types (
RepositorioProducto,CrearProductoImpl,MadreProducto,DtoProducto,RespuestaCrearProducto), methods (ejecutar,guardar,buscar_por_id,construir,aleatorio,con_<campo>), system fields (creado_en,actualizado_en,borrado,borrado_en), error variants and codes (producto.validacion.nombre_vacio,producto.no_encontrado), events (producto_creado), tables and routes with Spanish plurals (/productos,?limite=&desplazamiento=), tests (deberia_…_cuando_…,// Preparar // Actuar // Comprobar), logs, comments and theAGENTS.mdof every project. The demo entity isSaludo(GET /saludos/:nombre); auth’s isUsuario(POST /auth/registro); mail templates areasunto.txt,cuerpo.html,cuerpo.txt; the generated Makefile’s targets aretest/dominio,generar/entidad,db/reiniciar,eventos/descartados,correo/ui,auth/conceder… - An entity declared without fields gets
nombre: String(wasname: String)
No migration guide: there are no generated projects to migrate (the exception to release.md
decided on 2026-11-14 for this release).
[0.20.0] - 2026-10-14
Section titled “[0.20.0] - 2026-10-14”References between entities (PLAN Phase 18,
ADR-0022): an entity holds
another’s typed id, and in --db projects a foreign key checks that the target exists. A project
without references is generated as in 0.19, but for its AGENTS.md and its Pg test modules.
🚀 Features
Section titled “🚀 Features”customer_id:ref:Customerandreviewer_id:ref:opt:Customer([[entity.fields]] references = "Customer"): the domain, Params, repository port, Object Mother and tests hold the target’sCustomerId, so ids of two entities cannot be swapped; rows, DTOs and the events snapshot hold aUuid.!(one-to-one) is allowed onref:, not onref:opt:.scaffoldrefuses a target that is not a CRUD entity with code on disk, the entity itself, andref:User--db:CONSTRAINT orders_customer_id_fkey REFERENCES customers (id)plus an index. A write naming a missing target is422order.validation_error.customer_id_not_found— Postgres checks it, the use case does not look the target up. Soft deletes leave references pointing at the deleted row. Pg integration tests seed the targets first, through the target’s ownintegration_tests::seed- The list filters by each reference:
GET /orders?customerId=&limit=&offset=→ListOrdersParams { customer_id }→find_all(page, OrderFilter)(one static query,$3::uuid IS NULL OR customer_id = $3) - The frontend: the form’s
<select>lists the target’s first 100 items (labelled by its first requiredStringfield, else its id), the detail links to the target, andcustomer_id_not_foundshows under the select puerto validatechecks that areferencesnames another declared CRUD entity and is aUuidorOption<Uuid>- Runtime:
puerto_core::RepositoryError::MissingReference(field);puerto_sqlx::map_sqlx_error_with(err, &[ForeignKey])maps SQLSTATE23503through the entity’s constraint names (an unknown one staysUnavailable)
📚 Documentation
Section titled “📚 Documentation”- The generated root
AGENTS.mddocuments theref:syntax and how references behave - The website documents references (field types,
puerto.toml, entities and web guides)
Migration Guide
Section titled “Migration Guide”Nothing to migrate: bump the runtime crates to 0.20. To refer to another entity from an
existing one, replace its customer_id:Uuid field with customer_id:ref:Customer and re-scaffold
with --force; the existing table needs an ALTER TABLE … ADD CONSTRAINT … FOREIGN KEY written
with puerto generate migration, since a re-scaffold keeps the existing create migration.
[0.19.1] - 2026-10-13
Section titled “[0.19.1] - 2026-10-13”The agent instructions every project ships, checked against what Puerto writes (PLAN Phase 17).
🐛 Bug Fixes
Section titled “🐛 Bug Fixes”puerto generate scaffold <Name> --forcein a--dbproject (andpuerto generate repositoryon a scaffolded entity) no longer writes a secondcreate_<entity>_tablemigration, which madesqlx migrate runfail on the existing table. The existing migration is kept and the command says how a changed field set is migrated: edit it if it was never applied, elsepuerto generate migrationwith theALTER TABLE. An existing project with a duplicate only needs the newer file deleted (if it was never applied)- The generated
make lintrunsclippy --workspace --all-targets: the project’s test code was never linted. An existing project can add--all-targetsto its Makefile’slinttarget
📚 Documentation
Section titled “📚 Documentation”- The generated root
AGENTS.mdsays how to work with Puerto: every command and when it applies, the field syntax (value objects, enums, shared value objects), which files a generator rewrites and which are yours, how an entity’s fields change once its table exists, the loop (generate, then test first — whatgenerate use-caseleaves to fill in) and a checklist withpuerto validate,make web/syncand the--dbsteps. A test fails when apuerto generatesubcommand is not named there business/AGENTS.mddescribes what a use case file holds (its mock included), the unit of work ofeventsprojects,domain/mailanddomain/user
Release
Section titled “Release”- Publish order:
puerto-core→puerto-macros→puerto-web→puerto-sqlx→puerto-events→puerto-kafka→puerto-mail→puerto-auth→puerto(runtime crates unchanged, republished at the CLI’s version)
[0.19.0] - 2026-10-13
Section titled “[0.19.0] - 2026-10-13”Auth (PLAN Phase 16, ADR-0021): one
Authenticator port, answered by an OpenID Connect provider (Auth0, Keycloak) or by accounts and
sessions in the project’s own database. A project without --auth is generated exactly as in 0.18.
🚀 Features
Section titled “🚀 Features”puerto new --auth oidc: the API verifies the provider’s bearer tokens (RS256/ES256,iss,aud,exp/nbf, JWKS refetched on an unknownkidat most once a minute). Written once and yours: theUserentity (in memory, orPgUserRepositorywith ausersmigration in--db),ProvisioningAuthenticator(a caller becomes aUseron their first request) andGET /me. Keycloak 26.8 indocker-compose.ymlwith a realm of its own (clientweb, PKCE; a dev-only password-grant clientdev-cli;admin@<project>.localhostwithadmin,user@without),AUTH_*in.env,make auth/ui,make -s auth/token [EMAIL=…], an Auth section inAGENTS.mdpuerto new --db --auth local: accounts in Postgres —POST /auth/register,/auth/login(an opaque session token; the row keeps its SHA-256),/auth/logout; argon2id passwords; an unknown email and a wrong password get the same 401 in the same time.AUTH_SESSION_TTL,make auth/grant EMAIL=… ROLE=…- Protected scaffolds: in an auth project every CRUD handler takes
auth: BearerAuth(401auth.unauthenticated, 503auth.unavailable) except--public <uc>,…;--role <uc>=<role>adds#[require_role("<role>")](403auth.forbidden; two roles: both required). Protected params carryactor: Principal; route tests sign in through aMockAuthenticatorand add a 401 per protected route and a 403 per role.generate use-caseprotects the new use case too - The frontend signs in: OIDC through
oidc-client-ts(token in memory,/auth/callback), local through/loginand/register(token inlocalStorage).AuthProvider/useAuth/RequireAuth, a bearer middleware, a user menu; generated routes wrap protected screens in<RequireAuth>and screens hide the actions a role guards (can(role)) puerto.tomlgains[project] auth = "oidc" | "local"and[[entity]] public/roles;puerto validatechecks them and thatroutes.rsstill says the same (BearerAuth,require_role)- New runtime crates
puerto-macros(#[require_role], reached aspuerto_web::require_role) andpuerto-auth(OidcAuthenticator,Argon2Hasher).puerto-core::auth(Principal,Authenticator, the local ports and their mocks),puerto-web::auth(BearerAuth,forbidden(),bearer_token),puerto-sqlx::auth(PgSessions,PgCredentials, theusersandauthmigrations) make test/authruns the OIDC adapter and a generated OIDC project’s API against Keycloak + Postgres;make test/dbruns a local-auth project’s API end to end
🐛 Bug Fixes
Section titled “🐛 Bug Fixes”puerto new --auth oidc --no-democompiles: auth runs after the demo strip
Migration Guide
Section titled “Migration Guide”Nothing to migrate: 0.19 changes no project generated without --auth. Bump the runtime crates to
0.19. In an auth project, User, Me and Auth are reserved entity names.
Release
Section titled “Release”- Publish order:
puerto-core→puerto-macros→puerto-web→puerto-sqlx→puerto-events→puerto-kafka→puerto-mail→puerto-auth→puerto
[0.18.0] - 2026-10-12
Section titled “[0.18.0] - 2026-10-12”Mail (PLAN Phase 14, ADR-0020): a port per mail, its templates in infrastructure, sent by the worker once per event.
🚀 Features
Section titled “🚀 Features”puerto generate mail <name> [-- field:Type …](any project) writes, once and yours from then on:business/src/domain/mail/<name>.rs({Name}Mail+ the port{Name}Mailer+ its mock),infrastructure/src/mail/<name>.rs(Template{Name}Mailer, whose tests render every template — a typo failsmake test) andinfrastructure/mail/<name>/{subject.txt, body.html, body.txt}(minijinja, strict). The first mail addspuerto-mail, Mailpit todocker-compose.yml(created in a project without--db),SMTP_URL/MAIL_FROMin.env,make mail/uiand a Mail section inAGENTS.md--on <event_type> --to <field>(events projects): the worker sends the mail.worker/src/consumers/mail_<name>.rsbuilds it from the event’s snapshot and sends it throughsend_once, which keeps asent_mailsrow per event — a redelivered event does not send it again. 5xx → dead letter, 4xx / refused / timeout → retried with the delivery policy. Wired inregistry.rson both transports with oneSmtpMailerand onePgSentMailspuerto-mail, a new runtime crate:MailConfig::from_env(never prints the password inSMTP_URL),SmtpMailer(lettre over rustls),Templates,send_once, and behindtest-utilsRecordingMailer/InMemorySentMails.puerto-coregainsEmail,Mailer,MailError,SentMails;puerto-sqlxgainsmail::PgSentMailsandSENT_MAILS_MIGRATIONpuerto.tomlgains[[mail]] { name, on }(wiring only);puerto validatechecks names, events and the mail’s files;puerto listshows the mailsmake test/mail(the SMTP adapter against Mailpit);make test/dbandmake test/kafkarun the mail end to end against Mailpit: sent once, skipped when redelivered, retried while SMTP is down
Breaking
Section titled “Breaking”- An entity can no longer be named
Mail: mails own themailmodules ofbusinessandinfrastructure
Migration Guide
Section titled “Migration Guide”No projects generated by 0.17 are known to be in use. To bring one forward: bump the runtime crates
to 0.18, and rename an entity called Mail before running puerto generate mail.
Release
Section titled “Release”- Publish order:
puerto-core→puerto-web→puerto-sqlx→puerto-events→puerto-kafka→puerto-mail→puerto
[0.17.1] - 2026-10-12
Section titled “[0.17.1] - 2026-10-12”🐛 Bug Fixes
Section titled “🐛 Bug Fixes”puerto new --dbdeclarespub mod db;ininfrastructure/src/lib.rsright away. It used to wait for the first scaffold, so a project frompuerto new --db --events db|kafkadid not compile (the worker namesinfrastructure::db). Broken since 0.15; an existing project only needs the line added
Release
Section titled “Release”- Publish order:
puerto-core→puerto-web→puerto-sqlx→puerto-events→puerto-kafka→puerto(runtime crates unchanged, republished at the CLI’s version)
[0.17.0] - 2026-10-12
Section titled “[0.17.0] - 2026-10-12”Developer experience: what a walkthrough of a fresh project found (PLAN Phase 15). The default project now keeps what it is given, a startup failure explains itself, and the web form says what went wrong next to the field.
🚀 Features
Section titled “🚀 Features”- The in-memory repository keeps what it is given — without
--db,POSTanswered 201 andGET /:idthen 404.InMemory{Entity}Repositorynow behaves like the Postgres adapter: deleted rows hidden, lists newest first and paged, a unique value held by another live row answersDuplicate, with generated unit tests for each.make runsays the data is lost on restart - A startup failure is an error message, not a panic —
build_app/build_workerreturnResult<_, String>with a hint per cause (DATABASE_URLin.env,make docker-compose/up, the Kafka broker).puerto-webgainsApp::try_serveandpuerto-eventsWorker::try_run: the error is logged and the process exits 1.puerto_sqlx::DatabaseErrornameshost:port/databaseand the driver’s cause, never the password, and a refused connection is reported at once instead of after the 30 s pool timeout - The web form says what went wrong, next to the field —
domain/<entity>/messages.ts, generated from the same codes aserrors.rs, maps a code to a message and a field;FieldErrorshows it under the input (aria-invalid), other codes go to the alert - Snippets for events projects (
uow-write,app-use-case-uow,consumer-arm), custom endpoints (poem-endpoint-action,poem-route-test) and the frontend (web-container,web-container-test,web-repo-method,web-form-field,web-route) — Zed and VS Code web/src/presentation/core/routes.tsx(customRoutes): your own screens, rendered by the generated route table and never overwritten- The web list keeps its page in the URL (
?page=N): reload and back keep it puerto listshows the events transport, custom events, shared value objects and consumers
🐛 Bug Fixes
Section titled “🐛 Bug Fixes”generate use-caseputs the custom use case’s mock in the route tests’Mocks- A custom use case no longer logs its params (user data); its generated test is
#[ignore = "write this test"]ending intodo!()instead of an empty body that passed
Breaking
Section titled “Breaking”puerto_sqlx::DatabaseError::ConnectionErrorandMigrationErrorare now struct variants ({ target, cause },{ cause });puerto_web::ErrorgainsStartup- Generated
bootstrap.rs/registry.rsreturnResult, andmain.rscallstry_serve/try_run.serveandrunare unchanged: a 0.16main.rscompiles against the 0.17 runtime untilbootstrap.rsis regenerated, then it needstry_serve - The generated web form takes a
problemprop; the generated list reads its page from the URL
Migration Guide
Section titled “Migration Guide”No projects generated by 0.16 are known to be in use. To bring one forward: bump the runtime
crates to 0.17, run puerto generate bootstrap (it also rewrites worker/src/generated/registry.rs),
replace .serve( with .try_serve( in
presentation/src/main.rs and .run( with .try_run( in worker/src/main.rs, and re-run
puerto generate web <Entity> --force for each entity’s screens.
Release
Section titled “Release”- Publish order:
puerto-core→puerto-web→puerto-sqlx→puerto-events→puerto-kafka→puerto
[0.16.0] - 2026-10-12
Section titled “[0.16.0] - 2026-10-12”Fixes from a walkthrough of every command on five generated projects. Generated code is now
formatted as it is written, so a project’s own make format passes.
🐛 Bug Fixes
Section titled “🐛 Bug Fixes”- Generated code passes
cargo fmt --check(ADR-0019) — every command that writes Rust ends withcargo fmt --allin the project; a failed format only warns. A fresh project had 3–7 diffs, one with two scaffolded entities about 200 generate scaffold --forceon an entity that no longer has a local value object removesvalue_objects.rsand itspub mod— the stale file did not compilegenerate presentationbeforeapplication/repository(API first) writes the routes andtags.rsbut leavesbootstrap.rsalone, and names the next step — it used to write a bootstrap that did not compile and print “All layers wired”- Generated Makefile:
docker compose up -d --wait(the firstmake sqlx/migratefailed while Postgres started);make run,make workerandmake test/infrastructurestart the database;test/infrastructuredefined once; colors print whereshis bash;web/*targets ask formake web/installinstead of failing with exit 127 - The migration hint after a scaffold adds
make sqlx/prepare;generate consumer --helpsays--events
Breaking
Section titled “Breaking”- Generated output is reformatted (whitespace and import order only). No migration needed:
cargo fmt --allbrings an existing project to the same layout
Release
Section titled “Release”- Publish order:
puerto-core→puerto-web→puerto-sqlx→puerto-events→puerto-kafka→puerto(runtime crates unchanged, republished at the CLI’s minor)
[0.15.0] - 2026-10-12
Section titled “[0.15.0] - 2026-10-12”Domain events (ADR-0018). In a --db project created with --events db|kafka, every write of a
CRUD entity saves the entity and records its event in an outbox table in one transaction, and a
second process, worker/, relays the outbox to a transport and runs the consumers. Projects
created without --events are generated exactly as in 0.14.
🚀 Features
Section titled “🚀 Features”puerto new --db --events db|kafka—[project] events, the outbox migration, and per CRUD entity a generatedevents.rs({Entity}Snapshot,{Entity}Event,{ENTITY}_CREATED… constants) andunit_of_work.rs. The repository port only reads: writes gouow_factory.begin()→save→record→commit, tested withRecordingUnitOfWorkFactorypuerto generate event <Entity> <name>— a custom event beyond created / updated / deletedworker/— a second binary on the new runtime cratepuerto-events: the outbox relay, one consume loop per consumer with the delivery policy (Ack/Retrywith a 1 s → 300 s backoff / dead letter afterMAX_DELIVERIES),/health+/health/readyonWORKER_PORT, graceful shutdown.generated/registry.rsis regenerated frompuerto.toml;make worker,make events/dead-letterspuerto generate consumer <name> --on <event_type>[,…]—[[consumer]]inpuerto.toml, an idempotentEventHandlerstub with its tests inworker/src/consumers/<name>.rsdbtransport (puerto-sqlx): deliveries are rows in Postgres (event_deliveries), no brokerkafkatransport — the new runtime cratepuerto-kafka(rdkafka, needscmake): one topic per aggregate keyed by its id (the events of one aggregate stay in order), one consumer group per consumer, offsets committed after the outcome, aRetryretried in process without reordering.docker-compose.ymlgains Redpanda and.envKAFKA_BROKERSpuerto-coregains the event envelope,DomainEvent,EventHandler, the delivery policy and the transport ports;puerto validatechecks events and consumers
🐛 Bug Fixes
Section titled “🐛 Bug Fixes”- Web import specifiers are sorted as Biome does (the upper-case letter first), so
bun run lintpasses on entities whose types and helpers share a letter
Release
Section titled “Release”- Publish order:
puerto-core→puerto-web→puerto-sqlx→puerto-events→puerto-kafka→puerto
[0.14.0] - 2026-10-12
Section titled “[0.14.0] - 2026-10-12”The code every generated project shared as a copy now lives in three runtime crates, released in
lockstep with the CLI (ADR-0017): a fix to the server, the health probes or the Postgres error
mapping reaches existing projects through cargo update instead of staying wrong in every
project generated before it. New infrastructure (auth, jobs, mailer, storage) lands there next.
Breaking
Section titled “Breaking”puerto-core—RepositoryError(now#[non_exhaustive]),PageRequest,Page<T>.business/src/domain/shared/{pagination,repository_error}.rsare no longer generated; imports move fromcrate::domain::shared::…topuerto_core::…. Every entity’sFrom<RepositoryError>gains a_arm (→RepositoryError, 500)puerto-web— the server (App::serve: tracing, CORS, banner, graceful shutdown),Config::from_env, the/healthand/health/readyprobes andErrorResponse.presentation/src/main.rsisConfig::from_env()?+App::new(config).serve(build_app);health.rsis gone;api/error.rskeeps only theIntoErrorResponsetrait (the orphan rule keeps it in the project);build_app(config)ends withcrate::app::configure(…)puerto-sqlx(--dbprojects) —create_postgres_pool,run_migrations,ping,map_sqlx_error,DatabaseError(now#[non_exhaustive]).infrastructure/src/db.rsispub use puerto_sqlx::*;plus the project’sMIGRATOR, andbootstrap.rscallsrun_migrations(&pool, &infrastructure::db::MIGRATOR)HARBOR_BANNERis nowPUERTO_BANNER- A set but invalid
SERVICE_PORTorPUERTO_BANNERstops the server at startup instead of silently falling back to the default
🚀 Features
Section titled “🚀 Features”- Runtime requirements are declared once, in the root
Cargo.toml’s[workspace.dependencies]on the CLI’s minor (puerto-core = "0.14"), and inherited by each member with{ workspace = true } presentation/src/app.rs: the project’s own hook,configure(routes) -> impl Endpoint, for middleware and extra routes. Written once bypuerto new, never touched by a generatorpuerto validatewarns when a runtime crate is on another minor than the CLI- The generated root
AGENTS.mdnames each runtime crate and what it owns
Migration Guide
Section titled “Migration Guide”No project generated before 0.14.0 is in use, so the simplest path is to regenerate. For a project you keep, hand this to your coding agent:
Upgrade this Puerto project from 0.13 to 0.14. In the root
Cargo.tomladd[workspace.dependencies]withpuerto-core = "0.14",puerto-web = "0.14"and, ifinfrastructureuses sqlx,puerto-sqlx = "0.14"; add<crate> = { workspace = true }tobusiness,infrastructureandpresentation(puerto-webonly inpresentation,puerto-sqlxonly ininfrastructure). Deletebusiness/src/domain/shared/pagination.rs,shared/repository_error.rsandpresentation/src/health.rs, and replace every import of them withpuerto_core::{Page, PageRequest, RepositoryError}orpuerto_web::ErrorResponse; add a_ => Self::RepositoryErrorarm to eachFrom<RepositoryError>. Copypresentation/src/main.rs,presentation/src/app.rs,presentation/src/api/error.rsand (with a database)infrastructure/src/db.rsfrom a freshpuerto newof the same kind, move any middleware you had inmain.rsintoapp.rs, renameHARBOR_BANNERtoPUERTO_BANNERin.env, then runpuerto generate bootstrap,puerto validateandmake test.
[0.13.0] - 2026-10-11
Section titled “[0.13.0] - 2026-10-11”Three backlog items that a production service needs on day one and cannot cheaply add on day 100: ids that cannot be mixed up, one error type for every repository, and lists that never read a whole table. All three change generated code, hence the minor bump.
Breaking
Section titled “Breaking”- Entity ids are newtypes.
Product.id, the get / update / delete params andfind_by_idtakeProductId(declared inmodel.rs) instead ofUuid. The wire format, the SQL column andweb/are unchanged (ADR-0014) - Repositories return
RepositoryError(business/src/domain/shared/repository_error.rs) instead of the entity’s error; every entity error getsFrom<RepositoryError>. The API’s error codes are unchanged (ADR-0015) list_*is paged.find_all(page: PageRequest) -> Page<Entity>,ListEntitiesParams { page }, andGET /entities?limit=&offset=answers{ items, total, limit, offset }instead of a bare array (ADR-0016)- Shared value objects are declared in
business/src/domain/shared.rs;shared/mod.rsis no longer generated
🚀 Features
Section titled “🚀 Features”- Typed ids:
{Entity}Id::generate(),from_uuid,value()andDisplay; passing another entity’s id is a compile error - One driver-error mapping:
infrastructure::db::map_sqlx_errorturns a23505unique violation intoDuplicate(→409) and anything else intoUnavailable; a row the domain rejects is reported asInvalidDataand logged with the reason. Pg repositories with auniquefield ship an integration test for the duplicate - Paged lists:
PageRequest(default 20, capped at 100 in the domain — no route can bypass it) andPage<T>; Postgres readsORDER BY created_at DESC, id LIMIT/OFFSETplus aCOUNT(*) - Paged screens: the web list screen asks for one page at a time and renders a new
Paginationcontrol (“1–20 of 45”, Previous / Next) - New generated tests: the
From<RepositoryError>arms, a duplicate on create, an unavailable store on get, the page passed through the list use case and route, and the Pg page of a larger table
Migration Guide
Section titled “Migration Guide”No project generated before 0.13.0 is in use, so the simplest path is to regenerate. For a project
you keep: copy business/src/domain/shared.rs and shared/{pagination,repository_error}.rs from a
fresh puerto new, declare pub mod shared; in the domain block of business/src/lib.rs
(replacing shared/mod.rs with shared.rs if you have shared value objects), then re-scaffold
each entity with puerto generate scaffold <Name> --force and make web/sync. Hand-written code
that called find_all() or find_by_id(uuid) needs PageRequest::default() and
{Entity}Id::from_uuid(uuid); a mock returning Err(EntityError::RepositoryError) from a
repository returns Err(RepositoryError::Unavailable).
[0.12.0] - 2026-10-11
Section titled “[0.12.0] - 2026-10-11”Full-stack: every project now ships a React frontend, and scaffold writes each CRUD entity’s
screens next to its Rust layers — Rails-style, but with the same Dependency Rule on both sides and
the OpenAPI spec as the contract between them.
🚀 Features
Section titled “🚀 Features”web/in every new project (puerto new --no-webskips it; the wizard asks): React 19 + daisyUI 5 on Bun, wouter, Vite with/apiproxied to:8080,bun testwith happy-dom and Testing Library, Biome, and dependency-cruiser checkingdomain←infrastructure←presentation.[project] web = truein puerto.toml;make web/install,web/dev,web/test,web/lint;make testandmake lintinclude the frontend (ADR-0013)- The OpenAPI spec is exported to
docs/api/openapi.jsonby a test inbootstrap.rs, built from mocked use cases — no server, no database.make web/syncre-exports it, regenerates the frontend’s wire types (openapi-typescript) and formatsweb/; until thenbun run typecheckfails, which is the drift check - Screens per entity: in a web project,
generate scaffoldwrites the domain types, the repository port, an HTTP repository over openapi-fetch, list / detail / form (create + edit) containers and views, an Object Mother and an in-memory fake, all tested. The route table and the composition root (web/src/presentation/core/generated/) are regenerated from puerto.toml likebootstrap.rs - Every field type has its input: text, number (
step="any"forf64), checkbox,datetime-local, a select for enum value objects (a union type narrowed byparse<Vo>()), a —/Yes/No select forOption<bool>, comma-separated lists, akey=valuetextarea for maps; an empty optional input isnull. Server validation is the authority: the form shows the code the API answers puerto generate web <Name> [--force]: the screens alone, for an entity already in puerto.toml — the last step of the layer-by-layer flow- The overwrite guard covers the frontend files;
puerto validateandgenerate bootstrapreport a CRUD entity whose screens are missing
🐛 Fixed
Section titled “🐛 Fixed”- The
domain-use-caseIDE snippet ships the use case mock (mocks::Mock{Uc}UseCase)
Changed
Section titled “Changed”- A project created without
--no-webneeds Bun formake testandmake lint
🧪 Internal
Section titled “🧪 Internal”- The compile matrix installs, typechecks, lints (Biome before any formatting), tests and builds
the generated frontend of every web scenario; new scenarios
web_crudandweb_every_type - Generated TypeScript comes out Biome-clean: imports sorted and wrapped like Biome, routes wrapped
by width; the per-field frontend decisions live in
types::web_field_ctx
[0.11.0] - 2026-10-11
Section titled “[0.11.0] - 2026-10-11”The last batch of shape changes before the first projects are generated for real: the presentation layer now depends on use case ports and every CRUD route ships with tests, tables and paths use real plurals, and the list use case is named after the plural. Underneath, the generators finished their move to Tera templates — a refactor proven byte-identical by new snapshots of every generated file.
🐛 Fixed
Section titled “🐛 Fixed”- A failed generation step still printed
✓ Done. Zero manual wiring.—scaffoldignored the results of thelib.rspatchers, the Mother and shared VO writers and the puerto.toml / bootstrap update. Every step now propagates its error; render errors name the template, write errors name the path, and no generator panics on a render failure - Plurals:
Categorywas the table and pathcategorys
🚀 Features
Section titled “🚀 Features”- Route tests in every project: the CRUD
routes.rsis generated with tests that drive the realOpenApiServicethroughpoem::test::TestClient, one mocked use case per test, one test per status path (create 201 / 422, get 200 / 404, list 200 / 500, update 200 / 404, delete 204 / 404); the demoGreetingApigets 200 / 422 - Use case mocks: every use case trait ships
mocks::Mock{Uc}UseCasebehindcfg(any(test, feature = "test-utils")), like the repository mocks; Object Mothers compile under the same gate, so other crates’ tests can build entities - Real plurals for SQL tables and REST paths:
categories,boxes,statuses,people,order_items; uncountables (data,series, …) stay as they are
🧪 Internal
Section titled “🧪 Internal”- Snapshot of every generated file, one per compile-matrix scenario (Postgres included), checked
by
make teston every push;make test/snapshotsre-records them after an intended change - Generators render through Tera templates over a per-field
FieldCtx(ADR-0011): templates own the shape of the code,types.rsowns every per-field decision; no type name is hard-coded outside it. Snapshots unchanged throughout make lintcovers test targets; the 6.6k-linetests.rsis split into one module per area- Mutation testing: 0 survivors
Breaking
Section titled “Breaking”Generated code changes shape:
{Entity}Apiholds ports: fields areArc<dyn {Uc}UseCaseTrait>(wereArc<{Uc}UseCaseImpl>);routes.rsno longer importsbusiness::application::*(ADR-0012).presentationdev-depends onbusinesswithtest-utilsand onpoemwithtest- Tables and REST paths use real plurals —
categorys→categories,/categorys→/categories - The list use case is
list_{plural}:list_product→list_products(file, module,ListProductsUseCaseTrait,ListProductsParams,ListProductsUseCaseImpl,ListProductsResponse,ProductApi.list_products, puerto.toml)
Migration Guide
Section titled “Migration Guide”No project generated with an earlier Puerto is known to be in use. For one that is:
- In every
routes.rs, changeArc<{Uc}UseCaseImpl>fields toArc<dyn {Uc}UseCaseTrait>and import the trait frombusiness::domain::{entity}::use_cases::{uc}instead of the impl. Addbusiness = { path = "../business", features = ["test-utils"] }andpoem = { version = "3", features = ["test"] }topresentation’s[dev-dependencies]if you want to add route tests. - For each entity, rename
list_{snake}tolist_{plural}: the use case files indomain/{entity}/use_cases/andapplication/{entity}/, theirpub modlines inbusiness/src/lib.rs, the type names, the{Entity}Apifield and the entry in puerto.toml. Then runpuerto generate bootstrap. - Entities whose plural is irregular (
-y,-s,-x,-ch,-sh,person,child, …): either rename the table with a migration (ALTER TABLE categorys RENAME TO categories;) and tell API clients about the new path, or keep the old name by hand in the repository queries and routes.
[0.10.1] - 2026-10-10
Section titled “[0.10.1] - 2026-10-10”🐛 Fixed
Section titled “🐛 Fixed”- IDE snippets had drifted from the generated code, with nothing tying them to it:
NaiveDateTimewhere projects useDateTime<Utc>(domain-model,persistence-entity), DTOs without camelCase, a Pg repository that swallowed errors and never mapped23505→Duplicate, endpoints without tags or failure logs, an Object Mother with a different API, acfg-testblock whoseArcimport failedmake lint, a repository trait withoutfind_all
🚀 Features
Section titled “🚀 Features”- New snippets:
inmemory-repo,poem-endpoint-get,app-use-case-error-test,poem-error-mapper-test,migration-unique-index(partial),sql-select-active - Snippets are compiled in Puerto’s test suite: an entity is built from snippets alone and must
pass clippy
-D warningsand its tests — in memory (make test/full) and against Postgres, migration and integration tests included (make test/db)
📚 Docs
Section titled “📚 Docs”- The crates.io README told people to
cargo install puerto-framework— the crate’s old name — and documented ascaffold --dbflag that does not exist. Rewritten for 0.10. - Install with
cargo install puerto --locked(README, crate README, website). Without--locked, cargo resolves the newest transitive dependencies, andkstring 2.0.5(via cargo-generate → liquid) now requires Rust 1.96 — so a plaincargo install puertofails on 1.95. puerto new my-appexamples corrected topuerto new --name my-app.
[0.10.0] - 2026-10-10
Section titled “[0.10.0] - 2026-10-10”An end-to-end review generated real projects with every option — --db against a live Postgres
included — and found output that did not compile or did not pass the project’s own make lint.
This release fixes all of it, then adopts the conventions of a hand-written 60k-LOC backend built
on the same architecture (document-api). The compile matrix now runs clippy -D warnings in every
generated project and has a Postgres scenario (make test/db). 0.9.1 and 0.9.2 were tagged but never
reached crates.io; their changes ship here.
🐛 Fixed
Section titled “🐛 Fixed”- A fresh
puerto newfailed its ownmake lint— ~57 clippy errors in a project with value objects (map_errthat returns its input, redundant field names, argument-lessformat!, an inherentfrom_stron enum VOs, unused test imports, Mothers withoutDefault) generate use-caseon a scaffolded entity broke compilation (bootstrap wired a fieldroutes.rsdid not have) and silently replaced a working implementation with atodo!()stub when the action already existed — including the CRUD ones--dbprojects:HashMapcolumns did not compile (nowsqlx::types::Json); Pg repository tests missed imports, compared nanosecond timestamps with microsecond ones and seededuniquefields with constants; two scaffolds in the same second produced the same migration version; a field nameddesc/order/userbroke the migration- Entity whose only
Stringfield is an enum VO: its create test did not compile - Create use case logged the literal text
params.xinstead of a value puerto newsuggestedcargo run -p <name>(the package ispresentation).sqlx/was git-ignored while builds run withSQLX_OFFLINE=true- The AI rules shipped in every project described
mod.rsfiles — the one thing the module convention forbids — and were not loaded by Claude Code (no rootCLAUDE.md)
🚀 Features
Section titled “🚀 Features”- Health and shutdown:
GET /health(liveness),GET /health/ready(readiness —503until the database answers), graceful shutdown on SIGTERM / Ctrl-C - Agent rules: every project ships a root
AGENTS.md+CLAUDE.md— architecture, commands, conventions, one commit per piece, risk tiers for human review — kept in sync by tests - Pinned toolchain:
rust-toolchain.toml(1.95.0), edition 2024, resolver 3 - Validation at the command that writes:
generate value-object(name, type, duplicates),generate use-case(snake_case, existing actions), duplicate field names, SQL reserved words in--dbprojects, project names inpuerto new --name generate migrationwrites the file itself (nosqlxCLI needed) and is refused without--dbmake test/db(Postgres scenario) andmake test/mutation(cargo-mutants: 335 mutants, 0 survivors)docs/adr/— ten Architecture Decision Records
Breaking
Section titled “Breaking”Generated code changes shape:
- No logger port.
LoggerTrait,TracingLogger,business::domain::logger, everyloggerfield andsilent_logger()mock are gone; code logs withtracingmacros. Repository constructors take no logger (InMemoryXRepository::new(),PgXRepository::new(pool)) - Error contract.
ErrorResponse.nameis the error code (product.not_found) — it was a genericproduct_errorwith the code inmessage. Domain validation and invalid value objects answer 422 (was 400); response enums carryUnprocessableEntityinstead ofBadRequest - Enum value objects implement
FromStrinstead of an inherentfrom_str - Unique indexes are partial (
WHERE deleted = false) - Entity names
TracingandDbare rejected;generate use-caseis no longer idempotent (a second run is refused)
Migration Guide
Section titled “Migration Guide”No project generated with an earlier Puerto is known to be in use. For one that is:
- Delete
business/src/domain/logger.rsandinfrastructure/src/logger.rsand theirpub modlines; removeloggerfields and arguments; replaceself.logger.info(&x)withtracing::info!(…); addtracing = "0.1"tobusinessandpresentation. - Run
puerto generate bootstrap. - In each
error_mapper.rs, build bodies withErrorResponse::from_code(self.to_string())and mapValidationError/Invalid*toStatusCode::UNPROCESSABLE_ENTITY; inresponses.rsreplace the400 BadRequestvariant with422 UnprocessableEntity. Tell API clients that the code is now inname. - Replace
Vo::from_str(&x)withx.parse::<Vo>()(or importstd::str::FromStr). - Recreate unique indexes as partial:
DROP INDEX t_f_key; CREATE UNIQUE INDEX t_f_key ON t (f) WHERE deleted = false;
[0.9.2] - 2026-08-15
Section titled “[0.9.2] - 2026-08-15”Two rounds of work: making generated projects actually compile, and making the CLI honour what the
docs already promised. A compile matrix now gates both — it generates real projects, scaffolds into
them and runs cargo test --workspace inside, which is how the bugs below were found.
🐛 Fixed
Section titled “🐛 Fixed”Option<VO>andVec<VO>emitted model tests that did not compile — the test-props builders branched only on enum/plain VOs, soOption<VO>gotVO::new(None)andVec<VO>gotVO::new(vec![]), both with the wrong inner typepuerto new --no-demodroppedpub mod tags;frompresentation/src/api.rs, breaking the first scaffold into an empty project- An entity with no use cases emitted syntactically invalid
bootstrap.rs(EntityApi { , logger: … }) DateTime<Utc>/Uuidfields re-imported chrono and uuid in the model (E0252)get/list/deletetest modules missed field-type imports (E0433)- DTOs used
DateTime/HashMapwith no import, no chrono dependency and no poem-openapi chrono feature unique = truenever reached the SQL migration. It is documented inAGENTS.md, exposed as the!CLI suffix, and did nothing. Now emitsCREATE UNIQUE INDEX {table}_{field}_key— a named index rather than an inline columnUNIQUE, so a later migration can drop it by a predictable name. This also makes the23505→EntityError::Duplicatemapping in the Pg repository reachable for the first timepuerto generate domaincould never receive typed fields. A deadfindguaranteed an empty field list, and the entity was registered withfields: []— soapplication,repositoryandpresentation, which all read fields back frompuerto.toml, were field-blind. The entire documented domain-first workflow could only ever produce the defaultname: Stringentity
🚀 Features
Section titled “🚀 Features”puerto generate scaffoldno longer overwrites silently. Re-scaffolding an entity that has generated files is refused: interactively it lists the files and asks, non-interactively it aborts without writing a byte.--forceoverwrites and updates the[[entity]]block in place, so the manifest keeps describing the code on disk — use cases added viagenerate use-casesurvivepuerto generate domain <Name> -- fieldstakes the same field syntax asscaffoldand persists the fields topuerto.toml, which is what makes the later layered commands field-aware- Manifest / filesystem drift detection.
puerto validatenow errors when a declared[[entity]]has no code on disk (naming the missing paths and the command that fixes it) and warns on the inverse — a domain module with no[[entity]]block.puerto generate bootstraprefuses to write a bootstrap that will not compile;--allow-missingwrites it anyway puerto --version. The flag was documented in the install instructions and did not exist — clap never generated it becauseversionwas absent from#[command(...)]- Stricter name validation, applied identically by the CLI parser and
puerto validate: system field names (id,created_at,updated_at,deleted,deleted_at), Rust keywords, entity names that collide with generated code (Error,String,Logger,Type, …), duplicate enum variants, and two fields declaring the same value object with different inner types
🚜 Refactor
Section titled “🚜 Refactor”- New
generators/conflict.rs— the overwrite guard, checked before the first byte is written - New
generators/consistency.rs— the manifest/filesystem pass, covering exactly the filesbootstrap.rsimports - New
validation.rs— one home forSYSTEM_FIELDS,RUST_KEYWORDS, reserved type and module names, and the name predicates. Called fromparse_field_arg, fromrun_validateand before any scaffold write, so the two can no longer diverge - The
-- fieldsplumbing is a singleparse_cli_fields()shared byscaffoldanddomain
make test/fullruns on every push and pull request, not only on tag push. It used to be tag-only, which is how three separate bugs that produced non-compiling projects reachedmain- The compile matrix covers primitives,
Option/Vecprimitives, plain and unique value objects,Option/Vec/enum/shared value objects, multiple entities,--no-demo, and the domain-first layered flow with fields
📚 Documentation
Section titled “📚 Documentation”- Swept the drift between the docs and the CLI: the
scaffold --dbflag that no longer exists, the oldname:Name[vo:String]value object syntax,crates/template/basic/,scaffold.rsdescribed as the home of the writers, and tests described as living inmain.rs. Everycrates/-relative path inAGENTS.mdand.claude/rules/*is now verified to exist - The landing docs now document that re-running
scaffoldis refused, and what--forcedoes
💥 Breaking
Section titled “💥 Breaking”- Field names with a leading underscore are rejected.
_private:Stringused to parse. The predicate allowed it while its own error message said otherwise, and a leading underscore reads as “deliberately unused” to every Rust reader. - Re-running
puerto generate scaffold <Name>on an existing entity is refused instead of overwriting. Non-interactive callers (CI, scripts) now get a non-zero exit. puerto generate bootstraprefuses whenpuerto.tomldeclares an entity whose code is not on disk, instead of writing a file that does not compile.puerto validatefails on inputs it used to accept: system field names, Rust keywords, reserved entity names, duplicate enum variants, incoherent value objects, and declared-but- unscaffolded entities.
Migration Guide
Section titled “Migration Guide”Existing projects need no file changes. The commands are stricter, so adjust any automation:
-
Scripts that re-run
scaffoldto regenerate an entity must pass--force:puerto generate scaffold Product --force -- name:String price:i64Without it the command exits non-zero and writes nothing.
-
Run
puerto validateonce and fix what it reports. The new checks catch manifests that were already producing code that does not compile:- a field named
id/created_at/updated_at/deleted/deleted_at→ rename it; every entity already has those - a field named after a Rust keyword (
type,match,move, …) → rename it - a field name starting with
_→ rename it - an entity named
Error,String,Logger,Type, … → rename it - an entity declared in
puerto.tomlbut never scaffolded → run the commandvalidatesuggests, or delete the[[entity]]block
- a field named
-
If
puerto generate bootstrapnow refuses, the manifest and the filesystem disagree. Fix the drift it names.--allow-missingrestores the old behaviour if you genuinely want the file written anyway. -
SQL projects with
unique = truefields: the constraint was never generated, so existing tables do not have it. New scaffolds emit it. To add it to an existing table:CREATE UNIQUE INDEX products_sku_key ON products (sku);
[0.8.0] - 2026-05-04
Section titled “[0.8.0] - 2026-05-04”🚀 Features
Section titled “🚀 Features”- Entity fields in
puerto.toml— define typed fields on entities via[[entity.fields]]blocks. Generated model structs, Props, Params, DTOs, repository rows, and SQL migrations all derive from the field list automatically - Type registry — 13 Rust types supported out of the box:
String,i64,bool,f64,Uuid,DateTime<Utc>,Option<T>,Vec<T>,HashMap<String, String>, and their nullable/array variants. Each type maps to SQL column types, OpenAPI formats, and default test values - Scaffold with fields —
puerto generate scaffold Product name:String price:i64! sku:Stringpasses typed fields via CLI. Fields are persisted topuerto.tomland used across all layers puerto validate— new command that validatespuerto.toml: entity names (PascalCase), field names (snake_case), field types (against the type registry), duplicate entities/fields, and warns aboutOption+uniquecombinations- Dynamic generators — all layer generators now produce typed code from the field list. When
fieldsis empty, the previousname: Stringdefault is preserved for backward compatibility - Field-aware Object Mother —
ProductMothergenerates builder methods for each custom field (with_price(),with_empty_name(), etc.) instead of justwith_name()
🚜 Refactor
Section titled “🚜 Refactor”- Replaced string-constant generators with dynamic functions across all layers (
generate_model(),generate_mother(),generate_crud_dto(),generate_crud_routes(),generate_infra_entity(),generate_crud_infra_db_repository()) - Added
generators/types.rsmodule withTypeMappingregistry,resolve_type(),validate_fields(),collect_imports() - Added
commands/validate.rsmodule with full puerto.toml validation
[0.7.2] - 2026-05-04
Section titled “[0.7.2] - 2026-05-04”Changed
Section titled “Changed”- Refactor: split
main.rsandscaffold.rsinto dedicated modules (commands,generators,patchers,tests)
[0.7.0] - 2026-05-03
Section titled “[0.7.0] - 2026-05-03”💥 Rebranding — puerto-framework → puerto
Section titled “💥 Rebranding — puerto-framework → puerto”This release marks the rename of the crate from puerto-framework to puerto.
The name Puerto was taken by many existing tools, making SEO and discoverability difficult. Puerto (Spanish for port) keeps the original nautical metaphor, is easy to pronounce in English, and has a unique presence on crates.io.
What changed:
- Crate name on crates.io:
puerto-framework→puerto - GitHub repo:
Guuri11/puerto→Guuri11/Puerto - Everything else is identical — CLI commands, generated project structure,
puerto.tomlschema
Migrating:
[dependencies]# beforepuerto-framework = "0.6"# afterpuerto = "0.7"The puerto-framework crate on crates.io is now deprecated. No further versions will be published under that name.
[0.6.0] - 2026-05-03
Section titled “[0.6.0] - 2026-05-03”🚀 Features
Section titled “🚀 Features”- Add
puerto generate domain <Name>— scaffolds domain layer only (model, errors, repository trait, use cases, Object Mother) and adds entity topuerto.toml - Add
puerto generate application <Name>— scaffolds application layer only (use case impls) for an entity already inpuerto.toml - Add
puerto generate repository <Name>— scaffolds infrastructure layer only (InMemory or Pg repository, inferred frompuerto.toml) - Add
puerto generate presentation <Name>— scaffolds presentation layer only (routes, dto, responses, error_mapper) and regeneratesbootstrap.rs - Object Mother test factory (
{Entity}Mother) is now generated bypuerto generate domainandpuerto generate scaffold— providesrandom(),random_vec(n), builder chain, andbuild_props()helpers - Generated project Makefiles overhauled: ANSI colour output, 20+ targets, split test targets (
test/domain,test/application),check,clean,audit,audit/fix,format/fix,generate/entity,generate/use-case,generate/bootstrap - DB project Makefiles now include a full SQLx suite:
sqlx/online,sqlx/offline,sqlx/migrate,sqlx/prepare,sqlx/check,generate/migration; Docker helpersdocker-compose/up,docker-compose/down,db-up,db-down, and areset-dbtarget with destroy confirmation - Puerto root
Makefileupdated with ANSI colours,format/fix,audit,audit/fixtargets - Generated project
AGENTS.mdfiles updated with Object Mother docs and layer-by-layer command guidance
📚 Documentation
Section titled “📚 Documentation”/docspage: added “Layer Generators” section documenting all four new per-layer commandsAGENTS.md(puerto root): CLI commands table updated with four newpuerto generatecommands- Template
AGENTS.mdfiles updated to reference per-layer generators for AI-assisted development
[0.5.0] - 2026-04-27
Section titled “[0.5.0] - 2026-04-27”🚀 Features
Section titled “🚀 Features”puerto generate scaffoldnow infers--dbfrompuerto.toml(project.db = true) — no need to pass the flag when the project already uses SQLx- Interactive
puerto newdemo prompt: shows a real project preview (my-app) before asking for the actual project name - Bump to v0.5.0
[0.4.0] - 2026-04-27
Section titled “[0.4.0] - 2026-04-27”🚀 Features
Section titled “🚀 Features”- Generated projects now print a Puerto ASCII banner on startup (set
HARBOR_BANNER=falseto suppress) - HTTP request logging via poem’s
Tracingmiddleware — every request/response is traced automatically InMemoryRepositoryreceives the project logger; repository-level operations are now logged atdebugGreetingApi(and all generated*Apistructs) receive the logger; errors are logged atwarnuuidandchronotemplate dependencies now includeserdefeatures for JSON serialisation out of the boxpoem-openapitemplate dependency now includesuuidfeature for typed UUID path/query params
💥 Breaking
Section titled “💥 Breaking”InMemoryGreetingRepositoryis no longer a unit struct — constructor is nowInMemoryGreetingRepository::new(logger: Arc<dyn LoggerTrait>). Updatebootstrap.rsin existing projects (or runpuerto generate bootstrap).GreetingApi(and all scaffolded*Apistructs) now require alogger: Arc<dyn LoggerTrait>field. Updatebootstrap.rsin existing projects.build_app()ingenerated/bootstrap.rsis nowasyncand returnsimpl poem::Endpoint(wasRoute). Updatemain.rstogenerated::bootstrap::build_app().await.
🐛 Bug Fixes
Section titled “🐛 Bug Fixes”puerto new --dbnow correctly writesproject.db = truetopuerto.toml— was silently omitted, causingpuerto generate scaffold --dbto not detect db mode correctly
⚙️ Miscellaneous Tasks
Section titled “⚙️ Miscellaneous Tasks”- Test coverage: add
db_project_puerto_toml_has_project_db_trueandno_db_project_puerto_toml_omits_project_dbstructural tests
[0.3.0] - 2026-04-25
Section titled “[0.3.0] - 2026-04-25”🚀 Features
Section titled “🚀 Features”- Add
puerto generate snippets [--ide zed|vscode]command — writes TextMate-format snippet files for Zed (.zed/snippets/rust.json) and VS Code (.vscode/puerto.code-snippets), compatible with nvim+LuaSnip puerto newnow automatically writes snippet files to both IDEs on project creation- 23 Puerto-adapted snippets covering all DDD layers: domain model, errors, repository trait, use case trait/impl, persistence entity/repo, tokio test, sqlx integration test, Object Mother, and more
🐛 Bug Fixes
Section titled “🐛 Bug Fixes”- Fix
cargo fmtviolation inscaffold.rs(apply_db_to_new_projectmethod chain formatting)
📚 Documentation
Section titled “📚 Documentation”- Add IDE Snippets section to
/docspage with snippet inventory, IDE setup instructions, and regeneration commands
[0.2.0] - 2026-04-25
Section titled “[0.2.0] - 2026-04-25”🚀 Features
Section titled “🚀 Features”- Add
LoggerTraitdomain port withnoop()helper and mockall mock - Add
TracingLoggerinfrastructure adapter backed by thetracingcrate - Wire logger into all generated
UseCaseImplstructs andbootstrap.rs - Initialize
tracing_subscriberwith env-filter in generatedmain.rs - Add
--no-dbflag topuerto new(explicit opt-out without prompting) - Add
--destinationflag topuerto new(controls output directory) - Generate
docker-compose.ymland.envfor--dbprojects - Add db Makefile targets:
docker/up,sqlx/migrate,sqlx/prepare, etc. - Run migrations automatically on bootstrap startup (
run_migrations) - Add
uuid,chrono,serde,tracing,dotenvyto template dependencies
💥 Breaking
Section titled “💥 Breaking”- All generated
UseCaseImplstructs now require alogger: Arc<dyn LoggerTrait>field. Existing projects must add this field manually and updatebootstrap.rs(or runpuerto generate bootstrap).
🐛 Bug Fixes
Section titled “🐛 Bug Fixes”- Correct repo URL, install command, and Rust version in landing
🚜 Refactor
Section titled “🚜 Refactor”- Remove redundant crates/template, clean CLI output
📚 Documentation
Section titled “📚 Documentation”- Update release.md crate name and AGENTS.md make commands
- Fix install command in README (puerto-framework)
⚙️ Miscellaneous Tasks
Section titled “⚙️ Miscellaneous Tasks”- Add CI and release GitHub Actions workflows
[0.1.0] - 2026-04-12
Section titled “[0.1.0] - 2026-04-12”🚀 Features
Section titled “🚀 Features”- Auto-wire DI via puerto.toml + generated bootstrap
🐛 Bug Fixes
Section titled “🐛 Bug Fixes”- Rename template Cargo.toml to .liquid to fix crates.io packaging
⚙️ Miscellaneous Tasks
Section titled “⚙️ Miscellaneous Tasks”- Rename crate to puerto-framework for crates.io