The commands — pcreative Commerce

There are three command-line tools, one for each thing you build:

After npm ci at the root, all three are in node_modules/.bin/. Call them by that path and not with bare npx: npx can download and run a different package with the same name.

🔴 node_modules/.bin/pcc runs the compiled copy in apps/backend/dist/ if it exists, even if it is older than your code. Only when there is no dist/ does it run the source. npm run pcc always runs the source.

The command names are in Spanish, as they are typed.

pcc

The store. From apps/backend:

npm run pcc -- <command>

With no command, or with ayuda, -h or --help, it prints the list. Almost all of them need DATABASE_URL; without it they stop with a message before touching anything.

Which ones read .env

Every npm run script of the backend reads apps/backend/.env on its own: npm run dev, npm start, npm run pcc, npm run preparar, npm run rescate, npm run seed and npm run seed:market. They pass --env-file-if-exists=.env to Node, so a variable already in the environment wins over the file, and if there is no .env they carry on with what is in the environment. Run them from apps/backend, or from the root with npm run <script> -w @pcreative/commerce-backend.

The bare binary, node_modules/.bin/pcc, does not read it: without the variables in the environment it stops with Falta DATABASE_URL. Use npm run pcc -- <command>, or let Node load the file:

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

pcc instalar

It only works on an empty database. If there are tables already, it stops without touching anything: installing over a database with data is not what you want. If it really is, there is --igual.

It creates the schema in a single transaction: if something fails, nothing is left half done. Then it applies the migrations and compares the result with the schema snapshot; if it does not match, it ends in error and says what differs.

pcc migrar

Applies the pending migrations and says how many there were and how many there are in total. With --sin-tienda it does not prepare the store's data, only the schema.

A migration already applied is never applied again and cannot be changed: the store keeps its hash and refuses to go on if it does not match.

pcc esquema

Compares the current database with the saved schema snapshot and separates what breaks things from what does not.

• pcc esquema foto saves a snapshot of the current database. From then on, any schema change shows up in version control as a line.
• With no snapshot, it tells you how to take one.

pcc preparar

The command for a new install, or for after an update:

1. If the database is empty, it installs the schema. If not, it applies what is missing.
2. It prepares the store: creates whatever is missing to be able to sell.
3. It prints the publishable key (PUBLISHABLE_KEY=…).

With --clave <file> (or the KEY_OUTPUT_FILE variable) it also writes the key to that file. If the store was already prepared, it says so and duplicates nothing.

npm run preparar is the same.

pcc arrancar and pcc dev

arrancar starts the store the way it runs on the server. dev does the same and restarts it when you save a file.

🔴 Called as the bare binary, neither reads .env on its own (see Which ones read .env). npm run dev, npm start and npm run pcc -- arrancar do. pcc dev looks for ./src/scripts/arrancar-propio.ts in the current folder: run it from apps/backend.

pcc construir

Compiles with tsconfig.build.json and leaves the result in dist/. The panel is a separate application and does not come out of here.

npm run build compiles the same and also copies src/propio/esquema into dist/, which pcc construir does not. If you are going to run from dist/ (npm start, node_modules/.bin/pcc), build with npm run build.

pcc ejecutar

npm run pcc -- ejecutar ./src/scripts/probar-marketplace.ts one two

The script must export a default function (or main). It receives { contenedor, args }: the store's container, already connected to the database, and the remaining arguments. When it finishes, the connection closes by itself.

pcc tareas

One line per scheduled job: when it runs next, how many failures it has and the last error. It flags the ones that have never run, which tend to be the ones someone assumed were working.

pcc rescate

For when you are locked out of the panel. npm run rescate is the same.

The new password is shown once and is not stored anywhere. Change it when you log in: it has been on the screen and in your terminal history. alta and clave also close any sessions that were open.

Every rescue is recorded in the audit history, with who did it from the console.

pcc-theme

Themes. With no folder, every command works on the current one.

Anything else prints the help. If something fails, it exits with code 1.

init

It overwrites nothing: if a file already exists, it leaves it and warns you. Inside the repository, the theme points at the contracts in packages/ so you test with your copy's; with --registro, at the published ones.

