Communitygithub.com

Adrian7373/pipeline-video-semántico

Úsalo al desplegar o administrar una app que use Prisma Composer (`@prisma/composer`): conectar sus servicios y Módulos, ejecutarla localmente, probar servicios compuestos, o levantar/derribar un entorno.

¿Qué es pipeline-video-semántico?

Esta skill define los conceptos fundamentales de Prisma Composer, un framework para construir aplicaciones Prisma Cloud mediante declaraciones tipadas en TypeScript. Cubre la creación de servicios, recursos y módulos, el cableado a través de puertos tipados, y los dos canales de entrada: dependencias y entradas de configuración/credenciales. Explica el sistema de contratos RPC, la gestión de secretos, las migraciones replay-only para bases de datos, y que los builds son responsabilidad del desarrollador. También detalla la configuración de despliegue en `prisma.config.ts`, el manejo de builds para servidores planos y Next.js, y las reglas sobre claves de servicio, idempotencia y reintentos. Soporta los comandos `prisma deploy` y `prisma dev`, y se activa con referencias como "prisma composer", `@prisma/composer`, "prisma app", y operaciones como `compute()`, `module()`, `contract()`, `service.load()`, `mockService` y `bootstrapService`.

Compatible con~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Adrian7373/semantic-video-pipeline/tree/HEAD/packages/database/.agents/skills/prisma-composer-core-concepts

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

Conceptos centrales de Prisma Composer

Una App Prisma es un árbol de declaraciones tipadas compuestas en TypeScript y entregadas a la CLI prisma, que tiene dos comandos de Composer: prisma deploy y prisma dev. El derribo y los logs no son comandos; son las operaciones destroy y log de @prisma/composer/control, llamadas desde un script. Este archivo cubre estructuras, jerarquías, relaciones y flujos de trabajo: los conceptos que no se pueden observar desde el código o la ayuda de la CLI. No es una referencia de la CLI; descubre las banderas de cada comando con prisma <command> --help en lugar de inferirlas. La plataforma Prisma avanza rápido, así que trata este archivo como el núcleo conceptual estable y encuentra la documentación actual y completa en https://www.prisma.io/docs. Para código funcional, lee examples/ en el repositorio prisma/composer.

Dos principios lo gobiernan todo y son vinculantes (docs/design/01-principles/):

  1. Tu código nunca lee su entorno. Las dependencias, la configuración, las credenciales y el puerto llegan a través del nodo de servicio, tipado. process.env nunca es la respuesta.
  2. Composer nunca empaqueta ni transforma tu código. Tú construyes con tu propio empaquetador; el framework ensambla la salida construida mediante pasos deterministas y la entrega al destino de despliegue configurado.

Las declaraciones son datos

Todo lo que escribes es una declaración: datos simples que describen una pieza de la aplicación, que no ejecutan nada al importarse. Existen tres tipos de nodos:

TipoSe declara conPropósito
Serviciocompute()Una unidad de código en ejecución; atómica, Composer solo ve sus puertos
RecursorawPostgres(), bucket()Una dependencia gestionada con estado
Módulomodule()Un límite de agrupación; no ejecuta código propio, expone puertos tipados

Los nodos se conectan a través de puertos: deps declara lo que un nodo requiere, expose declara lo que ofrece. El cableado ocurre en el constructor de un Módulo mediante provision(), y el Módulo raíz, entregado a la CLI, es la App:

// module.ts
import { module } from '@prisma/composer';

export default module('store', ({ provision }) => {
  const catalog = provision(catalogModule);
  provision(storefrontService, { deps: { catalog: catalog.rpc } });
});

Como los puertos están tipados, el compilador verifica cada cable. Una dependencia conectada al productor incorrecto, un manejador RPC faltante, un valor de entrada literal con la forma incorrecta: todo falla en tsc, no en el despliegue. La entrada vinculada al entorno es la excepción: esos valores existen solo en el despliegue, por lo que los desajustes de enlace secreto y las variables de plataforma faltantes aparecen como rechazos tempranos en el despliegue (ver Dos canales a continuación). Verifica tipos, luego construye, luego despliega; no uses la nube para descubrir si el cableado es correcto.

