docker-swarm 0.6.0 → 0.7.1

data/docs/config/config.md

@@ -0,0 +1,140 @@
+# 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.

data/docs/glossary/glossary.md

@@ -0,0 +1,141 @@
+# Glosario — docker-swarm
+
+> meta: artefacto · RFC-009 · generado dev-enrich · anclado a `a4e3129` · cobertura: completo inicial (primitivas Docker + arquitectura interna); no se acrecienta sin tocar el flujo/concepto
+
+## 1. Resumen
+
+Términos de negocio que la gema `docker-swarm` materializa. Dos grupos: **primitivas Docker** (entidades del Engine API expuestas como modelos Ruby) y **conceptos arquitectónicos internos** (mecanismos que sostienen el ORM). Sólo términos de negocio con binding estable. Definiciones técnicas de columnas/atributos no van acá (sería Data Dictionary; n/a en gema sin DB).
+
+## 2. Términos
+
+### Service
+
+Servicio de Docker Swarm: definición declarativa de un conjunto de tasks que corren en el cluster. La gema lo expone como CRUD completo + `restart` + `logs`. Update atómico vía `Version.Index`.
+**Binding:** [`DockerSwarm::Service`](../../lib/docker_swarm/models/service.rb)
+
+### Node
+
+Miembro físico del cluster Swarm (manager o worker). Read-only desde el punto de vista de creación: los nodos se unen al swarm fuera de la gema; la gema sólo permite update (rol/disponibilidad) y destroy.
+**Binding:** [`DockerSwarm::Node`](../../lib/docker_swarm/models/node.rb)
+
+### Task
+
+Unidad de ejecución de un Service en un Node específico. Read-only: las tasks se generan automáticamente por el orquestador a partir del Spec del Service. La gema sólo permite listar/inspeccionar/obtener logs.
+**Binding:** [`DockerSwarm::Task`](../../lib/docker_swarm/models/task.rb)
+
+### Container
+
+Container Docker standalone (no Swarm). La gema expone start/stop/destroy/logs sobre containers existentes. Creación intencionalmente fuera de scope F1 — el caso de uso primario de la gema es Swarm.
+**Binding:** [`DockerSwarm::Container`](../../lib/docker_swarm/models/container.rb)
+
+### Image
+
+Imagen Docker (registry o local). La gema cubre listar, pull (`create`) y destroy. Build local no cubierto (no caso de uso de orquestación).
+**Binding:** [`DockerSwarm::Image`](../../lib/docker_swarm/models/image.rb)
+
+### Network
+
+Red Docker (overlay para Swarm, bridge para Container). CRUD completo. Update soporta conectar/desconectar containers.
+**Binding:** [`DockerSwarm::Network`](../../lib/docker_swarm/models/network.rb)
+
+### Volume
+
+Volumen Docker (named volume). CRUD sin update (Docker no soporta update de Volume). La respuesta del index viene envuelta en `{"Volumes": [...]}` — manejado vía `root_key`.
+**Binding:** [`DockerSwarm::Volume`](../../lib/docker_swarm/models/volume.rb)
+
+### Config
+
+Configuración inmutable distribuida en el cluster (archivos de configuración, manifests). CRUD sin update — Docker requiere recrear. Sólo Swarm.
+**Binding:** [`DockerSwarm::Config`](../../lib/docker_swarm/models/config.rb)
+
+### Secret
+
+Dato sensible distribuido en el cluster (passwords, tokens, certs). Misma semántica que Config pero el `Data` se filtra automáticamente en logs vía `LogHelper`. Sólo Swarm.
+**Binding:** [`DockerSwarm::Secret`](../../lib/docker_swarm/models/secret.rb)
+
+### Swarm
+
+Cluster Docker Swarm como entidad singleton. Sólo `show` (info del cluster: ID, Version, Spec, JoinTokens). No CRUD — el cluster se inicializa/disuelve fuera de la gema.
+**Binding:** [`DockerSwarm::Swarm`](../../lib/docker_swarm/models/swarm.rb)
+
+### System
+
+Daemon Docker como entidad singleton. Métodos estáticos: `info`, `version`, `up` (ping), `df` (disk usage). Útil para health checks y observabilidad.
+**Binding:** [`DockerSwarm::System`](../../lib/docker_swarm/models/system.rb)
+
+---
+
+### Base (ORM base)
+
+Clase base de todos los modelos. Hereda de `ActiveModel::Model`. Provee accessors dinámicos PascalCase, `find`, `all`, `where`, `reload`, `payload_for_docker`. Centraliza el patrón ORM contra Docker Engine API.
+**Binding:** [`DockerSwarm::Base`](../../lib/docker_swarm/base.rb)
+
+### Concern
+
+Mixin (`ActiveSupport::Concern`) que agrega capacidad CRUD/auxiliar a un modelo. La gema define cinco concerns ortogonales: cada modelo incluye los que aplican a su semántica Docker.
+
+| Concern | Símbolo | Aplica a |
+|---|---|---|
+| Creatable | [`DockerSwarm::Concerns::Creatable`](../../lib/docker_swarm/concerns/creatable.rb) | Service, Network, Volume, Config, Secret, Image |
+| Updatable | [`DockerSwarm::Concerns::Updatable`](../../lib/docker_swarm/concerns/updatable.rb) | Service, Node, Network |
+| Deletable | [`DockerSwarm::Concerns::Deletable`](../../lib/docker_swarm/concerns/deletable.rb) | Service, Node, Container, Network, Volume, Config, Secret, Image |
+| Loggable | [`DockerSwarm::Concerns::Loggable`](../../lib/docker_swarm/concerns/loggable.rb) | Service, Task, Container |
+| Inspectable | [`DockerSwarm::Concerns::Inspectable`](../../lib/docker_swarm/concerns/inspectable.rb) | Todos (vía Base) |
+
+### Middleware
+
+Capa Excon en el stack del cliente HTTP. Tres middlewares custom: serialización de body, parsing de respuesta con indifferent access, mapeo de status a excepción tipada.
+
+| Middleware | Símbolo | Rol |
+|---|---|---|
+| RequestEncoder | [`DockerSwarm::Middleware::RequestEncoder`](../../lib/docker_swarm/middleware/request_encoder.rb) | Serializa body (JSON / x-www-form / multipart) según Content-Type |
+| ResponseJSONParser | [`DockerSwarm::Middleware::ResponseJSONParser`](../../lib/docker_swarm/middleware/response_json_parser.rb) | Parsea JSON y aplica `with_indifferent_access` |
+| ErrorHandler | [`DockerSwarm::Middleware::ErrorHandler`](../../lib/docker_swarm/middleware/error_handler.rb) | Mapea 4xx/5xx → `DockerSwarm::Error::*` + log `business_error` |
+
+### Connection
+
+Wrapper sobre el cliente Excon. Memoiza la conexión, aplica timeouts/retries de configuración, clasifica errores idempotentes vs no-idempotentes (post-fix correctness), y emite logs KV.
+**Binding:** [`DockerSwarm::Connection`](../../lib/docker_swarm/connection.rb)
+
+### Dynamic Accessor
+
+Mecanismo por el cual los modelos exponen atributos no declarados. Docker Engine evoluciona y agrega campos: la gema usa `method_missing` + cache en `defined_attributes` (Set) para responder a cualquier campo PascalCase de la respuesta sin requerir update del código.
+**Binding:** [`DockerSwarm::Base#method_missing`](../../lib/docker_swarm/base.rb), [`DockerSwarm::Base.defined_attributes`](../../lib/docker_swarm/base.rb)
+
+### Spec deep_merge
+
+Estrategia de actualización parcial del campo `Spec` de un modelo. En vez de reemplazar Spec completo, `assign_attributes` hace `deep_merge` cuando la key es `Spec` y ambos valores son Hash. Razón: updates parciales no pierden campos anidados no tocados.
+**Binding:** [`DockerSwarm::Base#assign_attributes`](../../lib/docker_swarm/base.rb)
+
+### Version.Index
+
+Mecanismo de control de concurrencia optimista de Docker para updates atómicos. Cada Service/Node tiene `Version.Index` que incrementa en cada cambio. Update requiere enviar el index actual como query param; si no coincide, Docker rechaza (500). La gema lo extrae automáticamente en `Updatable#update`.
+**Binding:** [`DockerSwarm::Concerns::Updatable#update`](../../lib/docker_swarm/concerns/updatable.rb)
+
+### LogHelper
+
+Módulo de formateo de logs en KV (`key=value`) con masking automático de claves sensibles. La regex (`password|pass|passwd|secret|token|api_key|auth|\bdata\b`) reemplaza valores por `[FILTERED]`. `\bdata\b` evita falsos positivos en `metadata`/`database`.
+**Binding:** [`DockerSwarm::LogHelper`](../../lib/docker_swarm/log_helper.rb)
+
+### payload_for_docker
+
+Transformación interna que prepara un modelo para enviarlo al API: descarta atributos internos (`ID`/`Version`/`CreatedAt`/`UpdatedAt`), extrae el contenido de `Spec` al root y mergea otros campos top-level. Resultado: el payload que Docker espera para `create`/`update`.
+**Binding:** [`DockerSwarm::Base#payload_for_docker`](../../lib/docker_swarm/base.rb)
+
+## 3. Inferencias
+
+| Término | Inferencia | Confidence | Verificar |
+|---|---|---|---|
+| Container | "creación intencionalmente fuera de scope F1" | inferred | ¿se quiere documentar como decisión explícita o como gap a cubrir? |
+| Spec deep_merge | "razón: updates parciales no pierden campos" | declared | confirmado en CLAUDE.md decisión arquitectura |
+| Dynamic Accessor | "Docker evoluciona y agrega campos" | declared | confirmado en CLAUDE.md decisión arquitectura |
+
+## 4. Cobertura y fronteras
+
+- **Cobertura:** Completa para primitivas Docker (11) y conceptos arquitectónicos internos (9). Esta es una corrida inicial (sembrado autorizado, RFC-009).
+- **Frontera con Data Dictionary (RFC-002 §2.c r4):** la gema **no tiene capa de datos** (no DB, no `docs/data/`). Definiciones de columnas/atributos = `n/a`. Atributos PascalCase de Docker (`Spec`, `TaskTemplate`, etc.) son contrato de la API Docker, no del dominio de esta gema — no entran al glosario.
+- **Frontera con comportamiento:** flujos (create+reload, retry, error-mapping) viven en [`docs/behavior/behavior.md`](../behavior/behavior.md), no acá.
+- **Fuera de alcance:**
+  - Términos técnicos puros sin significado de negocio (ej: `instance_values`, `attr_accessor`) — son detalles de implementación, no contrato.
+  - Glossary del Docker Engine API (cómo funciona internamente Swarm, raft, gossip) — vive en docs de Docker, no se duplica acá.
+- **Cadencia:** incremental por PR a partir de acá; ausencia ≠ inexistencia (RFC-009).