validate

Two passes. The shape pass validates each JSON file against its schema (if ajv is not installed, it skips it and says so). The coherence pass looks for what no schema sees: a field pointing at a token that does not exist, a block the theme does not implement, an override from another version. With errors it exits with 1; warnings do not stop it.

audit

Shows what would run when installing the theme (install, build, start), which domains it talks to and what blocks the install. With blockers it exits with 1.

--monorepo audits as if the theme lived inside the repository.

pack

Seven steps, and it stops at the first one that fails:

1. Validates the contract.
2. Audits only what will travel in the zip.
3. Decides which files go in and looks for secrets. If it sees something that looks like a key, it stops: a theme is downloaded and read by everyone who buys it.
4. Replaces @pcreative/* dependencies pointing at a local folder (file:) with a packaged copy inside the theme.
5. Installs and really builds, in a separate folder.
6. Signs, if you give it --key and --publisher.
7. Writes the zip.

Unsigned, the zip still comes out and the panel installs it warning that nobody knows who made it.

sign

pcc-theme sign themes/my-theme --key private.pem --publisher "Your studio" --kid 2

Needs --key and --publisher, both. --kid is optional (default 1). It writes the signature to theme.sig.

verify

pcc-theme verify themes/my-theme --pubkey public.pem
pcc-theme verify themes/my-theme --url https://example.com/public-key

Needs one of the two: --pubkey (a file) or --url (where to fetch the public key). If the signature does not match, it lists which files are altered, which are extra and which are missing, and exits with 1.

css

Warnings go to standard error, so you can redirect the CSS without them getting in.

info

Id and version, stack, pages, blocks, features, languages, how many tokens and how many settings. If there are errors or warnings, it says how many and sends you to validate.

More on what each command checks: Theme contract.

pcc-plugin

Plugins. With no folder, comprobar and dev work on the current one.

Anything else prints the help.

nuevo

The name is lowercase letters, digits and hyphens, and the folder must not exist. It creates plugin.json, src/index.js, package.json, jsconfig.json, README.md and .gitignore. The example plugin listens to pedido.creado and writes it to the log, and its package.json already has npm run dev and npm run comprobar.

comprobar

Reads plugin.json, validates it and checks that the entry file exists. It shows every error and warning together, not just the first. With errors it exits with 1.

If it is fine, it shows the name, the version, where it runs and what it will be able to do, with the sensitive permissions flagged.

dev

Loads the plugin in development mode, which skips the licence check and says so, and reloads it every time you save a file (except in node_modules and .git). Ctrl+C to quit.

It loads it outside the store, on its own bus: it checks that it starts, that its hooks exist and that it declares the permission each one needs. Real events reach it once you install it in the store.

More: Write a plugin.

Other commands

The installer

sh instalar.sh [pcreative-commerce-<version>.zip]

It lives in scripts/instalar.sh and the release packager leaves a copy next to the zip. Without an argument it takes the most recent pcreative-commerce-*.zip in the current folder. It checks the zip against its .sha256 if there is one next to it, installs unzip and Docker if they are missing, demands 12 GB free, creates 4 GB of swap if the machine has less than 4.5 GB of RAM and less than 1 GB of swap, unzips, creates .env from .env.docker.example with a random POSTGRES_PASSWORD, and runs docker compose up -d --build. It can be run twice: if the folder already exists it uses it, and if something is already running it updates without deleting data. It writes everything it does to an instalar-<date>.log. Messages come out in English, or in Spanish if the system language is Spanish.

Step by step: Installation.

The release packager

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

From the repository root. It takes the code from git (HEAD by default, so nothing uncommitted goes in), builds the Docker images of every piece, keeps only the compiled programs and writes dist/pcreative-commerce-<version>.zip with its .sha256, plus instalar.sh and its .sha256. If it finds source code, source maps, secrets, a real .env or a client's theme inside, it writes no zip and lists the problems. It needs git and Docker.

Shortcuts at the root

Other scripts of the backend

From apps/backend: