Open Mercato Readiness Scanner

Check your app. Ship with confidence.

Scan an Open Mercato application for production and security configuration gaps. Get actionable findings in your terminal, Markdown, and JSON—from your laptop, a Railway container, or a deployment pipeline.

npx @open-mercato/readiness-scanner scan .
npx @open-mercato/readiness-scanner scan . --fail-on high

The scanner checks repository configuration, production .env files, inherited environment variables, and local file permissions. Secret values stay in memory and never appear in reports. Every finding has a stable rule ID, a remediation, and its own guide.

Quick start · Deployment checks · Rule selection · Rules · Framework docs · Discord

Quick start

You need Node.js 24 or newer. Run from an application created with create-mercato-app, or pass its path.

1. Scan your application

cd my-app
npx @open-mercato/readiness-scanner scan .

Starting from a nested directory also works: the scanner locates the parent application using @open-mercato/core and src/modules.ts. You do not need to install or start the application to scan it.

2. Save your report

npx @open-mercato/readiness-scanner scan . \
  --markdown readiness.md \
  --json readiness.json

The terminal groups findings as failed (❌), review (⚠️), passed (✅), and skipped (⏭️). Both files are written while the terminal report stays visible.

For a single output, use --output readiness.json or --output readiness.md; the extension selects the format and file output suppresses stdout. Use --format json --output - for machine-readable stdout.

3. Add a deployment gate

npx @open-mercato/readiness-scanner scan . --fail-on high

This writes the report and exits with code 1 when a failed rule has high or critical severity. Use critical, medium, or low to change the threshold. The default is never. Warnings require operator review and do not fail this threshold.

See the complete GitHub Actions and Railway examples. Run inside the deployed container to inspect its actual environment and mounted storage. In GitHub Actions, explicitly pass the deployment settings through the job's env mapping.

Choose your rules

# Discover rule IDs.
npx @open-mercato/readiness-scanner --list-rules

# Your deployment intentionally uses tracing.
npx @open-mercato/readiness-scanner scan . \
  --ignore runtime-tracing-disabled --fail-on high

# Check only signing secrets and database encryption.
npx @open-mercato/readiness-scanner scan . \
  --only secrets-jwt-signing,data-tenant-encryption-enabled,data-encryption-key-config \
  --fail-on high

--ignore and --only accept comma-separated IDs and can be repeated. Ignore takes precedence when the same ID appears in both. Disabled checks remain in the report as skipped. Unknown IDs return a usage error.

What gets checked

The 36 documented rules cover signing secrets, environment defaults, tenant field encryption and its fallback key, PostgreSQL and Redis credentials, supporting services, private upload permissions, tracing and debug flags, TLS guidance, origins, headers, container users, supply chain, workers, migrations, backups, rollback, and observability.

Environment precedence is: inherited process variables, .env.production.local, .env.local, .env.production, then .env. Sanitized example files are checked as templates and never supply live credentials. Dotenv values are parsed as data; variable references can be expanded, and commands are never executed.

Checks are read-only. The scanner does not start the app, execute its scripts, log in to services, perform network probes, or upload reports. Local configuration cannot prove database authentication, encryption of existing records, provider disk encryption, live TLS, or backup recovery. Permission checks inspect bounded filesystem metadata without opening uploaded files.

Install the CLI

For a persistent global command:

npm install --global @open-mercato/readiness-scanner
mercato-readiness scan . --fail-on high

The published package contains compiled JavaScript and TypeScript declarations and has no runtime dependencies. Its programmatic entry point exports scan, formatters, types, and the rule catalog.

Documentation

| Topic | Guide | |---|---| | Railway, GitHub Actions, environment precedence, and exit codes | Deployment checks | | All rule IDs, severities, and remediation guides | Rule catalog | | JSON report contract, schema version 1 | Report schema | | Contribute, test, and release the CLI | Development |

Development

npm ci
npm run check
npm run test:standalone

All implementation, build helpers, lint configuration, and tests are TypeScript. GitHub CI runs lint/type checks, unit tests, builds, package checks, integration tests, and a fresh standalone-app scan on Node.js 24 and 26. The standalone test scaffolds [email protected], installs the packed CLI into an isolated consumer, and validates its security reports without running application scripts.

Part of Open Mercato. Website · Framework docs · Cloud · Discord

MIT © Open Mercato contributors. See LICENSE.