data/lib/docker_swarm/base.rb

@@ -75,31 +75,23 @@ module DockerSwarm
 
     def assign_attributes(new_attributes)
       return if new_attributes.blank?
+      raise ArgumentError, "assign_attributes expects a Hash, got #{new_attributes.class}" unless new_attributes.is_a?(Hash)
 
-      attributes_to_assign = new_attributes.deep_dup
+      attributes_to_assign = new_attributes.deep_dup.with_indifferent_access
+      normalized_attributes = {}
 
-      if attributes_to_assign.is_a?(Hash)
-        attributes_to_assign = attributes_to_assign.with_indifferent_access
-        normalized_attributes = {}
+      attributes_to_assign.each do |key, value|
+        normalized_key = key.to_s == "Id" ? "ID" : key.to_s
+        _define_dynamic_accessor(normalized_key)
 
-        attributes_to_assign.each do |key, value|
-          normalized_key = key.to_s == "Id" ? "ID" : key.to_s
-          _define_dynamic_accessor(normalized_key)
-
-          if normalized_key == "Spec" && respond_to?(:Spec) && self.Spec.is_a?(Hash) && value.is_a?(Hash)
-            value = self.Spec.deep_merge(value)
-          end
-
-          normalized_attributes[normalized_key] = value
+        if normalized_key == "Spec" && respond_to?(:Spec) && self.Spec.is_a?(Hash) && value.is_a?(Hash)
+          value = self.Spec.deep_merge(value)
         end
 
