docker-swarm 0.7.1 → 0.8.0

data/lib/docker_swarm.rb

@@ -44,6 +44,7 @@ require_relative "docker_swarm/middleware/response_json_parser"
 require_relative "docker_swarm/middleware/error_handler"
 require_relative "docker_swarm/connection"
 require_relative "docker_swarm/api"
+require_relative "docker_swarm/registry_auth"
 
 # Concerns deben cargarse antes que Base si Base los incluye
 require_relative "docker_swarm/concerns/creatable"

data/skill/SKILL.md

@@ -9,10 +9,10 @@ description: >-
   cuando el caller necesita orquestar Docker desde Ruby — listar/crear/
   actualizar/eliminar recursos del cluster, leer logs de services/tasks/
   containers, hacer health-check del daemon (System.up/info/df), filtrar por
-  labels, o capturar errores tipados de Docker (Conflict/NotFound/
-  Communication). NO activar para builds de imágenes (no implementado), pull
-  con auth de registry privado (no implementado), o flujos que no son
-  Swarm (Docker Compose, raw containers).
+  labels, pullear imágenes (incl. de registries privados vía X-Registry-Auth),
+  o capturar errores tipados de Docker (Conflict/NotFound/Communication). NO
+  activar para builds de imágenes (no implementado) o flujos que no son Swarm
+  (Docker Compose, raw containers).
 triggers:
   - "DockerSwarm::"
   - "docker-swarm gem"
@@ -55,11 +55,11 @@ Defaults son razonables: en local sin TLS, no necesitás bloque `configure`.
 
 | Modelo | Class methods | Instance methods | Notas |
 |---|---|---|---|
-| `Service` | `all(filters)`, `find(id)`, `where(filters)`, `create(attrs)` | `update(attrs)`, `restart`, `destroy`, `logs(query)`, `reload`, `persisted?`, `id` | CRUD completo + force-recreate de tasks |
+| `Service` | `all(filters)`, `find(id)`, `where(filters)`, `create(attrs)` | `update(attrs)`, `restart`, `destroy`, `logs(query)`, `reload`, `persisted?`, `id` | CRUD completo + force-recreate de tasks; `create`/`update` aceptan `registry_auth:` (+ `update`: `registry_auth_from:`) para auth de registry privado |
 | `Node` | `all(filters)`, `find(id)`, `where(filters)` | `update(attrs)`, `destroy` | No `create` (los nodos se unen fuera de la gema) |
 | `Task` | `all(filters)`, `find(id)`, `where(filters)` | `logs(query)`, `reload` | Read-only (generados por orquestador) |
 | `Container` | `all(filters)`, `find(id)`, `where(filters)` | `start`, `stop`, `destroy`, `logs(query)` | **No `create`** (gap conocido, fuera F1) |
-| `Image` | `all(filters)`, `find(id)`, `create(attrs)` | `destroy` | `create` = pull. **No soporta `X-Registry-Auth`** (registries privados con auth no funcionan) |
+| `Image` | `all(filters)`, `find(id)`, `pull(image_reference, registry_auth:)` | `destroy` | **No `create`** (retirado; `Image` ya no es Creatable). `pull` = pull explícito síncrono → `{status, image_ref, digest?}`; **soporta `X-Registry-Auth`** para registries privados |
 | `Network` | `all(filters)`, `find(id)`, `create(attrs)` | `update(attrs)`, `destroy` | CRUD completo |
 | `Volume` | `all(filters)`, `find(id)`, `create(attrs)` | `destroy` | No `update` (Docker no lo soporta). Respuesta wrapped vía `root_key = "Volumes"` |
 | `Config` | `all(filters)`, `find(id)`, `create(attrs)` | `destroy` | No `update` — recrear |
