Publicación de Módulos

Comparta código reutilizable en el Wippy Hub.

Requisitos Previos

1. Cree una cuenta en hub.wippy.ai
2. Cree una organización o únase a una
3. Registre el nombre de su módulo bajo su organización

Estructura del Módulo

mymodule/
├── wippy.yaml      # Manifiesto del módulo
├── src/
│   ├── _index.yaml # Definiciones de entradas
│   └── *.lua       # Archivos fuente
└── README.md       # Documentación (opcional)

wippy.yaml

Manifiesto del módulo:

organization: acme
module: http-utils
type: library
description: HTTP utilities and helpers
license: MIT
repository: https://github.com/acme/http-utils
homepage: https://acme.dev
keywords:
  - http
  - utilities

type es la fuente de verdad de cómo el hub clasifica el módulo y puede cambiarse en una publicación posterior; --module-type lo sobrescribe para una única publicación. Cuando se omite, los módulos recién creados usan application por defecto con una advertencia de deprecación.

Definiciones de Entradas

Las entradas se definen en _index.yaml:

version: "1.0"
namespace: acme.http

entries:
  - name: definition
    kind: ns.definition
    meta:
      title: HTTP Utilities
      description: Helpers for HTTP operations
    readme: file://README.md
    wiki:
      GUIDE.md: file://docs/GUIDE.md
      examples/auth.md: file://docs/auth.md

  - name: client
    kind: library.lua
    source: file://client.lua
    modules:
      - http_client
      - json

El mapa wiki: en ns.definition publica páginas de documentación adicionales junto al readme: las claves son rutas de página, los valores son referencias file://. Los contenidos se incrustan en el momento del empaquetado y el hub los sirve como una wiki navegable por módulo.

Dependencias

Declare dependencias de otros módulos:

entries:
  - name: __dependency.wippy.test
    kind: ns.dependency
    meta:
      description: Testing framework
    component: wippy/test
    version: ">=0.3.0"

Restricciones de versión:

Requisitos

Defina la configuración que los consumidores deben proporcionar:

entries:
  - name: api_endpoint
    kind: ns.requirement
    meta:
      description: API endpoint URL
    targets:
      - entry: acme.http:client
        path: ".meta.endpoint"
    default: "https://api.example.com"

Los targets especifican dónde se inyecta el valor:

• entry - ID completo de la entrada a configurar
• path - JSONPath para la inyección del valor

default acepta cualquier tipo escalar — default: 20 fluye hacia un target numérico como número, no como cadena. Lo mismo aplica a parameters[].value en entradas ns.dependency, y ambos aceptan referencias ${env:NAME}, transportadas literalmente y resueltas cuando la entrada de destino se decodifica.

Los consumidores configuran mediante override. La bandera -o toma una tripleta namespace:entry:field=value:

wippy run -o acme.http:client:meta.endpoint=https://custom.api.com

Imports

Referencie otras entradas:

- name: handler
  kind: function.lua
  source: file://handler.lua
  modules:
    - json
  imports:
    client: acme.http:client           # Mismo namespace
    utils: acme.utils:helpers          # Namespace diferente
    base_registry: :registry           # Integrado

En Lua:

local client = require("client")
local utils = require("utils")

Contratos

Defina interfaces públicas:

- name: http_contract
  kind: contract.definition
  meta:
    name: HTTP Client Contract
  methods:
    - name: get
      description: Perform GET request
    - name: post
      description: Perform POST request

- name: http_contract_binding
  kind: contract.binding
  contracts:
    - contract: acme.http:http_contract
      methods:
        get: acme.http:get_handler
        post: acme.http:post_handler

Flujo de Publicación

1. Autenticarse

wippy auth login

2. Preparar

wippy init
wippy update
wippy lint

3. Validar

wippy publish --dry-run

4. Publicar

wippy publish --version 1.0.0

Con notas de versión:

wippy publish --version 1.0.0 --release-notes "Initial release"

Banderas Adicionales

Empaquetado de Archivos Estáticos

Los módulos con entradas fs.directory (assets estáticos, plantillas, archivos públicos) deben usar --embed para incluirlos en el paquete publicado. Sin él, las entradas fs.directory se excluyen.

wippy publish --version 1.0.0 --embed app:public_files
wippy publish --version 1.0.0 --embed app:assets,app:templates

La bandera --embed acepta IDs de entrada o nombres que coincidan con entradas fs.directory. La misma bandera está disponible en wippy pack.

Primera Publicación

La primera vez que publicas un módulo se registra en el hub automáticamente (privado por defecto) y la publicación se reintenta una vez. Pasa --create para registrarlo de antemano y establecer sus propiedades:

wippy publish --create --version 0.1.0 \
  --module-visibility public \
  --module-type library \
  --module-display-name "HTTP Utils"

