Skip to content

Root Scripts Reference

This page is the canonical reference for scripts in the repository root scripts/ directory.

  • Scope: root scripts only (scripts/*.mjs and supporting root script modules/data files).
  • Out of scope: app-local scripts under apps/lms/scripts/ and apps/cms/scripts/.
  • Prefer npm run <alias> when an alias exists in the root package.json; use direct node scripts/<file>.mjs only for manual one-off scripts.
  • Local npm run check formats scripts/ with biome check --write (check:root). CI uses read-only biome ci (check:root:ci), matching workspace check vs check:ci.

Scripts Catalogue

Script Name Purpose When to use
scripts/check-i18n.mjs Validates i18n key usage, locale parity, ICU placeholders, and English leftovers for LMS and CMS (npm run check:i18n). Use in CI and local validation; this is part of root npm run check and npm run check:ci.
scripts/check-route-config.mjs Guards Next.js route-segment exports to keep config values statically analyzable (npm run check:route-config). Use in CI and local validation after route config changes; this is part of root npm run check and npm run check:ci.
scripts/audit-zod-deprecations.mjs Flags deprecated Zod v3 APIs (z.string().uuid(), .strict(), .passthrough(), ZodIssueCode, { message } / positional error strings). npm run check:zod-deprecations is --strict. Use in CI and local validation; blocking via root npm run check / npm run check:ci. Report-only: npm run audit:zod-deprecations.
scripts/audit-data-testids.mjs Report-only audit for data-testid coverage across LMS/CMS source (npm run audit:testids). Use when reviewing or improving test-hook coverage; does not block CI.
scripts/audit-import-paths.mjs Report-only audit for deep relative imports that should use aliases (npm run audit:imports). Use when cleaning import paths and enforcing alias conventions; does not block CI.
scripts/audit-filenames.mjs Report-only filename audit against kebab-case/file-convention policy (npm run audit:filenames). Use when checking naming drift; optional --strict can fail on violations.
scripts/audit-implicit-submit-buttons.mjs Report-only audit for JSX <Button> / <button> tags with onClick but no explicit type (npm run audit:submit-buttons). Use to prevent accidental form submissions caused by implicit type="submit" defaults; optional --strict can fail on violations.
scripts/build-integrated.mjs Orchestrates integrated LMS build with a real CMS server (npm run build:integrated). Use when you need full LMS prerender coverage against live CMS responses during build.
scripts/build-lms-with-cms.mjs Builds LMS with environment produced by integrated CMS runtime (invoked by build-integrated.mjs). Internal orchestration step; run directly only for troubleshooting integrated build flow.
scripts/run-cms-build-server.mjs Starts CMS in integrated-build mode, writes shared runtime env (npm run cms:serve). Use inside integrated build workflow or when debugging integrated CMS startup behavior.
scripts/integrated-cms-config.mjs Shared constants for integrated CMS build runtime (INTEGRATED_CMS_PORT, data dir, etc.). Supporting module for integrated-build scripts; not a standalone command.
scripts/vercel-db.mjs Runs app DB migration + system seed during Vercel builds (db:migrate:deploy then db:seed:system). Use in deployment/build environments; both apps call this from their vercel.json build command.
scripts/i18n-apply-overrides.mjs Applies dotted-key locale overrides from scripts/i18n-overrides/*.json into app message files. Use for controlled bulk translation updates when preparing locale patch sets.
scripts/gen-bonsai-images.mjs Regenerates one themed set of CMS seed SVG assets via shared generator. Use only when intentionally updating CMS seed image fixtures.
scripts/gen-project-social-images.mjs Regenerates the five 1200×630 Open Graph images for named CMS demo projects. Use when intentionally updating seeded project social-card fixtures.
scripts/gen-will-images.mjs Regenerates one themed set of CMS seed SVG assets via shared generator. Use only when intentionally updating CMS seed image fixtures.
scripts/migrate-lms-filenames.mjs One-off LMS PascalCase-to-kebab-case component filename migration utility. Historical reference only; do not re-run unless explicitly needed for restore/migration recovery.
scripts/migrate-lms-module-filenames.mjs One-off LMS PascalCase-to-kebab-case module filename migration utility. Historical reference only; do not re-run unless explicitly needed for restore/migration recovery.
scripts/i18n-check-lib.mjs Shared analysis helpers used by i18n scripts (check-i18n, i18n-apply-overrides). Supporting module; not invoked directly in normal workflows.
scripts/lib/gen-seed-image-core.mjs Shared SVG generation core used by seed-image generator scripts. Supporting module; not invoked directly in normal workflows.

Supporting Data Files

  • scripts/i18n-allowlist.json: allowlisted keys/value patterns used by scripts/check-i18n.mjs via scripts/i18n-check-lib.mjs.
  • scripts/i18n-overrides/*.json: override inputs consumed by scripts/i18n-apply-overrides.mjs.

CLI Flags Appendix

scripts/check-i18n.mjs

  • --quiet: reduce output noise (used by root npm run check:i18n).
  • --skip-leftovers: skip English-leftover validation.
  • --report json (or json): emit machine-readable JSON report.
  • Optional positional app scope: apps/lms or apps/cms.

scripts/check-route-config.mjs

  • --json: emit JSON output.

scripts/audit-zod-deprecations.mjs

  • --json: emit JSON report.
  • --strict: fail with non-zero exit when deprecated Zod patterns exist (npm run check:zod-deprecations).

scripts/audit-data-testids.mjs

  • --json: emit JSON report.
  • --write-registry: write/update test ID registry snapshot files.

scripts/audit-import-paths.mjs

  • --json: emit JSON report.

scripts/audit-filenames.mjs

  • --json: emit JSON report.
  • --strict: fail with non-zero exit when violations exist.
  • --cms: include apps/cms/src in scan.

scripts/audit-implicit-submit-buttons.mjs

  • --json: emit JSON report.
  • --strict: fail with non-zero exit when violations exist.