Composer en sí mismo es independiente del destino: @prisma/composer lleva la autoría, las pruebas y la CLI, sin acoplarse a ninguna plataforma. Un destino de despliegue es una extensión registrada en la configuración de despliegue; @prisma/composer-prisma-cloud es el destino Prisma Cloud y el que asumen las secciones de despliegue de esta skill. Sus exportaciones raíz son compute, rawPostgres, bucket, envSecret y envParam; el vocabulario ORM (postgres, dataContract) vive bajo la subruta /orm, junto con los módulos compartidos /cron, /storage, /streams, /auth y /email. Estos son los únicos dos paquetes de Composer que necesita una app básica de Prisma Cloud, y nada los instala por ti: un proyecto nuevo comienza sin ninguno, así que agrega ambos como dependencias primero. Una extensión agrega su propio paquete prisma-composer-* junto a ellos. Compón un Módulo existente antes de implementar una capacidad tú mismo; cablear uno son un par de líneas.

Dentro del grafo de entrada (todo lo alcanzable desde module.ts), escribe importaciones relativas con extensiones .ts explícitas (./service.ts, con allowImportingTsExtensions en tsconfig): esa forma se resuelve en todas partes. prisma deploy y prisma dev también asignan ./service.js y ./service sin extensión a la fuente .ts, pero otras herramientas pueden no hacerlo.

El nodo de servicio es la única puerta de entrada

Tu código en tiempo de ejecución recibe todo desde la declaración de servicio que importa:

  1. service.load(): dependencias (clientes RPC tipados, enlaces de base de datos).
  2. service.input(): toda la entrada como un objeto validado por esquema; las credenciales en él son cajas SecretString que se redactan.
  3. service.port(): el puerto reservado para enlazar (por defecto 3000).

Una declaración de servicio son datos puros; el punto de entrada del servidor es lo que tu compilación produce y la plataforma arranca:

// service.ts
export default compute({
  name: 'auth',
  deps: { db: rawPostgres() },
  build: node({ module: import.meta.url, entry: '../dist/server.mjs' }),
  expose: { rpc: authContract },
});

// server.ts
const { db } = service.load(); // { url }: construyes tu propio cliente
const handler = serve(service, {
  rpc: { verify: async ({ token }) => ({ ok: token.length > 0 }) },
});
Bun.serve({ port: service.port(), hostname: '0.0.0.0', fetch: handler });

El consumidor declara deps: { auth: rpc(authContract) } y obtiene un cliente tipado de load().

Dos canales: dependencias y entrada

El valor es…DeclaraProporcionaLee
producido por otro nododeps: { db: rawPostgres() }cablea en provision()load()
cualquier otra cosa (configuración o credencial)un campo del esquema inputenlaza en provision(): literal, envParam() o envSecret()input()

El servicio declara toda su configuración entrante, valores simples y credenciales juntos, como un Standard Schema (arktype es la elección de la casa). Una credencial es un campo tipado como secretString() de @prisma/composer/arktype; la legalidad condicional ("sin clave de stripe a menos que la facturación esté activa") es una unión de esquema ordinaria. El enlace en provision() refleja la forma del esquema; envSecret('NAME') nombra la variable de plataforma y nunca lleva el valor.