-        super(normalized_attributes)
-      else
-        Array(attributes_to_assign).each do |item|
-          next unless item.is_a?(Hash)
-          item.each_key { |key| _define_dynamic_accessor(key) }
-        end
+        normalized_attributes[normalized_key] = value
       end
+
+      super(normalized_attributes)
     end
 
     def attributes

data/lib/docker_swarm/concerns/updatable.rb

@@ -6,13 +6,14 @@ module DockerSwarm
       extend ActiveSupport::Concern
 
       def update(new_attributes = {})
+        current_version = self.Version&.dig("Index")
         assign_attributes(new_attributes) if new_attributes.present?
         return false unless valid?
 
         Api.request(
           action: self.class.routes[:update],
           arguments: { id: self.ID },
-          query_params: { version: self.Version&.dig("Index") },
+          query_params: { version: current_version },
           payload: payload_for_docker
         )
 

data/lib/docker_swarm/connection.rb

@@ -2,6 +2,10 @@
 
 module DockerSwarm
   class Connection
+    # HTTP methods safe to retry automatically. POST/PATCH are excluded because
+    # replaying after a partial failure can create duplicate resources.
+    IDEMPOTENT_METHODS = %i[get head put delete options].freeze
+
     attr_reader :socket_path, :logger
 
     def initialize(socket_path, logger)
