Los comandos — pcreative Commerce

Hay tres herramientas de línea de comandos, una por cosa que se construye:

Comando	Para qué	Viene en
`pcc`	la tienda: base de datos, arranque, tareas, accesos	el backend (`apps/backend`)
`pcc-theme`	los temas: crear, validar, empaquetar, firmar	`@pcreative/theme-contract`
`pcc-plugin`	los plugins: crear, comprobar, probar	`@pcreative/plugin-contract`

Tras npm ci en la raíz, los tres están en node_modules/.bin/. Llámalos por esa ruta y no con npx a secas: npx puede bajarse y ejecutar otro paquete que se llame igual.

🔴 node_modules/.bin/pcc ejecuta la copia compilada de apps/backend/dist/ si existe, aunque sea más vieja que tu código. Solo si no hay dist/ ejecuta el código fuente. npm run pcc ejecuta siempre el código fuente.

pcc

La tienda. Desde apps/backend:

npm run pcc -- <comando>

Sin comando, o con ayuda, -h o --help, enseña la lista. Casi todos necesitan DATABASE_URL; sin ella se paran con un aviso antes de tocar nada.

Comando	Qué hace
`pcc instalar`	Crea el esquema completo en una base vacía y aplica las migraciones.
`pcc migrar`	Aplica las migraciones que falten.
`pcc esquema`	Compara la base con la foto del esquema y dice qué cambia.
`pcc preparar`	Deja la base lista para arrancar: instala o migra, y prepara la tienda.
`pcc arrancar`	Levanta la tienda: base, avisos, tareas y HTTP. También vale `start`.
`pcc dev`	Igual que `arrancar`, pero recarga al guardar un fichero.
`pcc construir`	Compila el TypeScript a `dist/`.
`pcc ejecutar <guion> [args…]`	Corre un guion con el contenedor de la tienda. También vale `exec`.
`pcc tareas`	Enseña cómo van las tareas programadas.
`pcc rescate [orden] [correo]`	Da acceso al panel desde la consola.

Cuáles leen el `.env`

Todos los guiones npm run del backend leen apps/backend/.env por su cuenta: npm run dev, npm start, npm run pcc, npm run preparar, npm run rescate, npm run seed y npm run seed:market. Le pasan a Node --env-file-if-exists=.env, así que una variable que ya esté en el entorno manda sobre el fichero, y si no hay .env siguen con lo que haya en el entorno. Lánzalos desde apps/backend, o desde la raíz con npm run <guion> -w @pcreative/commerce-backend.

El binario suelto, node_modules/.bin/pcc, no lo lee: sin las variables en el entorno se para con Falta DATABASE_URL. Usa npm run pcc -- <orden>, o deja que lo cargue Node:

node --env-file=.env ../../node_modules/.bin/pcc tareas

`pcc instalar`

Solo trabaja sobre una base vacía. Si ya hay tablas, se para sin tocar nada: instalar encima de una base con datos no es lo que quieres. Si de verdad lo es, existe --igual.

Crea el esquema en una sola transacción: si algo falla, no queda a medias. Después aplica las migraciones y compara el resultado con la foto del esquema; si no casa, termina en error y dice qué difiere.

`pcc migrar`

Aplica las migraciones pendientes y dice cuántas eran y cuántas hay en total. Con --sin-tienda no prepara los datos de la tienda, solo el esquema.

Una migración ya aplicada no se vuelve a aplicar ni se puede cambiar: la tienda guarda su huella y se niega a seguir si no coincide.

`pcc esquema`

Compara la base de ahora con la foto guardada del esquema y separa lo que rompe de lo que no.

pcc esquema foto guarda la foto de la base actual. A partir de ahí, cualquier cambio del esquema aparece en el control de versiones como una línea.
Sin foto, te dice cómo hacerla.

`pcc preparar`

El comando para una instalación nueva o para después de actualizar:

