tequio-core 0.1.0__tar.gz

tequio_core-0.1.0/.env.example

@@ -0,0 +1,64 @@
+# 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 ---
+# Por default sqlite local (zero-config, igual que el skeleton). Para otro motor
+# instala el extra del driver (uv sync --extra mysql) y cambia la URL:
+#   DATABASE_URL=mysql+pymysql://user:password@host:3306/database
+#   DATABASE_URL=postgresql+psycopg://user:password@host:5432/database
+DATABASE_URL=sqlite:///tequio.db
+
+# --- Colas / broker-agnostic ---
+# 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
+
+# --- 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"

tequio_core-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,63 @@
+name: CI
+
+# Corre los MISMOS guardrails que en local (CONTRIBUTING §Guardrails) en cada push a main y en cada PR.
+# tequio es worker-side: NO hay capa HTTP ni frontend, así que tampoco hay pasos de npm/Vite.
+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 + Build
+    runs-on: ubuntu-latest
+    # Sin .env en CI: damos un sqlite dummy explícito (DATABASE_URL ya tiene default en
+    # Settings, pero lo dejamos claro). Basta para importar (el engine es perezoso) y los
+    # tests son sin BD. Igual lo necesitan lint-imports y pytest (importan tequio.*).
+    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 3 guardrails + tests, 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 (import-linter: worker-side + módulos)"
+        run: uv run lint-imports
+
+      - name: Pytest (rápidos, sin BD)
+        run: uv run pytest
+
+      # --- Gate de empaquetado: el wheel se construye en limpio y se puede importar ---
+      - name: Build sanity (uv build construye sdist + wheel)
+        run: uv build
+
+      - name: Smoke de instalación (wheel limpio + import + CLI tequio)
+        run: |
+          uv venv /tmp/tequio-smoke
+          uv pip install --python /tmp/tequio-smoke/bin/python dist/*.whl
+          /tmp/tequio-smoke/bin/python -c "import tequio; print('tequio OK')"
+          # El script `tequio` se instaló en el PATH del venv: que al menos liste sin tronar.
+          /tmp/tequio-smoke/bin/tequio list

tequio_core-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,37 @@
+name: Docs
+
+# Publica la guía (documentation/) como sitio MkDocs Material en GitHub Pages en cada push a main.
+# Requiere (una sola vez): Settings → Pages → Source = "Deploy from a branch" → rama "gh-pages".
+on:
+  push:
+    branches: [main]
+    paths:
+      - "documentation/**"
+      - "mkdocs.yml"
+      - ".github/workflows/docs.yml"
+
+permissions:
+  contents: write # gh-deploy publica el sitio en la rama gh-pages
+
+concurrency:
+  group: docs-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    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: Instalar dependencias de docs
+        run: uv sync --group docs
+
+      - name: Construir y publicar en gh-pages
+        run: uv run mkdocs gh-deploy --force --no-history

tequio_core-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,54 @@
+name: Release (PyPI)
+
+# Publica tequio-core a PyPI cuando empujas un tag de versión (p. ej. `git tag v0.1.0 && 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 para el proyecto tequio-core.
+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 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

tequio_core-0.1.0/.gitignore

@@ -0,0 +1,32 @@
+# Entorno Python
+.venv/
+__pycache__/
+*.pyc
+*.pyo
+
+# Caches de herramientas (se regeneran solas; NO se versionan).
+.import_linter_cache/
+.ruff_cache/
+.pytest_cache/
+.mypy_cache/
+.claude/settings.local.json
+
+# Secretos y configuración local (NUNCA al repo)
+.env
+
+# Logs (no versionamos contenido, sí la carpeta)
+logs/*
+!logs/.gitkeep
+
+# BD sqlite local (p. ej. DATABASE_URL=sqlite:///tequio.db)
+*.db
+*.sqlite3
+
+# Artefactos de build
+dist/
+
+# Sitio de docs generado por `mkdocs build` (se publica con gh-deploy; NO se versiona).
+site/
+
+# Artefacto runtime del beat de Celery (shelve que persiste el schedule; se regenera solo)
+celerybeat-schedule*

tequio_core-0.1.0/CHANGELOG.md

@@ -0,0 +1,112 @@
+# Changelog
+
+Todos los cambios notables de **tequio** 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.1.0] - 2026-06-06
+
+**Nacimiento de tequio**: la extracción **worker-side** de [milpa](https://github.com/calcifux/milpa)
+`0.4.0`. El mismo estilo y el mismo kernel reutilizable (`Core`), pero **sin la capa web** —para
+servicios de Python que NO sirven páginas ni API (daemons, pipelines, monitores, ETLs, cron-jobs)
+y solo necesitan **trabajo en segundo plano + base de datos + consola**, con **correo** que vuelve
+al worker. Un contrato de `import-linter` garantiza que la capa web nunca se vuelva a colar al core.
+
+Forma tradicional vs estilo milpa: la forma tradicional arrastra todo el framework web (FastAPI,
+auth, pipeline de assets) aunque el servicio nunca sirva HTTP; estilo milpa el worker baja de peso
+quedándose solo con lo que de verdad usa (Celery + SQLAlchemy + Typer + correo), y el guardrail de
+fronteras lo mantiene así.
+
+### Added
+
+#### Lo que vino de milpa 0.4.0 (worker-side)
+
+- **Background** — `@job` (on-demand, `.dispatch()`, con `broker_guard` que traduce el broker caído
+  en un error accionable) y `@cron_task` (agendado, anti-overlap con lock en Redis y gate por
+  `APP_ENV`), separados a propósito (job ≠ cron). Celery broker-agnóstico (`BROKER_URL`).
+- **Patrones estilo milpa** (OPT-IN, auto-descubribles) — `Events`/`Observers` (1:N, transporte
+  adaptativo: worker si hay broker, si no síncrono), `Mediator` (command bus 1:1, `@handles`/`send`)
+  y `Pipeline` (modelo cebolla). Patrones que un arquitecto puede sugerir, no impuestos.
+- **Datos estilo Spring Data** — `Repository[Model, Id]` tipado, `@transactional`,
+  `current_session`, `Factory`/`Seeder` (con Faker), soft-delete y timestamps automáticos; engine
+  **agnóstico del motor** (se elige por `DATABASE_URL`, default `sqlite` zero-config), migraciones
+  **Alembic** motor-agnósticas.
+- **Errores que NUNCA fallan en silencio** — el CLI rinde un `DomainError` (esperado) como mensaje
+  accionable + su código (sin traceback crudo) y deja el traceback completo de un error inesperado
+  en el log.
+- **Consola estilo artisan** — kernel Typer con descubrimiento automático de comandos (Core +
+  generales del proyecto + módulos): `queue work`, `schedule work`/`run`, `migrate`, `db seed`,
+  `make …`, salida en tabla rich.
+- **Logging** — Loguru configurado (stderr conciso sin fuga de valores + archivo rotativo);
+  `LOG_JSON=true` agrega `logs/app.jsonl` (JSON Lines) para Loki/Grafana.
+- **Config tipada** — `Settings` (pydantic-settings) lee el `.env`; la infraestructura sin default
+  (obligatoria) falla claro si falta.
+- **Reloj inyectable** (`Core/Clock`) — `SystemClock` / `FixedClock` (= `Carbon::setTestNow`) para
+  congelar el tiempo en tests, estilo `java.time.Clock` de Spring.
+
+#### Lo propio de tequio
+
+- **Correo worker-side** (`Core/Mail`) — Mailables estilo Laravel (`Mail.send` / `Mail.queue`),
+  drivers (`smtp`/`log`/`null`), adjuntos por bytes o archivo y logo por CID. Vuelve al worker
+  porque muchísimos crons y jobs terminan mandando correo (justo el caso del `DailyDigestCron`).
+- **TemplateEngine e i18n de correos worker-side** (`Core/View/TemplateEngine.py`, `Core/Translate`)
+  — los correos se renderizan con Jinja2 y se traducen con `i18nice`, todo worker-side; `jinja2` e
+  `i18n` quedan permitidos por el contrato de fronteras (lo prohibido es la capa HTTP/Auth/frontend,
+  no el correo).
+- **Cola `emails` por convención** — los correos se encolan a la cola `emails`
+  (`queue work --queue emails`), el equivalente del `->onQueue('emails')` de Laravel; con
+  `MAIL_DRIVER=log` (default dev) el MIME se vuelca al log sin SMTP, y el `docker-compose.yml` trae
+  Mailpit para verlos en una UI.
+- **`queue work --pool`** — opción para elegir el pool de Celery (`prefork`/`solo`/`threads`/
+  `gevent`); en **Windows**, si se omite, cae a `solo` automáticamente (el prefork de billiard no es
+  confiable ahí).
+- **Encarpetado libre con discovery recursivo** — el discovery importa **todo el árbol** de cada
+  módulo (`import_submodules(..., recursive=True)`), así organizas tu app como quieras: la pieza se
+  descubre mientras lleve su decorador o herede de su base. La única convención con peso es
+  `Console/Commands/`. El guardrail `test_FreeLayoutDiscovery` fija esta libertad.
+- **El beat agenda los `@cron_task`** — `collect_beat_schedule()` (en el `Registry`) **fusiona** dos
+  fuentes para el calendario del beat: (1) cada `@cron_task(schedule=…)` auto-descubierto —su
+  expresión cron convertida a `celery.schedules.crontab`— y (2) los `beat_schedule` declarados en
+  `Console/Kernel.py` (vía declarativa, **con precedencia** en colisiones de nombre). Así
+  `schedule work` (el beat) agenda los `@cron_task` **sin** escribir un `Kernel.py`. El conversor
+  cron-string → `crontab` exige **exactamente 5 campos**; si no, falla con un error claro (no agenda
+  mal en silencio). Los gates de ejecución (anti-overlap y `environments`) siguen viviendo en
+  `@cron_task` al ejecutar; el beat solo agenda. (Decisión consciente: este comportamiento **diverge
+  de milpa**, que solo agendaba lo declarado en `Console/Kernel.py`.)
+- **Demo `Notes`** (`tequio new --demo`) — módulo de referencia corrible (notas, worker-side) que
+  ejercita TODO el stack: `@job`, `@cron_task` (un digest diario que **manda correo**),
+  eventos→observer (1:N), Mediator (1:1), Pipeline de limpieza y Mailables (i18n de correos), más
+  seeders/factories con Faker. Corre sobre SQLite sin levantar infraestructura. La nota es
+  deliberadamente mínima (`title`/`body`/`archived`): tequio no tiene Auth ni usuarios (eso vive en
+  milpa), así que la nota no tiene dueño.
+- **Scaffolder `tequio new <app> [--demo]`** — genera un proyecto listo para correr desde un
+  skeleton embebido (estilo `laravel new`); el paquete se llama `tequio-core` en PyPI pero el import
+  y el comando siguen siendo `tequio`. `--demo` materializa el módulo Notes; sin él, un módulo
+  `Hello` mínimo.
+- **Tres contratos `import-linter`** — (1) `forbidden`: `tequio.Core` **NO** depende de la capa web
+  (fastapi/starlette/uvicorn/slowapi/httpx/itsdangerous/pwdlib/jwt) —el contrato distintivo de
+  tequio—; (2) `forbidden`: el shared kernel (`Core`/`Models`/`Dictionaries`) no importa
+  `Modules`; (3) `independence`: los módulos no se importan entre sí.
+- **Documentación completa** (mkdocs) — guía estilo Laravel en español: instalación, configuración,
+  ciclo de vida (del **worker**, sin request), monolito modular, consola (`jornal`), base de datos,
+  background (jobs, colas, cron + el reloj), los patrones estilo milpa, correo, errores de dominio y
+  logging. Cada feature contrasta la *forma tradicional* vs *estilo milpa* y se demuestra ejecutable
+  en el módulo Demo.
+
+### Excluido (vive en milpa)
+
+- **Http/FastAPI, Auth** (RBAC/ABAC, JWT/sesión, Passport), **Views/Vite** (frontend,
+  microfrontends, PWA) e **i18n de la UI**. tequio **sí** trae correo (Mailables + i18n de correos)
+  porque vuelve al worker. Si tu servicio necesita algo de lo excluido, usa
+  [milpa](https://github.com/calcifux/milpa).
+
+### Notas
+
+- Todo es **síncrono** (SQLAlchemy + Celery). Los tests corren **sin base de datos** (fakes +
+  monkeypatch) y el toolchain de gates es ruff + mypy strict + import-linter + pytest.
+
+[Unreleased]: https://github.com/calcifux/tequio-core/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/calcifux/tequio-core/releases/tag/v0.1.0

tequio_core-0.1.0/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 **tequio** 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.

tequio_core-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,166 @@
+# Contribuir a tequio
+
+¡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".
+
+## ¿Qué es tequio (y qué no)?
+
+tequio es la **extracción worker-side** de [milpa](https://github.com/calcifux/milpa):
+el núcleo de trabajo en segundo plano (jobs, crons, eventos/observers, Mediator, Pipeline,
+BD con SQLAlchemy + Alembic, logging y CLI). **No** trae capa HTTP, Mail, Auth,
+Views/Vite ni i18n: si tu servicio sirve páginas o API, eso vive en
+[milpa](https://github.com/calcifux/milpa), no aquí.
+
+## Inicio rápido
+
+```bash
+git clone https://github.com/calcifux/tequio-core.git
+cd tequio-core
+uv sync                     # crea el venv y resuelve deps (incluye las de dev)
+cp .env.example .env        # ajusta lo que necesites (sqlite ya viene por default)
+uv run pytest               # si la suite pasa, ya puedes desarrollar
+```
+
+Con `uv`, antepón `uv run` a los comandos; con el venv activo, omítelo. El launcher de
+consola en la raíz es `jornal` (el mismo nombre que en milpa, a propósito).
+
+> **¿Quieres ver algo funcionando ya?** Corre el demo (sqlite, sin infra de BD):
+> ```bash
+> uv run python jornal migrate make -m inicial && uv run python jornal migrate run
+> uv run python jornal db seed          # puebla notas con Faker (DemoSeeder)
+> uv run python jornal queue work       # arranca el worker (procesa los @job)
+> ```
+> Notes worker-side: jobs/crons/observers que escriben al log, Mediator, Pipeline,
+> seeder con Faker. Para procesar la cola y el beat necesitas un broker (Redis); los
+> flujos síncronos no lo tocan.
+
+## 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). Para correr la cola/beat de verdad hace falta
+  un broker (Redis), no para contribuir/testear.
+- **Git** con auth SSH o HTTPS a GitHub
+
+## Estructura del repo
+
+```
+src/tequio/
+  Core/          ← EL FRAMEWORK (kernel genérico worker-side, reutilizable)
+  Models/        ← modelos SQLAlchemy compartidos (auto-discovery)
+  Dictionaries/  ← constantes de dominio compartidas
+  Modules/       ← los módulos del proyecto (independientes entre sí; Demo es el de referencia)
+  Console/       ← commands GENERALES del proyecto (opcional)
+Tests/           ← espeja src/tequio/ 1:1; tests unitarios sin BD
+documentation/   ← guía estilo Laravel (sitio MkDocs Material)
+jornal           ← entrypoint de consola en la raíz (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 (ver `[tool.importlinter]` en `pyproject.toml`):
+
+1. **tequio es worker-side**: `tequio.Core` **no** importa la capa web ni mail
+   (`fastapi`, `starlette`, `uvicorn`, `jinja2`, `jwt`, `i18n`, …). Ese contrato evita
+   que la capa HTTP/auth de milpa se vuelva a colar al núcleo.
+2. **El kernel no depende de los módulos**: `tequio.Core` / `tequio.Models` /
+   `tequio.Dictionaries` no importan `tequio.Modules`.
+3. **Los módulos son independientes entre sí**: `tequio.Modules.A` no importa
+   `tequio.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/cron-lock-timeout`, `fix/queue-retry-backoff`, `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 `src/tequio` y `Tests/Core`.
+- Un archivo por clase/responsabilidad (estilo Laravel/PascalCase en `src/tequio`).
+- Formato e imports los maneja **Ruff** (no formatees a mano); cada archivo declara
+  `from __future__ import annotations` (lo exige y autofixea Ruff).
+
+## Guardrails (lo que valida CI)
+
+Antes de abrir el PR, corre todo y déjalo verde. Son los **3 guardrails** (lint, tipos,
+fronteras) + **tests** + **build**:
+
+```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 (worker-side + módulos)
+uv run pytest               # tests (rápidos, sin BD)
+uv build                    # empaqueta sdist + wheel (no se publica algo que no construye)
+```
+
+Todo de una:
+
+```bash
+uv run ruff format --check . && uv run ruff check . && uv run mypy && uv run lint-imports && uv run pytest && uv build
+```
+
+## Contribuir al Core
+
+tequio es un **framework**: las contribuciones van al **kernel** (`src/tequio/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* tequio, en su propio repo (con `tequio new`).
+`src/tequio/Modules/Demo` es solo el módulo de **referencia/demo** (Notes worker-side):
+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 servicio
+   worker-side. Si dudas si algo es "del framework" o "de un proyecto", probablemente no
+   va en Core.
+2. **Respeta las fronteras**: `tequio.Core` no importa la capa web/mail ni los 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 `src/tequio/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 `src/tequio/` en `Tests/` (misma ruta). Tests **unitarios y sin BD**: usa fakes y
+  monkeypatch, no levantes Redis/Postgres.
+- Corre uno solo: `uv run pytest Tests/Core/Cron/test_Schedule.py -x`.
+
+## Checklist del PR
+
+- [ ] `ruff format --check .` y `ruff check .` pasan
+- [ ] `mypy` pasa (estricto)
+- [ ] `lint-imports` pasa (no rompiste las fronteras)
+- [ ] `pytest` pasa
+- [ ] `uv build` construye sdist + wheel
+- [ ] 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).

tequio_core-0.1.0/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.

tequio_core-0.1.0/PKG-INFO

@@ -0,0 +1,30 @@
+Metadata-Version: 2.4
+Name: tequio-core
+Version: 0.1.0
+Summary: Núcleo de trabajo en segundo plano estilo milpa: jobs, crons, eventos y BD (Celery + SQLAlchemy + Typer) sin capa HTTP.
+Author: @Calcifux (Carlos Guillermo Reyes Ramiro)
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.14
+Requires-Dist: alembic>=1.18.4
+Requires-Dist: celery[redis]>=5.6.3
+Requires-Dist: croniter>=6.2.2
+Requires-Dist: i18nice[yaml]>=0.16
+Requires-Dist: jinja2>=3.1.4
+Requires-Dist: loguru>=0.7
+Requires-Dist: pydantic-settings>=2.14.1
+Requires-Dist: redis>=6.4.0
+Requires-Dist: rich>=15.0.0
+Requires-Dist: sqlalchemy-easy-softdelete>=0.9.0
+Requires-Dist: sqlalchemy>=2.0.50
+Requires-Dist: typer>=0.26.2
+Requires-Dist: tzdata>=2026.2
+Requires-Dist: tzlocal>=5.3.1
+Provides-Extra: mssql
+Requires-Dist: pyodbc>=5.2; extra == 'mssql'
+Provides-Extra: mysql
+Requires-Dist: pymysql>=1.2.0; extra == 'mysql'
+Provides-Extra: oracle
+Requires-Dist: oracledb>=2.5; extra == 'oracle'
+Provides-Extra: postgres
+Requires-Dist: psycopg[binary]>=3.2; extra == 'postgres'