@@ -16,14 +20,16 @@ module DockerSwarm
                 level: :debug,
                 data: options.merge(path: options[:path]))
 
-      # Combinar opciones por defecto de la gema con las de la petición
+      method = options[:method].to_s.downcase.to_sym
+      idempotent = IDEMPOTENT_METHODS.include?(method)
+
       request_options = {
-        idempotent: true,
+        idempotent: idempotent,
         retry_errors: [ Excon::Error::Socket, Excon::Error::Timeout ],
         read_timeout: DockerSwarm.configuration.read_timeout.to_f,
         write_timeout: DockerSwarm.configuration.write_timeout.to_f,
         connect_timeout: DockerSwarm.configuration.connect_timeout.to_f,
-        retries: DockerSwarm.configuration.max_retries.to_i
+        retries: idempotent ? DockerSwarm.configuration.max_retries.to_i : 0
       }.merge(options)
 
       response = client.request(request_options)
@@ -37,8 +43,8 @@ module DockerSwarm
       response.body
     rescue => e
       # Excon suele envolver excepciones de middleware en Excon::Error::Socket.
-      # Intentamos recuperar la causa original si es una de nuestras excepciones.
-      actual_error = (e.respond_to?(:cause) && e.cause&.class&.name&.include?("DockerSwarm::Error")) ? e.cause : e
+      # Recuperamos la causa original si es una excepción de DockerSwarm.
+      actual_error = e.cause.is_a?(::DockerSwarm::Error) ? e.cause : e
 
       log_event("request_failure",
                 level: :error,
@@ -48,9 +54,10 @@ module DockerSwarm
                   duration_s: calculate_duration(start_time)
                 ))
 
-      if actual_error.class.name.include?("DockerSwarm::Error")
+      case actual_error
+      when ::DockerSwarm::Error
         raise actual_error
-      elsif actual_error.is_a?(Excon::Error::Socket)
+      when Excon::Error::Socket
         raise ::DockerSwarm::Error::Communication, "Docker socket error: #{actual_error.message}"
       else
         raise actual_error

data/lib/docker_swarm/log_helper.rb

@@ -3,7 +3,9 @@
 module DockerSwarm
   # Helper module to centralize logging logic and formatting
   module LogHelper
-    SENSITIVE_KEYS = /password|token|api_key|auth|secret|data/i.freeze
+    # `data` se matchea con \b para que `Data` (Secret/Config) se filtre
+    # pero `metadata` u otras claves no caigan en falso positivo.
+    SENSITIVE_KEYS = /password|pass|passwd|secret|token|api_key|auth|\bdata\b/i.freeze
 
     # Formats a hash into a KV structured string with sensitive data masking
     # @param payload [Hash] The data to format

data/lib/docker_swarm/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module DockerSwarm
-  VERSION = "0.6.0"
+  VERSION = "0.7.1"
 end