milpa-core 0.3.1__tar.gz

milpa_core-0.3.1/.dockerignore

@@ -0,0 +1,17 @@
+# Entorno y caches locales (la imagen instala sus propias dependencias).
+.venv/
+__pycache__/
+*.pyc
+*.pyo
+
+# Secretos y datos que NUNCA deben entrar a la imagen (se montan como volumen).
+.env
+secrets/
+logs/
+
+# Cosas del editor / control de versiones.
+.idea/
+.git/
+.gitignore
+.claude
+README.md

milpa_core-0.3.1/.env.example

@@ -0,0 +1,118 @@
+# Copia este archivo a .env y ajusta. Estos valores asumen ejecución en DOCKER.
+# Si corres en el HOST (uv run), usa localhost/127.0.0.1 en las URLs.
+
+# --- Infraestructura ---
+DATABASE_URL=mysql+pymysql://<user>:<password>@<host>:<port>/<database>
+
+# --- Colas / broker-agnostic (ver docs/research/broker_agnostic_plan.md) ---
+# BROKER_URL: vacío => redis local por default. Solo se usa para lo ENCOLADO (los
+# flujos síncronos no lo tocan). Cambia el transporte sin tocar código:
+#   Redis:    redis://localhost:6379/0
+#   RabbitMQ: amqp://guest:guest@localhost:5672//      (docker compose ya lo levanta)
+BROKER_URL=
+# Result backend: OPCIONAL (crons fire-and-forget). Vacío => sin backend.
+RESULT_BACKEND_URL=
+# Store de locks para without_overlapping (redis). Vacío => redis local por default.
+LOCK_URL=
+# Reintentos de tasks ante fallos TRANSITORIOS (backoff exponencial con jitter). Son los
+# DEFAULTS de retry_policy(); se pueden pisar A MANO en código por-task. Solo afectan a
+# tasks que OPTAN por reintentar (autoretry_for), NUNCA a crons. 0 => sin reintentos.
+TASK_MAX_RETRIES=3
+TASK_RETRY_BACKOFF=2          # segundos base del 1er reintento (luego se duplica)
+TASK_RETRY_BACKOFF_MAX=600    # tope del backoff entre reintentos (10 min)
+#
+# CLOUD (EDUCATIVO / EN CONSTRUCCIÓN — basado en docs, NO probado en docker, sin
+# mantenimiento garantizado estos primeros meses; solo de referencia):
+#   AWS SQS:   BROKER_URL=sqs://<AWS_KEY>:<AWS_SECRET>@        (dep: celery[sqs])
+#   Azure SB:  BROKER_URL=azureservicebus://<SAS>@<namespace>  (dep: azure-servicebus)
+#   GCP Pub/Sub: BROKER_URL=gcpubsub://projects/<PROJECT_ID>   (dep: celery[gcpubsub])
+# ActiveMQ NO es compatible con Celery (AMQP 1.0). Usa RabbitMQ como MQ.
+# Si se omite, el default es la zona del HOST. IMPORTANTE fijarla explícita: un
+# server suele estar en UTC y quien lo monta puede no ser quien programa.
+TIMEZONE=America/Mexico_City
+APP_ENV=local
+# Nombre del proyecto (el default del framework es genérico "App"; pon el tuyo).
+APP_NAME="My App"
+# Locale de fallback de i18n (correos, API, etc.) cuando no se pasa uno explícito.
+APP_FALLBACK_LOCALE=es
+# Locale de Faker para factories/seeders (datos falsos). Cualquier locale de Faker:
+# es_MX, es_ES, en_US, pt_BR, ... Default: es_MX.
+FAKER_LOCALE=es_MX
+# NUNCA en true contra la BD legacy (no debe crear/alterar tablas).
+AUTO_CREATE_TABLES=false
+# Puerto del servidor FastAPI (uvicorn --port).
+APP_PORT=8000
+
+# --- HTTP / middlewares (coma-separados; defaults SEGUROS si se omiten) ---
+# CORS: vacío => NO se monta (same-origin). En dev pon el origin de tu front:
+CORS_ALLOW_ORIGINS=          # ej: http://localhost:3000,https://app.tudominio.com
+CORS_ALLOW_METHODS=*         # en prod restringe: GET,POST,PUT,DELETE
+CORS_ALLOW_HEADERS=*
+CORS_ALLOW_CREDENTIALS=false # true requiere orígenes explícitos (no "*")
+# TrustedHost: "*" = off. En prod fija dominios (anti Host-header attack):
+TRUSTED_HOSTS=*              # ej: api.tudominio.com,*.tudominio.com
+# GZip: off por default (mejor en nginx/proxy en prod).
+GZIP_ENABLED=false
+# Security headers (defensivos). El trío seguro (nosniff/X-Frame-Options/Referrer-Policy)
+# va ON por default; todo es apagable. HSTS OFF por default: enciéndelo SOLO sirviendo
+# HTTPS (en prod, tras TLS). CSP vacío = no se manda (es específico de cada app).
+SECURITY_HEADERS_ENABLED=true
+SECURITY_FRAME_OPTIONS=DENY        # DENY | SAMEORIGIN | "" (no mandar)
+SECURITY_REFERRER_POLICY=no-referrer
+HSTS_ENABLED=false                 # true SOLO con HTTPS (en prod)
+HSTS_MAX_AGE=31536000
+HSTS_INCLUDE_SUBDOMAINS=true
+CONTENT_SECURITY_POLICY=           # ej: default-src 'self'
+# Errores en formato RFC 9457 (application/problem+json). Base del campo `type`: vacío =>
+# "about:blank". Si publicas docs de errores, apúntalo: https://tudominio.com/problems
+PROBLEM_BASE_URL=
+
+# --- Auth propia (login de milpa: JWT API + sesión cookie) ---
+AUTH_GUARD=jwt                 # guard por default: jwt | session | passport
+AUTH_USER_MODEL=milpa.Models.User.User
+JWT_SECRET=                    # OBLIGATORIO para emitir/validar JWT propios (genera uno largo y aleatorio)
+JWT_ALGORITHM=HS256
+JWT_TTL_SECONDS=3600
+# Prefijo de TODAS las cookies. Si SESSION_COOKIE/CSRF_COOKIE quedan vacíos, se derivan como
+# <COOKIE_PREFIX>_session / <COOKIE_PREFIX>_csrf. Default: milpa.
+COOKIE_PREFIX=milpa
+# Sesión cookie (carril browser/HTMX). SESSION_SECRET vacío => no se monta la sesión.
+# HttpOnly siempre; SESSION_SECURE=true en prod (HTTPS).
+SESSION_SECRET=                # genera uno largo y aleatorio para usar el guard 'session'
+# SESSION_COOKIE=              # vacío => <COOKIE_PREFIX>_session
+SESSION_TTL_SECONDS=1209600    # 14 días
+SESSION_SECURE=false           # true en PROD (HTTPS)
+SESSION_SAME_SITE=lax          # lax | strict | none
+# CSRF (double-submit): protege el carril cookie/sesión; exime bearer/JWT.
+CSRF_ENABLED=true
+# CSRF_COOKIE=                 # vacío => <COOKIE_PREFIX>_csrf
+CSRF_HEADER=X-CSRF-Token
+
+# --- Auth: validar tokens OAuth2 de Laravel Passport (tokens EXTERNOS, migración) ---
+# Copia la llave pública del legacy (storage/oauth-public.key) a ./secrets/
+# y apunta aquí a su ruta.
+PASSPORT_PUBLIC_KEY_PATH=/secrets/oauth-public.key
+# PASSPORT_EXPECTED_AUDIENCE=
+
+# --- Logging (Loguru) ---
+LOG_LEVEL=INFO
+# LOG_JSON=true agrega logs/app.jsonl (JSON Lines) para Loki/Grafana.
+LOG_JSON=false
+
+# --- Correo ---
+# MAIL_DRIVER: cómo se manda.  smtp = SMTP real | log = lo escribe en el log (dev sin
+# SMTP, cross-platform) | null = no-op (lo descarta).
+MAIL_DRIVER=smtp
+# En local apunta a Mailpit (puertos del docker-compose).
+MAILPIT_SMTP_PORT=1025
+MAILPIT_UI_PORT=8025
+MAIL_HOST=<host>           # ej. localhost (host) o mailpit (docker)
+MAIL_PORT=1025
+MAIL_USERNAME=
+MAIL_PASSWORD=
+MAIL_ENCRYPTION=          # "" sin cifrado (Mailpit) | tls (STARTTLS) | ssl (SMTPS)
+MAIL_FROM_ADDRESS=no-reply@example.com
+MAIL_FROM_NAME="My App"
+# Destinatarios de sistema (fallback si system_config no trae el name; CCO por APP_ENV si vacío).
+ADMIN_SYSTEM_MAILS=
+MAIL_CCO_RECIPIENT=