Si la base está vacía, instala el esquema. Si no, aplica lo que falte.
Prepara la tienda: crea lo que falte para poder vender.
Enseña la clave publicable (PUBLISHABLE_KEY=…).

Con --clave <fichero> (o la variable KEY_OUTPUT_FILE) escribe además la clave en ese fichero. Si la tienda ya estaba preparada, lo dice y no duplica nada.

npm run preparar es lo mismo.

`pcc arrancar` y `pcc dev`

arrancar levanta la tienda como va en el servidor. dev hace lo mismo y la reinicia al guardar un fichero.

🔴 Lanzados con el binario suelto, ninguno de los dos lee el .env por su cuenta (mira Cuáles leen el .env). npm run dev, npm start y npm run pcc -- arrancar sí lo leen. pcc dev busca ./src/scripts/arrancar-propio.ts en la carpeta actual: lánzalo desde apps/backend.

`pcc construir`

Compila con tsconfig.build.json y deja el resultado en dist/. El panel es otra aplicación y no sale de aquí.

npm run build compila lo mismo y además copia src/propio/esquema a dist/, cosa que pcc construir no hace. Si vas a ejecutar desde dist/ (npm start, node_modules/.bin/pcc), construye con npm run build.

`pcc ejecutar`

npm run pcc -- ejecutar ./src/scripts/probar-marketplace.ts uno dos

El guion tiene que exportar una función por defecto (o main). La recibe con { contenedor, args }: el contenedor de la tienda, ya conectado a la base, y el resto de argumentos. Al terminar, la conexión se cierra sola.

`pcc tareas`

Una línea por tarea programada: cuándo toca la próxima vez, cuántos fallos lleva y el último error. Marca las que nunca se han ejecutado, que suelen ser las que alguien dio por hechas.

`pcc rescate`

Para cuando te quedas fuera del panel. npm run rescate es lo mismo.

Orden	Qué hace
(ninguna)	Enseña las sesiones abiertas y quién tiene acceso: rol, si está suspendida, con y sin contraseña.
`alta <correo>`	Crea un acceso de Administrador al panel con una contraseña nueva.
`clave <correo>`	Pone una contraseña nueva a un acceso que ya existe, y lo reactiva si estaba suspendido.
`admin <correo>`	Hace Administrador a esa cuenta y la reactiva.
`cerrar <correo>`	Cierra todas las sesiones abiertas de ese correo.

La contraseña nueva se enseña una vez y no se guarda en ningún sitio. Cámbiala al entrar: ha pasado por la pantalla y por el historial de tu terminal. alta y clave cierran además las sesiones que hubiera abiertas.

Cada rescate queda apuntado en el historial de auditoría, con quién lo hizo desde la consola.

pcc-theme

Los temas. Sin carpeta, cada comando trabaja sobre la actual.

Comando	Qué hace
`pcc-theme init [dir]`	Crea un tema nuevo que ya vende y ya valida.
`pcc-theme validate [dir]`	Valida la forma y la coherencia del paquete.
`pcc-theme audit [dir]`	Revisa el tema antes de instalarlo.
`pcc-theme pack [dir]`	Valida, audita, busca secretos, construye y empaqueta un `.zip` que el panel acepta.
`pcc-theme sign [dir]`	Firma el tema.
`pcc-theme verify [dir]`	Comprueba la firma.
`pcc-theme css [dir]`	Emite las variables CSS resueltas.
`pcc-theme info [dir]`	Resumen del tema.

Cualquier otra cosa enseña la ayuda. Si algo falla, termina con código 1.

`init`

Opción	Qué hace
`--id <id>`	El identificador del tema. Si no lo das, sale del nombre de la carpeta. Sin carpeta y sin `--id`, se para: dale una de las dos.
`--name "<nombre>"`	El nombre que se enseña.
`--stack <stack>`	`next` (por defecto), `astro`, `sveltekit`, `nuxt`, `react-router` o `vite-react`.
`--author <quien>`	El autor.
`--description "<texto>"`	La descripción.
`--registro`	Toma los contratos del registro de npm aunque estés dentro del repositorio.

