Paquetes

Todo lo que construyes en ObjectOS reside en un paquete: un conjunto de metadatos versionado y autocontenido. Los paquetes son la unidad sobre la que trabaja el AI Builder, la unidad que distribuye el marketplace y la unidad respecto a la que ObjectOS rastrea las actualizaciones.

Qué contiene un paquete

com.acme.crm@1.2.0
├── manifest          id, version, namespace, dependencies
├── objects/          *.object.ts, *.state.ts, *.hook.ts
├── views/            *.view.ts, *.page.ts, *.form.ts
├── actions/          *.action.ts
├── flows/            *.flow.ts, *.approval.ts
├── agents/           *.agent.ts, *.skill.ts
├── permissions/      *.permission.ts
├── sharing/          *.sharing.ts
├── translations/     en.ts, zh-CN.ts, ...
├── apps/             *.app.ts  (navigation)
└── data/             defineDataset(...) seed

Cada artefacto de metadatos (objeto, acción, flujo, …) pertenece a exactamente un paquete. El id del paquete sigue el formato DNS inverso (com.acme.crm, org.mycompany.helpdesk) y el prefijo del namespace (crm_, hd_) evita que los nombres de tablas / objetos colisionen entre paquetes instalados en el mismo tenant.

Crear un paquete

Desde el AI Builder

"Inicia un nuevo paquete para nuestro CRM interno, con el namespace crm."

La IA invoca create_package y set_active_package. A partir de ese momento, cada objeto / campo / acción que describas se ubica en crm.

Desde la CLI

os init my-crm -t app
cd my-crm
# manifest lives in the `manifest:` block of ./objectstack.config.ts
pnpm dev

Desde Console

Console → Packages → New Package — nombre, id, versión, namespace.

Paquete activo

En el AI Builder, una conversación lleva asociado un paquete activo: el contenedor predeterminado para los nuevos metadatos. La IA lo establece con la herramienta set_active_package cuando dices algo como "Cambia a com.acme.helpdesk." Desde la CLI, el paquete activo es simplemente el declarado en el objectstack.config.ts del proyecto (el bloque manifest:).

Versionado

Los paquetes usan semver. Las mismas reglas que el runtime — consulta Changelog & Versioning.

Incrementar una versión no cambia nada hasta que publicas. El runtime rastrea installed_version por tenant y por paquete, y el marketplace muestra una insignia de "Update available" cuando el catálogo tiene una versión más reciente.

Dependencias

Los paquetes pueden depender de otros paquetes:

{
  "id": "com.acme.helpdesk",
  "version": "0.3.0",
  "dependencies": {
    "com.acme.crm": "^1.0.0",
    "sys.feeds":   "*"
  }
}

El runtime resuelve las dependencias durante la instalación. Si com.acme.crm no está instalado, la instalación del helpdesk falla con un error claro.

Los paquetes de sistema (sys.*) siempre están presentes — feeds, adjuntos, auditoría, identidad, etc.

Publicar

os compile                     # → dist/objectstack.json
os package publish             # → ObjectStack cloud catalog

os package publish sube el manifiesto compilado al plano de control en la nube configurado por OS_CLOUD_URL, autenticado con OS_CLOUD_API_KEY. Para distribución privada / sin conexión (air-gapped), omite la publicación y entrega el dist/objectstack.json compilado directamente a la instalación de destino (consulta Instalación más abajo). Consulta Marketplace.

Instalar

La instalación fusiona los metadatos del paquete en el kernel en vivo, registra sus objetos con ObjectQL y carga los datos iniciales en la primera instalación — sin necesidad de reiniciar. Las instalaciones en caché se vuelven a registrar en el siguiente arranque, por lo que sobreviven a los reinicios del proceso.

Desinstalar

Desinstalar elimina el manifiesto en caché del paquete para que ya no se vuelva a registrar en el siguiente arranque. Como el registro de objetos es aditivo, se requiere un reinicio del kernel para descargar por completo los objetos de un paquete ya en ejecución. Los datos se conservan de forma predeterminada, por lo que puedes reinstalar y continuar.

Convenciones entre paquetes

Para evitar colisiones cuando coexisten muchos paquetes:

Tanto la CLI como el AI Builder aplican esto al momento de la creación.

Paquetes de sistema

El runtime incluye un pequeño conjunto de paquetes siempre presentes que proporcionan servicios polimórficos:

Los habilitas mediante enable: { feeds: true, trackHistory: true, … } en tus objetos — consulta Data Model.

A dónde ir después

• Marketplace — distribuye paquetes a otros tenants
• Data Model — qué va dentro de un paquete
• os package commands — referencia completa de la CLI