@@ -131,7 +131,8 @@ Todas heredan de `DockerSwarm::Error`. Tres formas de acceso equivalentes: `Dock
 - **`Spec` se mergea con `deep_merge` en updates**, no se reemplaza. Pasale sólo los campos que cambian: `service.update(Mode: {...})`, no `service.update(Spec: {...completo})`.
 - **`assign_attributes` muta antes de validar.** Si `update` falla por `valid?` o por el API, la instancia local quedó mutada. Hacé `reload` si necesitás estado limpio.
 - **`Container.create` no existe** en la gema (gap intencional F1). Si necesitás crear containers standalone, usá `DockerSwarm.request(method: :post, path: "containers/create", ...)` directo.
-- **Pull con registry privado no soportado.** `Image.create` no inyecta header `X-Registry-Auth`. Para registries privados, fallback a `DockerSwarm.request` con headers manuales.
+- **`Image.create` retirado (breaking).** Ya no existe (`Image` dejó de ser Creatable; el `create` estaba roto y sin consumidores). Usá `Image.pull(image_reference, registry_auth:)`.
+- **Auth de registry privado soportado** vía credencial opaca base64url en `registry_auth:` — `Image.pull(ref, registry_auth:)`, `Service.create(..., registry_auth:)` y `Service#update(..., registry_auth:` / `registry_auth_from:)`. Viaja por header `X-Registry-Auth` (o query `registryAuthFrom`: `spec`\|`previous-spec`, excluyentes); la gema no la mintea ni decodifica. Ver flujos 3.9/3.10 de `docs/behavior/behavior.md`.
 - **`destroy` es graceful con 404** (retorna `nil`), no con 409. Si el recurso está en uso, `Conflict` se propaga.
 - **Logs sensibles enmascarados** automáticamente: keys matching `password|pass|passwd|secret|token|api_key|auth|\bdata\b` → `[FILTERED]`. `\bdata\b` evita filtrar `metadata`/`database`.
 