--create es idempotente — para un módulo ya registrado, el paso de creación no hace nada. Si tu cuenta no puede crear módulos en la organización, el hub devuelve un error de permiso en lugar de publicar.

Publicar en un Hub Local

Apunta --registry a un hub que se ejecute localmente para publicar e instalar sin el registro público. Se permite HTTP plano solo para hosts locales — localhost, 127.0.0.1 y los alias de contenedor host.docker.internal (Docker Desktop / OrbStack) y host.containers.internal (Podman); cualquier otro host debe usar HTTPS.

wippy auth login --registry http://localhost:8080 --token wpy_xxx
wippy publish --registry http://localhost:8080 --create --version 0.1.0

El registro y el token también pueden provenir de las variables de entorno WIPPY_REGISTRY y WIPPY_TOKEN. Cuando no se establecen, el registro toma por defecto https://hub.wippy.ai.

Cuotas

Si la cuota de módulos privados de la organización está agotada, la publicación falla con un mensaje como cannot publish: Private-module quota exhausted (5 of 5).... Haz el módulo público o pide a un administrador de la organización que aumente la cuota. Las cargas y descargas se reintentan automáticamente ante errores de red transitorios.

Publicar Valores por Defecto de Runtime {#publishing-runtime-defaults}

Las aplicaciones (solo type: application) pueden distribuir valores por defecto de configuración de runtime dentro de sus packs mediante publish.runtime en wippy.yaml:

type: application
publish:
  runtime:
    source: .wippy.yaml            # default: .wippy.yaml
    sections: [security, registry, override]
    vars: [public_url]

Reglas:

• Solo se empaquetan las variables referenciadas por las secciones seleccionadas o los perfiles publicados (seguidas transitivamente); todo lo demás necesita una entrada en vars.
• Las referencias ${env:...} en la configuración exportada se rechazan — el entorno del publicador nunca se filtra a un pack.
• Las secciones locales de máquina boot, extensions y workspace no pueden exportarse.
• Solo el pack de la aplicación principal proporciona valores por defecto de runtime del host; los metadatos de runtime en los packs de dependencias se ignoran.

En el destino, la configuración se aplica de menor a mayor: valores por defecto del pack de la app, valores por defecto integrados del runtime, archivos de configuración locales, perfiles seleccionados, sobrescrituras de CLI.

Publicar Perfiles {#publishing-profiles}

Los perfiles de la aplicación raíz se exportan a los metadatos runtime.profiles del pack. Publicar no selecciona ni fija un perfil — los consumidores eligen uno en tiempo de ejecución con wippy run --profile <name>:

publish:
  profiles:
    enabled: true
    source: config/profiles.yaml   # default: .wippy.yaml
    include: [production]          # omit to publish all non-workspace profiles

include: [] no publica ninguno; un nombre desconocido hace fallar la publicación. Las subsecciones workspace nunca se exportan, ni siquiera dentro de un perfil publicado. Ver Configuración para declarar perfiles.

Uso de Módulos Publicados

Agregar Dependencia

wippy add acme/http-utils
wippy add acme/http-utils@1.0.0
wippy install

Configurar Requisitos

Anular valores en tiempo de ejecución:

wippy run -o acme.http:client:meta.endpoint=https://my.api.com

O en .wippy.yaml:

override:
  acme.http:client:meta.endpoint: "https://my.api.com"

Importar en Su Código

# su src/_index.yaml
entries:
  - name: __dependency.acme.http
    kind: ns.dependency
    component: acme/http-utils
    version: ">=1.0.0"

  - name: my_handler
    kind: function.lua
    source: file://handler.lua
    imports:
      http: acme.http:client

Ejemplo Completo

wippy.yaml:

organization: acme
module: cache
description: In-memory caching with TTL
license: MIT
keywords:
  - cache
  - memory

src/_index.yaml:

version: "1.0"
namespace: acme.cache

entries:
  - name: definition
    kind: ns.definition
    meta:
      title: Cache Module

  - name: max_size
    kind: ns.requirement
    meta:
      description: Maximum cache entries
    targets:
      - entry: acme.cache:cache
        path: ".meta.max_size"
    default: 1000

  - name: cache
    kind: library.lua
    meta:
      max_size: 1000
    source: file://cache.lua
    modules:
      - time

src/cache.lua:

local time = require("time")

local cache = {}
local store = {}
local max_size = 1000

function cache.set(key, value, ttl)
    if #store >= max_size then
        cache.evict_oldest()
    end
    store[key] = {
        value = value,
        expires = ttl and (time.now():unix() + ttl) or nil
    }
end

function cache.get(key)
    local entry = store[key]
    if not entry then return nil end
    if entry.expires and time.now():unix() > entry.expires then
        store[key] = nil
        return nil
    end
    return entry.value
end

return cache

Publicar:

wippy init && wippy update && wippy lint
wippy publish --version 1.0.0

Véase También

• Referencia CLI
• Tipos de Entrada
• Configuración