Reglas que muerden:

  1. El secreto se aplica mediante validación. Un literal enlazado donde el esquema espera SecretString falla el despliegue; envSecret enlazado a un campo de cadena simple falla de la misma manera.
  2. Los valores de envParam llegan como cadenas sin procesar; enlázalos a campos de cadena. La variable de plataforma del stage es el almacén; el shell de despliegue solo siembra un nombre faltante (y el despliegue falla temprano, nombrando la variable, cuando ambos faltan). Cambiar el valor de la plataforma necesita un redespliegue.
  3. La ausencia es decisión del esquema. Un campo vinculado al entorno cuya variable no está establecida o está vacía se resuelve como clave omitida, lo cual es legal solo si el esquema lo permite (campo opcional, rama de unión). El informe de despliegue imprime el documento de entrada serializado (los secretos viajan como punteros {"$secret":"VAR"}) y cada clave que se resolvió ausente.
  4. El port reservado está fuera del esquema. Léelo a través de service.port(), nunca de process.env. El framework también exporta PORT para Next.js standalone, que lo enlaza por sí mismo.
  5. Un Módulo reenvía una necesidad secreta sin conocer el nombre de la plataforma. Declara secrets: { signingKey: secret() } en el límite del Módulo y pasa la referencia reenviada como una hoja de enlace; el padre enlaza la fuente real.
  6. input.apiKey.expose() es la única forma de acceder al valor de un secreto; la caja redacta en todos los demás lugares (logs, JSON, errores).

Contratos y RPC

Un contrato es la interfaz tipada a través de la cual se comunican los servicios. Vive con el servicio que lo posee, tipado por cualquier validador Standard Schema, y tanto el proveedor (serve(), exhaustivo sobre los métodos del contrato en tiempo de compilación) como el consumidor (rpc(contract)) referencian el mismo valor. Las llamadas viajan como RPC sobre HTTP. Dos comportamientos se aprovisionan por ti y no deben ser reimplementados:

  1. Claves de servicio. En el despliegue, Composer acuña una clave única e inescrutable por enlace consumidor→proveedor; serve() devuelve 401 a cualquier otra cosa antes de que el manejador se ejecute. Nada en tu código lo declara. Consecuencias: no construyas tu propia autenticación servicio a servicio, y no hagas curl a un /rpc/<method> desplegado para verificar que funciona. Un llamador no cableado siempre obtiene 401, que parece un despliegue roto y no lo es. Depura a través de un consumidor, o localmente, donde no se aplica nada. Las claves son por enlace (una fuga no puede hacerse pasar por otro consumidor), con ámbito de servicio (cualquier clave válida alcanza todos los métodos; divide los servicios para controlar por separado), se rotan solo eliminando el enlace o destruyendo el stack y redeployando, y se almacenan en variables COMPOSER_* propiedad del despliegue que nunca editas a mano.
  2. Idempotencia y reintentos. Cada llamada de cliente generado lleva una Idempotency-Key; las llamadas descartadas se reintentan con backoff, y serve() ejecuta una llamada por clave, repitiendo la respuesta completada a reintentos tardíos. Por lo tanto, cada método es seguramente reintentable y ningún contrato declara nada al respecto (no hay una bandera "es idempotente"; no inventes una). Un manejador puede tomar un tercer argumento opcional (input, deps, ctx) y leer ctx.idempotencyKey (string | undefined) si necesita exactamente-una-vez más allá de la memoria de una instancia; la mayoría no lo necesita. Localmente y en pruebas no se aprovisiona nada, así que serve() pasa cada llamada: nunca proporciones una clave en las entradas de prueba.

Los builds son tuyos

Tú construyes, el framework ensambla. Para un proceso de servidor simple, entry debe apuntar a un único archivo ESM autocontenido: todo inline excepto los built-ins del runtime (bun, bun:*, node:*). El despliegue copia ese único archivo y nunca envía node_modules, así que cualquier cosa que quede sin inline falla en el arranque, no en el despliegue. Reglas que muerden:

  1. Dos servicios en un mismo paquete significan dos builds separados, uno por entrada. Un build de múltiples entradas divide el código compartido en un chunk que ninguna salida contiene.
  2. Un build de directorio usa dir + entry (dir relativo al módulo de servicio, entry un archivo dentro de dir; ../ es un error). El árbol se copia textualmente, así que el servidor debe resolver los hermanos contra import.meta.url, no el directorio de trabajo. El árbol no debe contener symlinks: el empaquetador los rechaza, nombra el enlace y el ensamblaje falla.
  3. Next.js: next build con output: 'standalone' es todo el build; nextjs({ module, appDir }) nombra la raíz de la app. Cualquier página o acción que llame a load() necesita export const dynamic = 'force-dynamic', porque el entorno de ejecución no existe en tiempo de build y Next ignora el entorno de ejecución para rutas prerenderizadas.
  4. Siempre construye antes de deploy o dev. Ninguno construye por ti.