@@ -164,10 +165,16 @@ Logs salen en formato KV (`component=docker_swarm.connection event=request_succe
 
 ## Índice de artefactos
 
+- [`docs/interface/interface.md`](docs/interface/interface.md) — API Ruby pública (11 modelos + `Base` + concerns + `Api`/`Connection`). La tabla de símbolos de arriba es el resumen; el detalle por símbolo acá.
+- [`docs/errors/errors.md`](docs/errors/errors.md) — jerarquía de excepciones + mapeo status HTTP → excepción. La tabla de errores de arriba es el resumen.
+- [`docs/consumed/docker-engine-api.md`](docs/consumed/docker-engine-api.md) — superficie del Docker Engine API consumida (`Api::ENDPOINTS`) + política de retry estructural.
 - [`docs/glossary/glossary.md`](docs/glossary/glossary.md) — definición de términos (primitivas Docker + conceptos internos).
 - [`docs/behavior/behavior.md`](docs/behavior/behavior.md) — secuencias load-bearing (create+reload, update+Version, retry-policy, error-mapping, etc.).
+- [`docs/config/configuracion.md`](docs/config/configuracion.md) — inventario de configuración runtime (7 opciones del bloque `configure`, sin env vars, ninguna secreta). El bloque de arriba es el resumen; shape/defaults/consumidores en el detalle.
+- [`docs/topology/topology.md`](docs/topology/topology.md) — dependencias runtime (3) + grafo de contexto.
+- [`docs/test/testing.md`](docs/test/testing.md) — estructura de la suite RSpec (unit + integration) y comandos de corrida.
 - `docs/data/` — `n/a` (gema sin DB).
-- `docs/api/`, `docs/interface/`, `docs/topology/` — F2 declaradas, **no implementadas**. El contrato resumido de arriba reside **transitoriamente** acá (RFC-008 §2 coexistencia transitoria con destino pendiente).
+- `docs/api/` (operaciones), `docs/events/` — `n/a` (la gema no expone superficie HTTP/CLI/eventos propia; su superficie pública es la interfaz Ruby).
 
 ## Versionado del contrato
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: docker-swarm
 version: !ruby/object:Gem::Version
-  version: 0.7.1
+  version: 0.8.0
 platform: ruby
 authors:
 - Gabriel
@@ -91,8 +91,14 @@ files:
 - LICENSE
 - README.md
 - docs/behavior/behavior.md
-- docs/config/config.md
+- docs/config/configuracion.md
+- docs/consumed/docker-engine-api.md
+- docs/errors/errors.md
 - docs/glossary/glossary.md
+- docs/interface/interface.md
+- docs/release/release.md
+- docs/test/testing.md
+- docs/topology/topology.md
 - lib/docker-swarm.rb
 - lib/docker_swarm.rb
 - lib/docker_swarm/api.rb
@@ -120,6 +126,7 @@ files:
 - lib/docker_swarm/models/system.rb
 - lib/docker_swarm/models/task.rb
 - lib/docker_swarm/models/volume.rb
+- lib/docker_swarm/registry_auth.rb
 - lib/docker_swarm/version.rb
 - skill/SKILL.md
 homepage: https://github.com/gedera/docker-swarm
@@ -128,9 +135,9 @@ licenses:
 metadata:
   homepage_uri: https://github.com/gedera/docker-swarm
   source_code_uri: https://github.com/gedera/docker-swarm
-  changelog_uri: https://github.com/gedera/docker-swarm/blob/v0.7.1/CHANGELOG.md
+  changelog_uri: https://github.com/gedera/docker-swarm/blob/v0.8.0/CHANGELOG.md
   bug_tracker_uri: https://github.com/gedera/docker-swarm/issues
-  documentation_uri: https://github.com/gedera/docker-swarm/blob/v0.7.1/skill/SKILL.md
+  documentation_uri: https://github.com/gedera/docker-swarm/blob/v0.8.0/skill/SKILL.md
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:

data/docs/config/config.md

@@ -1,140 +0,0 @@
-# Inventario de Configuración — docker-swarm
-
-> meta: artefacto · generado manual · anclado a `b3549e7` · cobertura: archivos de configuración versionados del repo (excluye `lib/`, `spec/`, `skill/`, `docs/`)
-
-## 1. Resumen
-
-Lista de archivos de configuración del repo, qué controlan, quién los consume y dónde tocar para cambiar comportamiento. Agrupados por dominio: **gema**, **Ruby/lint**, **CI/CD**, **dependencias automatizadas**, **agentes/skills**, **entorno local**.
-
-## 2. Gema
-
-### `docker-swarm.gemspec`
-
-Especificación de la gema (nombre, versión, autoría, deps runtime, ficheros incluidos, metadatos RubyGems). Versión leída desde `lib/docker_swarm/version.rb`.
-
-- Ruby mínimo: `>= 3.2.0`
-- Runtime deps: `activesupport >= 6.0`, `activemodel >= 6.0`, `excon >= 0.80`
-- Dev deps: `rake ~> 13.0`, `rspec ~> 3.0`
-- Files glob: `{lib,exe,skill,docs}/**/*` + `README.md`, `CHANGELOG.md`, `LICENSE`
-- MFA RubyGems: requerido (`rubygems_mfa_required = true`)
-- Cambio típico: bumpear versión → editar `lib/docker_swarm/version.rb` (no acá).
-
-### `Gemfile`
-
-Sólo declara `gemspec` + grupos `:development, :test` y `:test`. Runtime deps viven en el gemspec.
-
-- `:development, :test`: `rspec`, `pry`, `rubocop-rails-omakase`
-- `:test`: `activemodel`, `activesupport`, `excon` (re-declaradas para resolver en test sin runtime gemspec)
-
-### `Gemfile.lock`
-
-Lock generado por Bundler. Versionado. No editar a mano.
-
-## 3. Ruby / Lint
-
-### `.rubocop.yml`
-
-Base: `rubocop-rails-omakase`.
-
-- `TargetRubyVersion: 3.2`
-- Exclude: `bin/**/*`, `vendor/**/*`, `spec/fixtures/**/*`, `Gemfile`, `Gemfile.lock`, `docker-swarm.gemspec`
-- `Style/Documentation`: deshabilitado (ruido masivo; habilitar cuando YARD esté completo)
-- `Naming/MethodName`: excluido en `lib/docker_swarm/base.rb` y `lib/docker_swarm/models/**/*` (justificación: PascalCase fiel a Docker API)
-
-Sin `.ruby-version` en el repo. Ruby de runtime se infiere del gemspec (`>= 3.2.0`) y CI fija `3.4.4`.
-
-## 4. CI/CD
-
-### `.github/workflows/main.yml`
-
-Workflow `Ruby` — corre en `push` a `main` y en cada `pull_request`.
-
-- Runner: `ubuntu-latest`
-- Matrix Ruby: `['3.4.4']`
-- Steps: checkout (`actions/checkout@v6`, `persist-credentials: false`) → `ruby/setup-ruby@v1` con `bundler-cache: true` → `bundle exec rspec --tag ~type:integration` → `bundle exec rubocop`
-- Tests de integración (`type:integration`) excluidos en CI — requieren Docker Engine real, correr local.
-
-### `.github/workflows/release.yml`
-
-Workflow `Publish to RubyGems` — corre en push de tag `v*`.
-
-- Runner: `ubuntu-latest`
-- Permisos: `contents: read`, `packages: write`
-- Steps: checkout → setup Ruby 3.4.4 → `gem build *.gemspec` → `gem push *.gem`
-- Secret requerido: `RUBYGEMS_API_KEY`
-- Trigger manual: pushear tag `v<version>` (ver `/gem-release`).
-
-## 5. Dependencias automatizadas
-
-### `.github/dependabot.yml`
-
-Dos ecosistemas:
-
-- `bundler` (`/`): semanal, máx 10 PRs abiertos. Grupo `development-dependencies` agrupa `rubocop*`, `rspec*`, `pry*` en un sólo PR.
-- `github-actions` (`/`): mensual.
-
-## 6. Agentes / Skills
-
-### `skills.yml`
-
-Declara MCPs y skills externas a sincronizar.
-
-- MCPs: `github`, `clickup`
-- Skills (todas `repo: sequre/ai_knowledge` excepto donde se indique): `yard`, `quality-code`, `gem-release`, `dev-structure`, `dev-compose`, `dev-enrich`, `skill-feedback`, `agent-issue`, `dev-flow`, `matrix-element`, `documentation-writer` (`repo: github/awesome-copilot`, `path: skills/documentation-writer`)
-- `matrix-element` consume env `MATRIX_AUTH_TOKEN` + homeserver `https://matrix.cloud.wispro.co` + room `agents`.
-
-### `skills.lock`
-
-Lock de skills sincronizadas (`synced_at: 2026-04-07`). Todas con `scope: local` y path en `.agents/skills/`. Regenerable con `ruby .agents/skills/skill-manager/scripts/sync.rb`.
-
-### `.claude/settings.local.json`
-
-Permisos locales de Claude Code (no versionar credenciales acá). Allow:
-
-- `Bash(find /Users/gabriel/src/gems/docker-swarm/spec/integration -type f -name "*_spec.rb" -exec wc -l {} \\;)`
-- `Bash(grep "^[[:space:]]*class " /Users/gabriel/src/gems/docker-swarm/lib/docker_swarm/**/*.rb)`
-- `Bash(git rm *)`
-- `Bash(bundle exec *)`
-
-### `.claude/commands/*.md`
-
-Slash commands del proyecto. Cuatro archivos: `api.md`, `errors.md`, `orm.md`, `test.md`. Invocables como `/api`, `/errors`, `/orm`, `/test` desde Claude Code.
-
-## 7. Entorno local
-
-### `.env`
-
-**No versionado** (`.gitignore`). Variables ClickUp para reporting de agentes:
-
-- `AI_REPORTS_SPACE_ID`, `AI_REPORTS_BUG_REPORTS_LIST_ID`, `AI_REPORTS_IMPROVEMENTS_LIST_ID`
-- `AGENT_REVIEW_SAPCE_ID` (sic, typo), `AGENT_LIST_ID`, `AGENT_ACTION_PLAN_LIST_ID`
-
-### `.gitignore`
-
-Ignora: `.agents/` (skills sincronizadas, regenerables) y `.env` (variables de entorno).
-
-## 8. Tabla resumen
-
-| Archivo | Dominio | Consumidor | Versionado |
-|---|---|---|---|
-| `docker-swarm.gemspec` | Gema | Bundler / RubyGems | sí |
-| `Gemfile` | Gema | Bundler | sí |
-| `Gemfile.lock` | Gema | Bundler | sí |
-| `.rubocop.yml` | Lint | RuboCop | sí |
-| `.github/workflows/main.yml` | CI | GitHub Actions | sí |
-| `.github/workflows/release.yml` | CD | GitHub Actions | sí |
-| `.github/dependabot.yml` | Deps auto | GitHub Dependabot | sí |
-| `skills.yml` | Skills | `skill-manager` | sí |
-| `skills.lock` | Skills | `skill-manager` | sí |
-| `.claude/settings.local.json` | Agente | Claude Code | sí |
-| `.claude/commands/*.md` | Agente | Claude Code | sí |
-| `.env` | Entorno | runtime local | **no** |
-| `.gitignore` | VCS | git | sí |
-
-## 9. Secrets / credenciales
-
-- GitHub Actions: `RUBYGEMS_API_KEY` (release.yml)
-- Local `.env`: IDs ClickUp (no secretos pero específicos del workspace)
-- Skills `matrix-element`: `MATRIX_AUTH_TOKEN`
-
-Ninguna credencial hardcodeada en archivos versionados.