No pisa nada: si un fichero ya existe, lo deja y te avisa. Dentro del repositorio, el tema apunta a los contratos de packages/ para que pruebes con los de tu copia; con --registro, a los publicados.

`validate`

Dos pasadas. La de forma valida cada JSON contra su esquema (si no está instalado ajv, se la salta y lo dice). La de coherencia busca lo que ningún esquema ve: un campo que apunta a un token que no existe, un bloque que el tema no implementa, un override de otra versión. Con errores, termina en 1; los avisos no cortan.

`audit`

Enseña qué se ejecutaría al instalar el tema (instalar, construir, arrancar), a qué dominios habla y qué bloquea la instalación. Con bloqueantes, termina en 1.

--monorepo audita como si el tema viviera dentro del repositorio.

`pack`

Siete pasos, y se para en el primero que falle:

Valida el contrato.
Audita solo lo que va a viajar en el zip.
Decide qué ficheros entran y busca secretos. Si ve algo que parece una clave, se para: un tema se descarga y lo lee todo el que lo compre.
Cambia las dependencias @pcreative/* que apuntan a una carpeta local (file:) por una copia empaquetada dentro del tema.
Instala y construye de verdad, en una carpeta aparte.
Firma, si le das --key y --publisher.
Escribe el zip.

Opción	Qué hace
`--salida <f.zip>`	Dónde escribir el zip. Por defecto, `<id>-<versión>.zip`.
`--key <f.pem>`	La clave privada para firmar. Va con `--publisher`.
`--publisher <quien>`	Quién firma. Va con `--key`.
`--kid <id>`	El identificador de la clave. Por defecto, `1`.
`--sin-construir`	Se salta el paso 5. Validar no prueba que un tema compile; úsalo sabiendo eso. Sin construir, el tema tiene que traer su fichero de bloqueo o el panel lo rechaza.

Sin firma, el zip sale igual y el panel lo instala avisando de que no se sabe quién lo hizo.

`sign`

pcc-theme sign temas/mi-tema --key privada.pem --publisher "Tu estudio" --kid 2

Pide --key y --publisher, los dos. --kid es opcional (por defecto, 1). Deja la firma en theme.sig.

`verify`

pcc-theme verify temas/mi-tema --pubkey publica.pem
pcc-theme verify temas/mi-tema --url https://ejemplo.com/clave-publica

Pide una de las dos: --pubkey (un fichero) o --url (de donde bajar la clave pública). Si la firma no casa, dice qué ficheros están alterados, cuáles sobran y cuáles faltan, y termina en 1.

`css`

Opción	Qué hace
`--out <fichero>`	Escribe el CSS en un fichero. Sin ella, a la salida estándar.
`--selector <s>`	El selector que envuelve las variables. Por defecto, `:root`.

Los avisos salen por la salida de errores, así que puedes redirigir el CSS sin que se cuelen.

`info`

Id y versión, stack, páginas, bloques, funciones, idiomas, cuántos tokens y cuántos ajustes. Si hay errores o avisos, dice cuántos y te manda a validate.

Más sobre qué valida cada comando: Contrato de tema.

pcc-plugin

Los plugins. Sin carpeta, comprobar y dev trabajan sobre la actual.

Comando	Qué hace
`pcc-plugin nuevo <nombre>`	Crea un plugin que ya funciona.
`pcc-plugin comprobar [dir]`	Dice qué está mal, todo de una vez.
`pcc-plugin dev [dir]`	Lo carga y lo recarga al guardar.

Cualquier otra cosa enseña la ayuda.

`nuevo`

El nombre va en minúsculas, números y guiones, y la carpeta no puede existir. Crea plugin.json, src/index.js, package.json, jsconfig.json, README.md y .gitignore. El plugin de ejemplo escucha pedido.creado y lo apunta en el registro, y su package.json ya trae npm run dev y npm run comprobar.

`comprobar`

Lee plugin.json, lo valida y mira que exista el fichero de entry. Enseña todos los errores y avisos juntos, no el primero. Con errores, termina en 1.

Si está bien, enseña el nombre, la versión, dónde corre y lo que podrá hacer, con los permisos delicados marcados.

`dev`

Carga el plugin en modo desarrollo, que no comprueba la licencia y lo avisa, y lo recarga cada vez que guardas un fichero (menos en node_modules y .git). Ctrl+C para salir.

Lo carga fuera de la tienda, en un bus propio: comprueba que arranca, que sus puntos de enganche existen y que declara el permiso que cada uno pide. Los eventos de verdad le llegan cuando lo instalas en la tienda.

Más: Escribir un plugin.

Otros comandos

El instalador

sh instalar.sh [pcreative-commerce-<versión>.zip]

Vive en scripts/instalar.sh y el empaquetador de versiones deja una copia al lado del zip. Sin argumento, coge el pcreative-commerce-*.zip más reciente de la carpeta actual. Comprueba el zip contra su .sha256 si lo tiene al lado, instala unzip y Docker si faltan, exige 12 GB libres, crea 4 GB de swap si la máquina tiene menos de 4,5 GB de RAM y menos de 1 GB de swap, descomprime, crea el .env a partir de .env.docker.example con una POSTGRES_PASSWORD aleatoria y lanza docker compose up -d --build. Se puede lanzar dos veces: si la carpeta ya existe la usa, y si ya había algo en marcha actualiza sin borrar datos. Apunta todo lo que hace en un instalar-<fecha>.log. Los mensajes salen en inglés, o en español si el idioma del sistema es español.

Paso a paso: Instalación.

El empaquetador de versiones

node scripts/empaquetar-release.mjs [--ref <commit>] [--salida <fichero.zip>]

Desde la raíz del repositorio. Toma el código de git (HEAD por defecto, así que no entra nada sin commitear), construye las imágenes de Docker de cada pieza, se queda solo con los programas compilados y escribe dist/pcreative-commerce-<versión>.zip con su .sha256, más instalar.sh y su .sha256. Si encuentra dentro código fuente, mapas de código, secretos, un .env de verdad o el tema de un cliente, no escribe el zip y enumera los problemas. Necesita git y Docker.

Atajos en la raíz

Comando	Qué hace
`npm run dev:backend`	`npm run dev` del backend.
`npm run dev:admin`	`npm run dev` del panel.
`npm run build:backend`	`npm run build` del backend.
`npm run build:admin`	`npm run build` del panel.
`npm run seed`	`npm run seed` del backend.
`npm test`	Las pruebas de `packages/` y del panel.
`npm run theme -- <comando>`	`pcc-theme`.
`npm run dev:theme`	`npm run dev` del tema `mascotas`.
`npm run docs`	Regenera la referencia de `docs/es/referencia/`.
`npm run docs:estricto`	Lo mismo, y termina en error si una ruta de la API no tiene explicación o una variable no tiene ejemplo.

Otros guiones del backend

Desde apps/backend:

Comando	Qué hace
`npm run seed`	Carga productos de demostración, con fotos de relleno en `static/demo/`, y tarifas de envío. Antes, `pcc preparar`. Si ya estaba cargada, sustituye los productos de demostración anteriores. Lee el `.env`.
`npm run seed:market`	Crea la demo del mercado de temas y extensiones: cuatro autores y diez piezas que pasan por la misma subida, revisión y publicación que un vendedor de verdad. No duplica si ya está. `npm run seed:market -- --limpiar` la borra. Lee el `.env`.
`npm run comprobar:imports`	Busca imports que no resuelven, paquetes que se usan sin estar declarados en `package.json` y código de producción que depende de un guion de pruebas `probar-`. Termina en error si encuentra alguno. `comprobar:imports:ver` explica cada uno con detalle.

Los comandos — pcreative Commerce

En esta página