Buildcheck Dev

CRITICAL: A task is not complete while affected development containers show compilation, runtime, type, dependency, or template errors.

Shared component tip: If frontend logs show errors in shared components, check apps/frontend/src/app/shared/components/{component}/README.md before changing the component usage.

Core Rule

Development verification always uses watch-mode output — nothing else. Since 2026-08-30 that output comes from two places, because the frontend no longer runs in Docker:

Never run tsc, ngc, ng build, npm run build, npm run build:prod, or any npm run buildcheck* command as part of normal development, and never as an automatic pre-PR/pre-push gate. These commands hold multiple gigabytes of RAM on a machine that is already budgeted for the dev stack (see Memory Budget below) and freeze it.

The native ng serve is not an exception to that rule: it is a long-lived watcher you start once and leave running, not a one-shot build you fire to check something.

GitHub Actions (.github/workflows/ci.yml) already runs the build before merge/release, so a local build adds little and costs a lot. The only two legitimate reasons to run a build/typecheck command locally are:

1. The human explicitly asks, verbally, to test a build (any wording — "prueba el build", "corre un

build", "test the production build").

1. The human is preparing a release. Even then, suggest running buildcheck/build:prod and

wait for confirmation — do not run it unprompted. Mention that CI already gates it, so it is optional insurance, not a requirement.

Outside those two cases, a task is verified and complete using Docker logs alone.

Current Dev App Status Workflow

Use this workflow when the human asks how the development app is doing, whether the dev environment is healthy, or to "check app dev" before or after changes.

1. Check compose service state first:

docker compose ps
docker ps --filter "name=vendix_" --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"

1. Check short logs for the core development services:

docker logs --tail 80 vendix_backend
docker logs --tail 80 vendix_postgres
docker logs --tail 80 vendix_redis

There is no vendixfrontend container any more, so there is no docker logs vendixfrontend. Its replacement — and the ONLY frontend check an agent can perform — is:

bash scripts/buildcheck.sh --watch

It reports three things in one shot: whether ng serve is alive on :4200, the verdict of the LAST compile cycle, and the errors of that cycle. It compiles nothing and starts nothing.

It reads .dev/frontend-watch.log, which scripts/dev-fe.sh keeps trimmed to the current cycle only (hard ceiling 16 KB — it is rewritten on every cycle, never appended). That is deliberate: reading a whole build log is how an error that was already fixed gets reported as live. Since the file IS the last cycle, a reader cannot make that mistake.

Two answers that mean "do not trust this":

• RANCIO — the log survived but nothing listens on :4200. The watcher died; the last verdict

is history, not the state of the code. This is the failure a plain log read would report as healthy.

• SIN DATOS ... el proceso corre pero no pasó por scripts/dev-fe.sh — someone started

ng serve by hand. There is no log. Ask them to restart with npm run dev:fe.

Do NOT tell a human to "read the terminal where npm run dev:fe runs": an agent cannot see it, and neither can a second agent working the same tree.

To confirm the app answers at all, use the vhost — never localhost:4200, which has no row in domainsettings and makes the app resolve the wrong apptype:

curl -sk -o /dev/null -w "%{http_code}\n" https://vendix.com/

1. Run lightweight HTTP checks only after containers are running:

curl -fsS http://localhost:3000/api/health
curl -I -fsS http://localhost:4200

1. If vendix_nginx is part of the reported problem, also inspect:

docker logs --tail 80 vendix_nginx

1. Summarize status by service: running/stopped, recent errors, HTTP health result, and next required fix.

Do not treat a healthy HTTP response as enough if watch-mode logs still show TypeScript, Angular template, NestJS runtime, dependency, Prisma, Redis, or database errors.

Default Verification Workflow

1. Apply the code change.
2. Check the logs for every affected development container using docker logs --tail 40.
3. Check container status with docker ps.
4. If logs contain errors, fix them and repeat from step 2.
5. Finish only when affected containers are running and logs show zero relevant errors.

Development Commands

Use the commands that match the files changed:

Expected healthy signals include messages such as Compiled successfully, Successfully compiled, Nest application successfully started, /api/health returning status: ok, or database system is ready to accept connections.

Blocking signals include ERROR, ERROR in, TypeError, ReferenceError, TypeScript errors, Angular template parsing errors, missing dependency errors, Prisma generation errors, database syntax errors, Redis connection failures, or repeated container restarts.

Compilation/Build Checks — Never Automatic, Suggest-Only

HARD RULE: Do not run any command below during normal development or as a self-initiated
pre-PR/pre-push gate. Docker logs are the only required verification. These commands exist for the
two exceptions in the Core Rule (explicit human request, or release prep after the human confirms
the suggestion) and, even then, any command that starts a server, a watcher, or the Angular
prerender worker pool stays forbidden, because an aborted run leaves orphan Node processes
holding gigabytes of RAM.

When one of the two exceptions applies, use the guarded one-shot runner. It compiles, reports PASS/FAIL, and kills its whole process group on exit:

Properties of the runner (scripts/buildcheck.sh):

• Never serves, never watches, never prerenders.
• Each step runs in its own process group; the group is TERM/KILLed on exit,

timeout, or Ctrl-C, so esbuild and Angular workers cannot survive.

• Hard timeout (BUILDCHECK_TIMEOUT, default 900s) and RAM caps

(BUILDCHECKBEMEM 3072MB, BUILDCHECKFEMEM 4096MB).

• Steps run sequentially on purpose — running them in parallel is what exhausts RAM.
• Logs land in .buildcheck/<step>.log; failures print the first error lines.
• Backend typecheck is incremental (dist/tsconfig.build.tsbuildinfo): first run

is slow (~85s cold), later runs are seconds. Frontend typecheck ~15s warm.

• A preflight aborts before spawning anything if free RAM is below what the

step needs. Override only knowingly with --force.

Shared log path — do not trust the file under .buildcheck/

The runner writes its log to .buildcheck/<step>.log, a path that lives inside the repo and inside the shared dev tree. When more than one agent is working on the same checkout at once, the file is being written by N writers and read by N readers. A PASS line that this agent reads may belong to a different agent's run, on a different tree state, finished seconds ago or minutes ago. Reporting buildcheck PASS without confirming the log was produced by the local run on the final tree is reporting hearsay.

Two specific signals that a reported PASS is not trustworthy:

1. Total time landing exactly on BUILDCHECK_TIMEOUT (default 900 s). This is not coincidence: it is the pattern of the pipeline hanging on an orphaned sleep left behind by a previous run. The typecheck step itself may still have completed and emitted PASS, so the verdict can be true, but a total time equal to the timeout is a tell that the wrapper did not exit cleanly and that the exit code is suspect.
2. Identical lines between two consecutive reports. If the last 10 lines of .buildcheck/frontend-typecheck.log look exactly like the previous run's last 10 lines — including timestamps that haven't advanced — the file was probably not overwritten.

Correct invocation when the runner is used at all (still subject to the two exceptions in the Core Rule):

LOG=/tmp/buildcheck-$$-fe.log            # $$ is this shell's PID: no collision with other agents
date -u +"start %Y-%m-%dT%H:%M:%SZ"
npm run buildcheck:fe > "$LOG" 2>&1; echo "exit=$?"
date -u +"end   %Y-%m-%dT%H:%M:%SZ"
tail -12 "$LOG"

Read the exit code, not the last line of the log. Capture $? on the line right after the command — any other command in between overwrites it.

Always report:

• The HEAD hash taken in the same shell call as the report — not a hash copied from a previous minute's dump. dev moves under you.
• UTC start and end of the local run.
• An explicit confirmation that the tree was the final state, not an intermediate one.

For anyone orchestrating pushes: run your own buildcheck, then add a HEAD guard immediately before pushing that compares the local git rev-parse HEAD against the SHA you audited. A 2-minute typecheck is enough time for another agent to land a commit on dev.

Memory Budget — 16 GB Dev Machine, 10 Cores

The host does not have 16 GB available for a build. Two consumers share it:

Real host budget with the full dev environment up: ~4 GB. The frontend left Docker on 2026-08-30 precisely because it did not fit: measured with the old layout, vendix_frontend held 5.4 GiB of its 5.5 GiB cgroup (98.2 %) while the host had 903 MB free.

Running natively removed the cgroup, so the frontend no longer dies with CONSTRAINT_MEMCG — but it did not make it cheap. It is still the heaviest process on the machine, and it now competes with builds directly rather than from behind a memory limit.

Consequences that are not negotiable:

When the machine bogs down, npm run buildcheck:top names the culprit with its full command line — consecutive PIDs with identical RSS mean a worker pool, and a pool of cores - 1 is Jest's default, not Angular's (Angular caps lower).

Forbidden verification commands

npm run build, build:prod, and every npm run buildcheck* compile/typecheck command stay reserved for the two exceptions in the Core Rule — never for routine development, never as a self-initiated PR gate. GitHub Actions (ci.yml) already runs the build before merge/release.

Development logs are the only required verification source for development work.

Docker Availability

If Docker is unavailable, Docker Desktop is stopped, or the expected containers do not exist:

1. Report the verification blocker clearly.
2. Do not mark the task as fully verified.
3. Do not start, restart, rebuild, or recreate containers unless that action is necessary for the task or the human approves it.

If a relevant container exists but is stopped unexpectedly, inspect docker ps -a and only restart it when it clearly belongs to the affected Vendix service.

Container Restart/Recreate

Use restart or recreate only for cache, dependency, Dockerfile, compose, or stuck-container issues.

Prefer the compose command used by the repository (docker compose or docker-compose). Examples below use docker compose.

# Restart a service
docker compose restart <service>

# Rebuild one service after dependency or Dockerfile changes
docker compose build --no-cache <service>
docker compose up -d <service>

# Recreate one service safely
docker compose stop <service>
docker compose rm -f <service>
docker compose up -d <service>

# Force recreate all services only when needed
docker compose up -d --force-recreate

After any restart or recreate, re-run the development log checks and docker ps.

Completion Checklist

• Logs checked for all affected development containers with docker logs --tail 40.
• Container status checked with docker ps.
• Dev app status requests include docker compose ps and lightweight HTTP checks when containers are running.
• Zero relevant errors remain in affected logs.
• Fixes were re-verified after changes.
• No tsc, ngc, ng build, npm run build, or npm run buildcheck command was run — unless

the human explicitly asked to test a build, or confirmed a suggested release-prep build.

• If a build/typecheck command was run (one of the two exceptions), no orphan Node process

survived it (npm run buildcheck:reap reports none).

• If Docker was unavailable, the blocker was reported instead of claiming full verification.

Golden Rule

Development means watch-mode output — the npm run dev:fe terminal for the frontend, docker logs for everything else. Nothing else. Never run a build or compile-check unprompted, not even before a PR: CI (ci.yml) already gates the build before merge/release. A build or npm run buildcheck* runs only when the human explicitly asks, or when preparing a release and the human confirms your suggestion to run one.

Related Skills

• vendix-development-rules - General development rules
• vendix-naming-conventions - Naming conventions
• vendix-backend-domain - Backend verification patterns
• vendix-frontend-component - Frontend verification patterns