milpa_core-0.3.1/.github/workflows/ci.yml

@@ -0,0 +1,65 @@
+name: CI
+
+# Corre los MISMOS guardrails que en local (README §7) en cada push a main y en cada PR.
+# Sin `docker build`: por diseño la app NO va en Docker (README §5; Docker solo infra).
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+# Cancela corridas viejas del mismo ref si llega un push nuevo.
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  quality:
+    name: Lint + Types + Imports + Tests
+    runs-on: ubuntu-latest
+    # Sin .env en CI: damos un sqlite dummy explícito (DATABASE_URL ya tiene default, pero
+    # lo dejamos claro). Basta para importar (el engine es perezoso) y los tests son sin BD.
+    env:
+      DATABASE_URL: "sqlite://"
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+
+      - name: Instalar uv (con Python 3.14 + caché)
+        uses: astral-sh/setup-uv@v8.1.0
+        with:
+          python-version: "3.14"
+          enable-cache: true
+
+      - name: Sincronizar dependencias (incluye grupo dev; reproducible con el lock)
+        run: uv sync --frozen
+
+      # Los 5 guardrails, en pasos separados para ver de un vistazo cuál falla.
+      - name: Ruff format (solo verifica)
+        run: uv run ruff format --check .
+
+      - name: Ruff lint
+        run: uv run ruff check .
+
+      - name: Mypy (estricto)
+        run: uv run mypy
+
+      - name: Fronteras entre módulos (import-linter)
+        run: uv run lint-imports
+
+      - name: Pytest (rápidos, sin BD)
+        run: uv run pytest
+
+      # --- Gates de empaquetado (Fase D): el wheel se construye e instala/usa en limpio ---
+      - name: Build sanity (uv build construye sdist + wheel)
+        run: uv build
+
+      - name: Smoke de instalación (wheel limpio + scaffolder milpa new)
+        run: |
+          uv venv /tmp/milpa-smoke
+          uv pip install --python /tmp/milpa-smoke/bin/python dist/*.whl
+          /tmp/milpa-smoke/bin/python -c "import milpa; print('milpa', milpa.__version__)"
+          ( cd /tmp && /tmp/milpa-smoke/bin/milpa new smokeapp )
+          test -f /tmp/smokeapp/app/Modules/Hello/Http/HelloController.py
+          # El controller generado debe IMPORTAR (ejecuta @Controller/@Get): cubre que el
+          # skeleton no esté roto, no solo que el archivo exista.
+          ( cd /tmp/smokeapp && /tmp/milpa-smoke/bin/python -c "import app.Modules.Hello.Http.HelloController; print('scaffolder OK')" )

milpa_core-0.3.1/.github/workflows/release.yml

@@ -0,0 +1,54 @@
+name: Release (PyPI)
+
+# Publica a PyPI cuando empujas un tag de versión (p. ej. `git tag v0.3.0a0 && git push --tags`).
+# Usa Trusted Publishing (OIDC): NO hay tokens ni secretos — PyPI confía en este workflow.
+# Requisito una sola vez: configurar el "pending publisher" en PyPI (ver docs/prerelease/07).
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  release:
+    name: Build + Publish (Trusted Publishing OIDC)
+    runs-on: ubuntu-latest
+    # 'environment' protege el publish: puedes exigir aprobación manual en Settings → Environments.
+    environment: pypi
+    permissions:
+      id-token: write # OBLIGATORIO para OIDC (Trusted Publishing, sin tokens)
+      contents: read # con un bloque permissions explícito, GitHub recorta el resto a 'none'
+    env:
+      DATABASE_URL: "sqlite://"
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+
+      - name: Instalar uv (Python 3.14 + caché)
+        uses: astral-sh/setup-uv@v8.1.0
+        with:
+          python-version: "3.14"
+          enable-cache: true
+
+      - name: Sincronizar dependencias (reproducible con el lock)
+        run: uv sync --frozen
+
+      # --- Los 5 guardrails ANTES de publicar: no se publica algo roto ---
+      - name: Ruff format
+        run: uv run ruff format --check .
+      - name: Ruff lint
+        run: uv run ruff check .
+      - name: Mypy
+        run: uv run mypy
+      - name: Import-linter
+        run: uv run lint-imports
+      - name: Pytest
+        run: uv run pytest
+
+      - name: Construir sdist + wheel
+        run: uv build --no-sources
+
+      # uv detecta el OIDC de GitHub Actions y publica vía Trusted Publishing (sin tokens).
+      # (el default es --trusted-publishing automatic; no se pasa flag).
+      # Tip primer release: si falla el OIDC, cambia temporalmente a
+      # `uv publish --trusted-publishing always` para ver el error exacto.
+      - name: Publicar a PyPI
+        run: uv publish

milpa_core-0.3.1/.gitignore

@@ -0,0 +1,45 @@
+# Entorno Python
+.venv/
+__pycache__/
+*.pyc
+*.pyo
+
+# Caches de herramientas (se regeneran solas; NO se versionan). graphify también las
+# IGNORA al indexar porque respeta .gitignore — antes ensuciaban el grafo con nodos basura.
+.import_linter_cache/
+.ruff_cache/
+.pytest_cache/
+.mypy_cache/
+.claude/settings.local.json
+
+# Secretos y configuración local (NUNCA al repo)
+.env
+# Ignora TODO el contenido de secrets/ (llaves, etc.) pero conserva la carpeta vacía.
+secrets/*
+!secrets/.gitkeep
+
+# Logs (no versionamos contenido, sí la carpeta)
+logs/*
+!logs/.gitkeep
+
+# BD sqlite local (p. ej. la del demo: DATABASE_URL=sqlite:///milpa.db)
+*.db
+*.sqlite3
+
+# Runtime: PID del servidor web (lo escribe start.sh, lo lee stop.sh)
+app.pid
+
+# Handoff local entre sesiones (estado actual + pendientes); NO se versiona.
+NEXT_SESSION.md
+
+# Editor / SO
+.idea/
+.DS_Store
+docs/
+
+# Sitio generado por MkDocs (se construye en CI; no se versiona)
+site/
+
+# Artefactos de build/empaquetado (uv build)
+/dist/
+*.egg-info/

milpa_core-0.3.1/CHANGELOG.md

@@ -0,0 +1,146 @@
+# Changelog
+
+Todos los cambios notables de **milpa** se documentan aquí.
+
+El formato sigue [Keep a Changelog](https://keepachangelog.com/es-ES/1.1.0/) y el proyecto usa
+[Versionado Semántico](https://semver.org/lang/es/). En `0.x` la API puede cambiar entre minors.
+
+## [Unreleased]
+
+## [0.3.1] - 2026-06-02
+
+Primer release **publicado a PyPI**. Consolida el paquete instalable (extraído en `0.3.0a0`) con el
+set completo de patrones estilo milpa, la API REST estilo DRF, el demo integral y el manual.
+
+### Added
+
+- **Patrones estilo milpa** (OPT-IN, auto-descubribles): `Events`/`Observers` (1:N, transporte
+  adaptativo worker/síncrono), `Mediator` (command bus 1:1, transport-neutral HTTP+CLI) y `Pipeline`
+  (modelo cebolla). No impuestos: patrones que un arquitecto puede sugerir.
+- **Background**: `@job` (on-demand, `.dispatch()`) separado a propósito de `@cron_task` (agendado).
+- **API REST (estilo DRF)**: versionado (`@Controller(version="v1")`), rate limiting (`@rate_limit`),
+  filtering DSL (`FilterQueryModel`) + paginación por cursor, negociación de contenido (una ruta
+  sirve JSON o HTML según `Accept`) y serializers Pydantic v2 (`computed_field`).
+- **Módulo `Demo`** integral (reemplaza a `Example`): users/notes ejercitando auth dual, RBAC+ABAC,
+  los tres patrones, correos por evento + mailables firmados, y UI HTMX + Alpine + Pico.css.
+- **Manual** ampliado (mkdocs): eventos/observers, mediator, pipeline, jobs, versionado, rate
+  limiting, filtrado/paginación, negociación de contenido, serializadores y errores RFC 9457.
+- **Skeleton del scaffolder**: `.env.example` con sección de correo (`MAIL_DRIVER=log` por default,
+  que imprime en la terminal de `jornal serve`; Mailpit para inbox web) y `docker-compose.yml`
+  (redis + mailpit) para la infra de dev.
+
+### Fixed
+
+- **`milpa new --demo` funciona out-of-the-box**: `faker` se incluye en el grupo dev del proyecto
+  generado y `Core/Database/Faker.py` da un error accionable si falta (las factories/seeders lo
+  necesitan; es dependencia de dev, no de producción).
+
+### Changed
+
+- Heredado de `0.3.0a0`: `DATABASE_URL` con default `sqlite`, `pymysql` movido al extra
+  `milpa-core[mysql]` (core agnóstico de dialecto), y el paquete importable `app` → `milpa`.
+
+## [0.3.0a0] - 2026-06-01
+
+Primera versión **INSTALABLE**: milpa se extrae como paquete (`pip install milpa-core`) con un
+scaffolder de proyectos. Alpha — la API puede cambiar entre versiones.
+
+### Added
+
+- **Paquete instalable** (`pip install milpa-core` / `uv add milpa-core`): src-layout (`src/milpa`),
+  `[build-system]` hatchling, comando de consola `milpa`, versión single-source en `__init__`.
+- **`milpa new <app>`** — scaffolder que genera un proyecto listo para correr (estilo
+  `laravel new` / `django-admin startproject`) desde un skeleton embebido en el paquete.
+- **Config-seam**: el Core resuelve módulos/modelos/recursos/migraciones del proyecto desde
+  `Settings`/`.env` (`MODULES_PACKAGE`, `MODELS_PACKAGE`, `USER_VIEWS_DIR`, …) en vez de rutas
+  hardcodeadas — un proyecto externo apunta milpa a su propio código. Nuevo `milpa.Core.Discovery`.
+- Pipeline de release a PyPI (Trusted Publishing OIDC) + gates de empaquetado en CI
+  (`uv build` + smoke de instalación).
+
+### Changed
+
+- **`DATABASE_URL`** ahora tiene default `sqlite:///./milpa.db` (zero-config: milpa arranca sin
+  configurar nada, como Django en dev). En QA/prod se pone el motor real en `.env`.
+- **`pymysql`** sale del core → extra opcional `milpa-core[mysql]` (el core queda agnóstico de dialecto).
+- El paquete importable se renombró `app` → `milpa`.
+
+## [0.2.0] - 2026-05-30
+
+DX de la consola: más comandos `jornal` (estilo `artisan`) y una lista coherente y legible.
+
+### Added
+
+- **`jornal route list`** — lista las rutas HTTP montadas (método/path/nombre) en tabla rich,
+  construyendo la app real (≈ `php artisan route:list`).
+- **`jornal db fresh`** — recrea la BD: baja todo, re-migra y siembra. Destructivo; pide
+  confirmación salvo `--force` (≈ `php artisan migrate:fresh --seed`).
+- **`jornal make controller|model|module`** — scaffolding idempotente de stubs idiomáticos
+  (los controllers se auto-montan por el Registry; nunca sobrescribe un archivo existente)
+  (≈ `php artisan make:*`).
+
+### Changed
+
+- **`jornal list`** ahora incluye también los comandos raíz (p. ej. `serve`, `list`), no solo los
+  agrupados; y estrena título: **🌽 Labores de la milpa**.
+- Descripciones (`help`) de **todos** los comandos normalizadas a un estilo coherente
+  `<imperativo>. (≈ php artisan X)`.
+
+### Docs
+
+- Guía de BD: cuándo sembrar un **catálogo fijo** en la propia migración con `op.bulk_insert`
+  (vs. seeder + factory para datos de ejemplo).
+
+### Tests
+
+- Cobertura (sin BD) de los comandos nuevos (registro de `route`/`db`/`make`, delegación de
+  `db fresh`, pureza de los stubs) y del `PassportGuard` (sin bearer → `None`, token válido →
+  user, token inválido → 401).
+
+## [0.1.0] - 2026-05-30
+
+Primera versión: el esqueleto del microframework + auth, demo y herramientas de datos.
+
+### Added
+
+#### Kernel / HTTP
+- App factory FastAPI (`create_app`) con auto-discovery de routers por módulo.
+- Routing **class-based** estilo Spring: `@Controller` + `@Get/@Post/@Put/@Patch/@Delete`
+  (convive con el estilo `APIRouter`).
+- Errores en **RFC 9457** (`application/problem+json`): `DomainError` y subclases + handler global
+  (dominio, validación 422, `HTTPException`, catch-all 500).
+- Middlewares: CORS / TrustedHost / GZip + **SecurityHeaders** (nosniff/X-Frame-Options/HSTS/CSP).
+
+#### Auth (modelo Sanctum) + autorización
+- **JWT** propio (HS256), guard `jwt`, `Auth.attempt`; **sesión cookie** firmada + **CSRF**
+  double-submit, guard `session`; **PassportGuard** (RS256 externo) para migrar Laravel.
+- `Hash` (argon2id + verifica bcrypt `$2y$` de Laravel), `UserProvider` (SQLAlchemy, overridable),
+  `current_user`/`CurrentUser`, `guarded(name)`.
+- **RBAC** (`@Roles`/`require_roles`) + **ABAC** (`Gate.define/authorize`, `@Can`).
+- Nombres de cookie configurables con prefijo (`COOKIE_PREFIX`, default `milpa`).
+
+#### Datos (estilo Spring/Laravel)
+- `Repository[Model, Id]` tipado: `get/all/add/delete/find_or_fail/first_or_create` + `paginate()`
+  (offset/limit sin COUNT, `Page`). Sesión ambiente (`@transactional`/`session_scope`), soft-delete,
+  timestamps. Engine **agnóstico del motor**.
+- **Migraciones** con Alembic (`jornal migrate make/run/status/rollback`).
+- **Seeders** (`jornal db seed`) y **Factories** `Factory[Model]` con **Faker** (locale configurable
+  vía `FAKER_LOCALE`).
+
+#### Tareas / consola / correo / i18n
+- Celery (broker-agnóstico) + crons `@cron_task` con **retry/backoff** (`retry_policy`).
+- Consola `jornal` (Typer) con auto-discovery y salida en tabla **rich**.
+- Mail (`Mailable`/`Mailer`, drivers smtp/log/null, Jinja2, i18n) y Logging (loguru, JSON).
+
+#### Demo + tooling
+- Módulo **Demo** corrible (SQLite): dashboard con auth dual, RBAC+ABAC, **búsqueda en vivo** +
+  **scroll infinito** (HTMX), branding StackCraft (Pico.css + Alpine). 100 usuarios vía factories.
+- **CI** (GitHub Actions): ruff + mypy strict + import-linter + pytest. Sitio de docs (MkDocs
+  Material) publicable a GitHub Pages.
+
+### Notas
+- Todo es **síncrono** (SQLAlchemy + Celery). Tests **sin base de datos** (fakes + monkeypatch).
+
+[Unreleased]: https://github.com/calcifux/milpa/compare/v0.3.1...HEAD
+[0.3.1]: https://github.com/calcifux/milpa/compare/v0.2.0...v0.3.1
+[0.2.0]: https://github.com/calcifux/milpa/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/calcifux/milpa/releases/tag/v0.1.0

milpa_core-0.3.1/CODE_OF_CONDUCT.md

@@ -0,0 +1,58 @@
+# Código de Conducta
+
+## Nuestro compromiso
+
+Como miembros, contribuyentes y mantenedores, nos comprometemos a hacer de la
+participación en **milpa** una experiencia libre de acoso,
+acogedora y respetuosa para todas las personas, sin importar su origen o
+identidad. Nos comprometemos a actuar e interactuar de formas que construyan una
+comunidad abierta, amable, diversa y sana.
+
+## Nuestros estándares
+
+Ejemplos de comportamiento que ayudan a crear un ambiente positivo:
+
+- Mostrar empatía y amabilidad hacia los demás
+- Respetar opiniones, puntos de vista y experiencias distintas
+- Dar y aceptar con gracia retroalimentación constructiva
+- Asumir la responsabilidad, disculparse con quienes se vean afectados por
+  nuestros errores y aprender de ellos
+- Enfocarse en lo que es mejor para la comunidad en su conjunto
+
+El acoso, las conductas abusivas o irrespetuosas, los ataques personales o
+políticos, publicar información privada de terceros sin su consentimiento y
+cualquier otra conducta que una persona razonable consideraría inapropiada en un
+entorno profesional **no se toleran**.
+
+## Estándar adoptado
+
+Este proyecto adopta el **[Contributor Covenant, versión 2.1](https://www.contributor-covenant.org/es/version/2/1/code_of_conduct/)**.
+El texto completo —con los estándares detallados y las cuatro guías de aplicación
+(Corrección → Advertencia → Expulsión temporal → Expulsión permanente)— aplica a
+este proyecto. Por favor léelo ahí.
+
+## Alcance
+
+Este Código de Conducta aplica en todos los espacios del proyecto (issues, pull
+requests, discusiones, código) y cuando una persona representa oficialmente al
+proyecto en espacios públicos.
+
+## Aplicación
+
+Las personas mantenedoras son responsables de aclarar y hacer cumplir estos
+estándares, y pueden eliminar, editar o rechazar contribuciones que no se
+alineen con este Código de Conducta.
+
+Las instancias de comportamiento abusivo, de acoso o de cualquier otra forma
+inaceptable pueden reportarse **en privado** a la persona mantenedora
+(`@calcifux`) vía GitHub (abrir un *private security advisory* o contactarla
+directamente).
+<!-- TODO: agrega un email de contacto dedicado si prefieres uno en vez de GitHub. -->
+Todas las quejas serán revisadas e investigadas de forma rápida y justa. Las
+personas mantenedoras están obligadas a respetar la privacidad y la seguridad de
+quien reporta.
+
+## Atribución
+
+Este Código de Conducta es una adaptación del
+[Contributor Covenant](https://www.contributor-covenant.org/es/), versión 2.1.

milpa_core-0.3.1/CONTRIBUTING.md

@@ -0,0 +1,148 @@
+# Contribuir a milpa
+
+¡Gracias por tu interés en contribuir! Este documento explica cómo levantar el proyecto
+en local, las convenciones que seguimos y cómo enviar un Pull Request con las mejores
+probabilidades de merge.
+
+> Si vas a tocar un subsistema, lee primero su página en
+> [`documentation/`](documentation/README.md): ahí está el "cómo funciona".
+
+## Inicio rápido
+
+```bash
+git clone https://github.com/calcifux/milpa.git
+cd milpa
+uv sync                     # crea el venv y resuelve deps (incluye las de dev)
+cp .env.example .env        # ajusta al menos DATABASE_URL
+uv run pytest               # si la suite pasa, ya puedes desarrollar
+```
+
+Si no usas `uv`, ver [documentation/02-instalacion.md](documentation/02-instalacion.md)
+(opción pip). Con `uv`, antepón `uv run` a los comandos; con el venv activo, omítelo.
+
+> **¿Quieres ver algo funcionando ya?** Corre el demo (sqlite, sin infra):
+> ```bash
+> uv run python jornal migrate run && uv run python jornal db seed && uv run python jornal serve
+> # http://127.0.0.1:8000  ·  admin@demo.test / password
+> ```
+> Auth dual (JWT + sesión/CSRF), RBAC + ABAC, búsqueda + scroll infinito, factories con Faker.
+
+## Requisitos
+
+- **Python 3.14+**
+- **[uv](https://docs.astral.sh/uv/)** (recomendado) como gestor de entorno y deps
+- **Docker NO** es necesario para los tests: son unitarios y **sin base de datos** (usan
+  fakes y monkeypatch, no servicios vivos). Docker solo hace falta para correr la app de
+  verdad (Redis + Mailpit), no para contribuir/testear.
+- **Git** con auth SSH o HTTPS a GitHub
+
+## Estructura del repo
+
+```
+app/
+  Core/          ← EL FRAMEWORK (kernel genérico, reutilizable)
+  Models/        ← modelos SQLAlchemy compartidos (auto-discovery)
+  Dictionaries/  ← constantes de dominio compartidas
+  Modules/       ← los módulos del proyecto (independientes entre sí)
+  Resources/     ← vistas/lang/estáticos compartidos
+Tests/           ← espeja app/ 1:1; tests unitarios sin BD
+documentation/   ← guía estilo Laravel (pública)
+jornal           ← entrypoint de consola (el "artisan")
+```
+
+Detalle en [documentation/04-estructura-directorios.md](documentation/04-estructura-directorios.md).
+
+## Las dos fronteras (no las rompas)
+
+`import-linter` las fuerza en CI:
+
+1. **El kernel no depende de los módulos**: `app.Core` / `app.Models` / `app.Dictionaries`
+   no importan `app.Modules`.
+2. **Los módulos son independientes entre sí**: `app.Modules.A` no importa `app.Modules.B`.
+
+Si dos módulos necesitan compartir algo, ese algo sube al kernel compartido. Ver
+[documentation/06-monolito-modular.md](documentation/06-monolito-modular.md).
+
+## Ramas y commits
+
+- `main` siempre verde. No hagas push directo; abre un PR.
+- Ramas de feature: `feat/mail-cc-bcc`, `fix/cron-lock-timeout`, `docs/install-guide`.
+- [Conventional Commits](https://www.conventionalcommits.org/): `feat:`, `fix:`, `docs:`,
+  `refactor:`, `test:`, `ci:`, `chore:`.
+
+## Estilo de código
+
+- Identificadores en **inglés**; comentarios y docstrings en **español**, explicando el
+  *porqué* (no abreviar).
+- Sin emojis en código/comentarios/docstrings.
+- Tipos completos: `mypy` corre en modo **estricto** sobre `app/` y `Tests/Core`.
+- Un archivo por clase/responsabilidad (estilo Laravel/PascalCase en `app/`).
+- Formato e imports los maneja **Ruff** (no formatees a mano).
+
+## Guardrails (lo que valida CI)
+
+Antes de abrir el PR, corre todo y déjalo verde:
+
+```bash
+uv run ruff format .        # formato        | --check  solo verifica (modo CI)
+uv run ruff check .         # lint           | --fix    arregla lo auto-arreglable
+uv run mypy                 # tipos (estricto)
+uv run lint-imports         # fronteras entre módulos
+uv run pytest               # tests (rápidos, sin BD)
+```
+
+Todo de una:
+
+```bash
+uv run ruff format --check . && uv run ruff check . && uv run mypy && uv run lint-imports && uv run pytest
+```
+
+## Contribuir al Core
+
+milpa es un **framework**: las contribuciones van al **kernel** (`app/Core`), a sus tests
+(`Tests/Core`) y a la documentación. **No** se trata de crear módulos de negocio nuevos —
+eso lo hace cada proyecto que *usa* milpa, en su propio repo. `app/Modules/Example` es
+solo el módulo de **referencia/demo**: tócalo únicamente para demostrar una capacidad del
+Core, no para meter features de dominio.
+
+Al tocar el Core:
+
+1. **Mantén el Core genérico.** Nada de dominio ni de un proyecto en particular (ni
+   nombres, ni reglas de negocio): el kernel debe servir igual a cualquier proyecto. Si
+   dudas si algo es "del framework" o "de un proyecto", probablemente no va en Core.
+2. **Respeta la frontera `app.Core ↛ app.Modules`**: el kernel no importa módulos (el
+   discovery es dinámico, no por imports estáticos). Lo valida `lint-imports`.
+3. **Espeja la estructura por capas**: cada subsistema vive en `app/Core/<Subsistema>/`
+   con un `__init__.py` que expone su API pública.
+4. **Agrega tests** en `Tests/Core/...` (sin BD) y, si cambia comportamiento público,
+   **documéntalo** en `documentation/`.
+
+Para entender un subsistema antes de tocarlo, lee su página en
+[documentation/](documentation/README.md).
+
+## Tests
+
+- Espeja `app/` en `Tests/` (misma ruta). Tests **unitarios y sin BD**: usa fakes y
+  monkeypatch, no levantes Postgres/Redis.
+- Los tests escriben su log en `logs/tests/` (lo fija `Tests/conftest.py`), no en
+  `logs/app.log`.
+- Corre uno solo: `uv run pytest Tests/Core/Mail/test_Mailer.py -x`.
+
+## Checklist del PR
+
+- [ ] `ruff format --check .` y `ruff check .` pasan
+- [ ] `mypy` pasa (estricto)
+- [ ] `lint-imports` pasa (no rompiste las fronteras)
+- [ ] `pytest` pasa
+- [ ] Subject en Conventional Commits
+- [ ] Sin datos personales, secretos ni credenciales
+- [ ] Si cambió comportamiento público, actualizaste `documentation/`
+
+## Código de Conducta
+
+Este proyecto adopta el [Código de Conducta](CODE_OF_CONDUCT.md) (Contributor Covenant
+2.1). Al participar, aceptas cumplirlo.
+
+## Licencia
+
+Al contribuir aceptas que tu aporte queda bajo la [Licencia MIT](LICENSE).

milpa_core-0.3.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 @Calcifux (Carlos Guillermo Reyes Ramiro)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.