Construcción de Packs

Resumen

Los packs son la unidad de distribución en Greentic. Esta guía cubre la creación, construcción, firmado y publicación de packs usando las herramientas CLI.

Comandos CLI de Pack

gtc pack

gtc pack <COMMAND>

Commands:
  build     Build a pack from source directory
  verify    Verify pack signature and contents
  info      Display pack metadata
  extract   Extract pack contents
  sign      Sign a pack
  publish   Publish pack to registry

Crear un Pack

1. Crear la estructura de directorios del pack

   mkdir -p my-pack/{flows,components,assets}

2. Crear el manifiesto del pack

   my-pack/pack.toml

   [pack]
   name = "my-feature"
   version = "1.0.0"
   description = "My awesome feature pack"
   authors = ["Your Name <you@example.com>"]
   
   [capabilities]
   id = "greentic.cap.app.v1"
   provides = ["my-feature"]
   
   [flows]
   main = "flows/main.ygtc"
   
   [components]
   processor = "components/processor.wasm"
   
   [assets]
   templates = "assets/templates/"

3. Agregar flows

   my-pack/flows/main.ygtc

   name: main
   version: "1.0"
   description: Main flow
   
   nodes:
     - id: process
       type: reply
       config:
         message: "Hello from my pack!"
   
   triggers:
     - type: message
       target: process

4. Agregar components (si aplica)

   Construye los components WASM y colócalos en components/:

   cd my-component
   cargo build --target wasm32-wasip2 --release
   cp target/wasm32-wasip2/release/my_component.wasm ../my-pack/components/

Construir Packs

Build básico

gtc pack build ./my-pack

# Output: my-feature-1.0.0.gtpack

Build con opciones

# Specify output path
gtc pack build ./my-pack --output ./dist/my-feature.gtpack

# Skip WASM optimization
gtc pack build ./my-pack --no-optimize

# Include debug info
gtc pack build ./my-pack --debug

Salida del build

• Directoriomy-feature-1.0.0.gtpack

  • manifest.cbor
  • Directorioflows/

    • main.ygtc
  • Directoriocomponents/

    • processor.wasm
  • Directorioassets/

    • Directoriotemplates/

      • …
  • sbom.json

Firmar Packs

Precaución

Firma siempre los packs antes de distribuirlos. Los packs sin firmar pueden ser rechazados por el runtime en producción.

Generar clave de firma

# Generate new Ed25519 key pair
gtc pack keygen --output my-signing-key

# Creates:
# - my-signing-key.pem (private key - keep secret!)
# - my-signing-key.pub (public key - distribute)

Firmar un Pack

gtc pack sign my-feature-1.0.0.gtpack --key my-signing-key.pem

# Output: my-feature-1.0.0.gtpack (updated with signature)

Verificar firma

gtc pack verify my-feature-1.0.0.gtpack --pubkey my-signing-key.pub

# Output: Signature valid

Inspección de Packs

Ver metadatos

gtc pack info my-feature-1.0.0.gtpack

Salida:

Pack: my-feature
Version: 1.0.0
Description: My awesome feature pack
Authors: Your Name <you@example.com>

Capabilities:
  ID: greentic.cap.app.v1
  Provides: my-feature

Contents:
  Flows: 1
  Components: 1
  Assets: 2 directories

Signature: Valid (signed by: ABC123...)

Listar contenido

gtc pack info my-feature-1.0.0.gtpack --list

# Lists all files in the pack

Extraer Pack

gtc pack extract my-feature-1.0.0.gtpack --output ./extracted/

# Extracts pack contents for inspection

Validación de Flows

Validar flows

# Validate all flows in a directory
gtc flow doctor ./my-pack/flows/

# Validate specific flow
gtc flow validate ./my-pack/flows/main.ygtc

Salida de doctor

gtc flow doctor ./flows/

# Output:
# Checking flows/main.ygtc... OK
# Checking flows/helper.ygtc... OK
#
# 2 flows checked, 0 errors, 0 warnings

Errores comunes de validación

Error	Causa	Solución
Unknown node type	Tipo de nodo no válido	Verifica los tipos de nodo disponibles
Missing target node	Una arista apunta a un nodo inexistente	Corrige la referencia del ID del nodo
Circular dependency	Los nodos forman un ciclo	Rompe el ciclo
No trigger defined	El flow no tiene punto de entrada	Agrega un trigger

Publicar Packs

Publicar en un registro OCI

# Login to registry
gtc pack login ghcr.io --username USER --password TOKEN

# Publish pack
gtc pack publish my-feature-1.0.0.gtpack --registry ghcr.io/greentic

Descargar desde el registro

gtc pack pull ghcr.io/greentic/my-feature:1.0.0

Usar en un Bundle

greentic.demo.yaml

apps:
  my-app:
    pack: "oci://ghcr.io/greentic/my-feature:1.0.0"

Plantillas de Pack

Plantilla de Pack de Provider

pack.toml

[pack]
name = "messaging-custom"
version = "1.0.0"
description = "Custom messaging provider"

[capabilities]
id = "greentic.cap.messaging.provider.v1"
provides = ["custom"]

[flows]
setup_default = "flows/setup.ygtc"
verify_webhooks = "flows/verify.ygtc"

[components]
ingress = "components/ingress.wasm"
egress = "components/egress.wasm"
operator = "components/operator.wasm"

[secrets]
required = ["api_key"]
optional = ["webhook_secret"]

Plantilla de Pack de Aplicación

pack.toml

[pack]
name = "helpdesk-bot"
version = "1.0.0"
description = "IT Helpdesk bot"

[capabilities]
id = "greentic.cap.app.v1"
provides = ["helpdesk"]

[dependencies]
greentic-templates = "^0.4"
greentic-llm-openai = "^0.4"

[flows]
on_message = "flows/on_message.ygtc"
on_ticket = "flows/on_ticket.ygtc"

[assets]
cards = "assets/cards/"
templates = "assets/templates/"

Buenas prácticas

1. Versiona semánticamente - Usa semver (MAJOR.MINOR.PATCH)
2. Firma todas las releases - Nunca distribuyas packs sin firmar
3. Incluye SBOM - Documenta dependencias para auditorías de seguridad
4. Prueba antes de publicar - Valida flows y prueba components
5. Documenta a fondo - Incluye un README en el pack
6. Mantén los packs enfocados - Una funcionalidad o provider por pack
7. Usa CI/CD - Automatiza build y publicación

Ejemplo de CI/CD

.github/workflows/pack.yml

name: Build and Publish Pack

on:
  push:
    tags:
      - 'v*'

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Rust
        uses: dtolnay/rust-toolchain@1.90.0

      - name: Build Pack
        run: gtc pack build ./my-pack

      - name: Sign Pack
        run: |
          echo "${{ secrets.SIGNING_KEY }}" > key.pem
          gtc pack sign my-feature-*.gtpack --key key.pem

      - name: Publish
        run: |
          gtc pack login ghcr.io --username ${{ github.actor }} --password ${{ secrets.GITHUB_TOKEN }}
          gtc pack publish my-feature-*.gtpack --registry ghcr.io/${{ github.repository }}

Siguientes pasos

• Referencia del formato de Pack - Especificación completa
• Referencia del esquema de Flow - Esquema YAML
• Guía de Components - Construcción de components WASM