La configuración de despliegue es la sección composer de prisma.config.ts, y nada más. Registra extensiones (prismaCloud(), nodeBuild(), nextjsBuild() cuando la app tiene un servicio Next.js) y el backend de estado de despliegue (prismaState()):

// prisma.config.ts
import { defineConfig as composer } from '@prisma/composer/config';
import { nodeBuild } from '@prisma/composer/node/control';
import { prismaCloud, prismaState } from '@prisma/composer-prisma-cloud/control';
import { definePrismaConfig } from 'prisma/config';

export default definePrismaConfig({
  composer: composer({ extensions: [prismaCloud(), nodeBuild()], state: prismaState() }),
});

Los comandos encuentran prisma.config.ts desde el directorio en el que se ejecutan, subiendo hasta la raíz del repositorio; el archivo más cercano que declara composer gana, y su sección se usa completa, nunca fusionada clave por clave. Solo se permiten extensions y state; cualquier otra clave es un error. El código de la app nunca importa el archivo.

Un prisma-composer.config.ts separado ya no se lee, y la configuración antigua es rechazada, nunca ignorada silenciosamente: CONFIG.SECTION_MISSING cuando ningún prisma.config.ts cargado declara una sección composer, CONFIG.FIELD_RETIRED cuando la sección todavía tiene configPath, CONFIG.FILE_RETIRED cuando un prisma-composer.config.* se encuentra junto al prisma.config.ts declarante; los tres bajo el CLI.CONFIG_SECTION_INVALID de la CLI. La solución para los tres es mover las extensions y state del archivo antiguo a la sección y eliminar el archivo antiguo. @prisma/composer-cli/family ya no exporta ComposerSection; el tipo de la sección es PrismaAppConfig de @prisma/composer/config.

Bases de datos y migraciones

Dos tipos de dependencia Postgres:

  1. rawPostgres(): el enlace es { url } y la app posee su cliente.
  2. postgres(...): una base de datos tipada por Prisma ORM. El enlace es { url, client } (ADR-0040): la URL de conexión sin procesar más el cliente tipado que Composer construye desde tu contrato de datos, de forma perezosa en el primer acceso, así que las consultas van a través de binding.client y se verifican en tiempo de compilación. Tanto postgres como dataContract se importan de @prisma/composer-prisma-cloud/orm, no de la raíz del paquete. Un valor envuelto por dataContract (emitido desde contract.prisma por prisma contract emit) es referenciado tanto por el extremo de dependencia (deps: { db: postgres(catalogData) }) como por el extremo del recurso, que también nombra la ruta de prisma.config.ts para que el paso de migración del despliegue pueda recargar el contract.json emitido y encontrar migrations/.

Los despliegues son solo-reproducción: aplican las migraciones confirmadas bajo migrations/ y nunca crean esquema por sí mismos. Cada cambio de esquema, incluido el primer esquema de una nueva base de datos, sigue un bucle:

  1. Edita contract.prisma.
  2. prisma contract emit regenera contract.json + contract.d.ts.
  3. prisma migration plan --name <slug> autoriza la migración (en un grafo vacío, esto autoriza la línea base).
  4. Confirma migrations/ con el cambio, luego despliega. Una base de datos nueva reproduce toda la ruta desde vacía.

Cada servicio que usa la base de datos se despliega solo después de que su migración se completa: una migración fallida significa que el nuevo código no se envía. El código antiguo sirve contra el nuevo esquema hasta que el nuevo despliegue esté activo, así que mantén cada migración compatible con el código que reemplaza.

Si ninguna ruta autorizada alcanza el contrato objetivo, el despliegue (y dev contra una base de datos local desactualizada) se niega con MIGRATION_PATH_NO

…

[truncado para traducción]

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

Skills relacionados