Lantern

Appearance

Scripts Guide ​

Date: 2026-01-217
Status: ✅ Active

Overview of npm scripts and utility scripts for Lantern development, deployment, and maintenance. CustomAll scripts live in scripts/ and are documented here instead of a module-level README.

Quick Reference ​

Most Common Commands ​

CommandDescription
npm run devStart development server
npm run buildProduction build
npm run previewPreview production build locally
npm testRun tests in watch mode
npm run validateFull validation (tests, lint, format, audit)
npm run lint:fixAuto-fix linting issues
npm run formatFormat code with Prettier
npm run storybookStart Storybook dev server

Core Development ​

App Development ​

bash
npm run dev          # Start Vite dev server (auto-generates version.json)
npm run build        # Production build (auto-generates version.json)
npm run build:app    # Same as build, explicit version generation
npm run preview      # Preview production build locally

Admin Portal (Workspace) ​

bash
npm run admin:dev     # Start admin portal dev server
npm run admin:build   # Build admin portal for production
npm run admin:preview # Preview admin portal build

Discord Bot (Workspace) ​

bash
npm start            # Start Discord bot (runs in discord-bot workspace)

Testing ​

Unit & Integration Tests ​

bash
npm test                    # Run Vitest in watch mode
npm run test:coverage       # Run tests with coverage report

Workflow Tests ​

bash
npm run test:workflows              # Run workflow tests in watch mode
npm run test:workflows:run          # Run workflow tests once
npm run test:workflows:real         # Run with real API calls (costs money!)
npm run test:workflows:validate     # Validate triage config consistency
npm run test:workflows:issue-extraction  # Test issue extraction shell script

Note: test:workflows:real requires RUN_REAL_API_TESTS=true and will make actual API calls.

Linting & Formatting ​

Linting ​

bash
npm run lint                  # Run all linters (ESLint + custom)
npm run lint:fix              # Auto-fix ESLint issues
npm run lint:docs             # Lint documentation files
npm run lint:docs:strict      # Strict documentation linting
npm run lint:conventions      # Validate linter naming conventions
npm run lint:console          # Find console.log statements
npm run lint:venue-config     # Validate venue config (with Firestore)
npm run lint:venue-config:static  # Validate venue config (static only)

Formatting ​

bash
npm run format        # Format src/**/*.{js,jsx,css} with Prettier
npm run format:check  # Check formatting without changes

See: Documentation Linter Guide

Validation & Auditing ​

Full Validation ​

bash
npm run validate      # Run ALL checks (tests, lint, format, audit, workspaces)
npm run validate:fix  # Auto-fix lint, format, and conventions

validate runs: headers check → workflow validation → test coverage → format check → lint → audit → workspace validations

Security Auditing ​

bash
npm run audit             # Production-only audit (moderate+ severity)
npm run audit:fix         # Auto-fix audit issues
npm run audit:fix:force   # Force-fix audit issues (may break things)
npm run validate:headers  # Validate security headers configuration

Documentation ​

VitePress Docs ​

bash
npm run docs:dev      # Start docs dev server
npm run docs:build    # Build docs for production
npm run docs:preview  # Preview built docs

Storybook ​

Development ​

bash
npm run storybook                    # Start Storybook on port 6006
npm run storybook:log                # Start with logging to file
npm run storybook:dated-log          # Start with timestamped log file
npm run storybook:debug-log          # Start with debug logging
npm run storybook:interactive-log    # Interactive mode with logging
npm run storybook:interactive-dated-log  # Interactive + timestamped
npm run storybook:tail               # Tail the Storybook log file

Building ​

bash
npm run build-storybook      # Build static Storybook
npm run build-storybook:log  # Build with logging

Logs location: logs/storybook/

Available Scripts ​

Changelog Management ​

consolidate-changelog.mjs ​

Consolidates daily [DEV] changelog entries into production releases with semantic versioning.

Usage:

bash
# Interactive mode (prompts for version)
npm run changelog:consolidate

# Automatic versioning
npm run changelog:consolidate -- --auto

# Preview without modifying files
npm run changelog:consolidate -- --dry-run --auto

# Help
npm run changelog:consolidate -- --help

What it does:

  • Parses all [DEV] - YYYY-MM-DD sections from docs/CHANGELOG.md
  • Groups changes by category (Added, Changed, Fixed, etc.)
  • Removes duplicates
  • Suggests semantic version based on change types
  • Creates consolidated production release section
  • Removes [DEV] sections after consolidation

See: Changelog Workflow

Database & Venue Management ​

backfill-geohash.mjs ​

Backfills geohash data for existing venues in Firestore.

Usage:

bash
npm run backfill:geohash

What it does:

  • Queries all venues from Firestore
  • Calculates geohash for each venue's coordinates
  • Updates venue documents with geohash field
  • Enables geofencing and proximity queries

Manual run (dev Firestore):

bash
# Option 1: Use .env.local (recommended)
# Add to .env.local:
#   GOOGLE_APPLICATION_CREDENTIALS=/path/to/dev-service-account.json
#   GOOGLE_CLOUD_PROJECT=lantern-app-dev
npm run backfill:geohash

# Option 2: Inline environment variables
GOOGLE_APPLICATION_CREDENTIALS=$HOME/repos/secrets/firebase/lantern-app-dev-firebase-adminsdk-fbsvc-6ea86176a1.json \
GOOGLE_CLOUD_PROJECT=lantern-app-dev \
npm run backfill:geohash

Notes:

  • Preferred setup: Add GOOGLE_APPLICATION_CREDENTIALS and GOOGLE_CLOUD_PROJECT to .env.local (both scripts auto-load it).
  • Optional emulator flag: prepend FIRESTORE_EMULATOR_HOST=localhost:8080 to dry-run against the emulator.
  • Safe to rerun; rows with correct geohash are skipped. Only lat, lng, and geohash are updated.
  • Use the production service account only after explicit approval.
  • CLI auth: gcloud auth application-default login then export GOOGLE_CLOUD_PROJECT=lantern-app-dev (firebase login alone is not enough for ADC).
  • If gcloud is not installed: sudo snap install google-cloud-cli --classic (snap requires the --classic flag) or use the service-account JSON path via GOOGLE_APPLICATION_CREDENTIALS instead of CLI auth.

Headless/no-browser auth (servers/WSL):

bash
# Application Default Credentials without launching a browser
gcloud auth application-default login --no-launch-browser || gcloud auth application-default login --no-browser

# Follow the prompt: copy the URL into any browser, complete login,
# paste the verification code back into the terminal when asked.

# Set project for ADC consumers
gcloud config set project lantern-app-dev
export GOOGLE_CLOUD_PROJECT=lantern-app-dev

# If you see a quota project mismatch warning, set the ADC quota project
gcloud auth application-default set-quota-project lantern-app-dev

# Run backfill
npm run backfill:geohash

backfill-venues.mjs ​

Aggregate backfill for venues (geohash, address, closed flag/status, search terms).

Usage:

bash
# Default: geohash + address + heuristic closed flag + searchTerms
npm run backfill:venues

# Dry run (no writes)
npm run backfill:venues -- --dry-run

# Only specific tasks (comma-separated)
npm run backfill:venues -- --only=geohash,address

# Apply closed status when heuristic triggers (otherwise just sets heuristicLikelyClosed=true)
npm run backfill:venues -- --apply-closed

# Respect Nominatim rate limit (default 1000ms)
npm run backfill:venues -- --rate-limit-ms=1000

What it does:

  • Ensures geohash matches lat/lng (same behavior as backfill-geohash)
  • Reverse geocodes missing/placeholder address using Nominatim (1 req/sec)
  • Marks heuristicLikelyClosed when OSM lifecycle tags suggest closure; with --apply-closed, sets status: 'closed'
  • Regenerates searchTerms from osmTags and venue name for better keyword matching

Notes:

  • Preferred setup: Add GOOGLE_APPLICATION_CREDENTIALS and GOOGLE_CLOUD_PROJECT to .env.local (both scripts auto-load it).
  • Nominatim usage follows the 1 request/second policy; adjust with --rate-limit-ms.
  • Safe to rerun; only missing or out-of-date fields are updated.
  • Network timeouts are handled gracefully; venues that fail reverse geocoding are skipped with a warning.

import-venues-osm.mjs ​

Imports venue data from OpenStreetMap (OSM) via Overpass API.

Usage:

bash
npm run import:venues:osm -- --lat=32.7157 --lng=-117.1611 --radius=5000

Options:

  • --lat - Center latitude
  • --lng - Center longitude
  • --radius - Search radius in meters
  • --limit - Max venues to import (default: 100)
  • --dry-run - Preview without writing to Firestore
  • --consolidate - Merge duplicate venues by osmId

What it does:

  • Queries Overpass API for businesses in geographic area
  • Normalizes OSM data to Lantern venue format
  • Deduplicates by osmId
  • Batch writes to Firestore
  • Preserves merchant-customized fields
  • Captures hours, cuisine, accessibility, amenities

See: Venue Import Guide

check-duplicate-venues.mjs ​

Checks for duplicate venues in Firestore.

Usage:

bash
npm run check:venues      # Interactive mode
npm run check:venues:ci   # CI mode (exits with error code if duplicates found)

deduplicate-venues.mjs ​

Removes duplicate venues from Firestore.

Usage:

bash
npm run deduplicate:venues

delete-all-venues.mjs ​

Deletes all venues from Firestore. Use with extreme caution.

Usage:

bash
npm run delete:venues

list-osm-tag-keys.mjs ​

Lists all OSM tag keys used in imported venues.

Usage:

bash
npm run list:osm-tags

lookup-osm-place.mjs ​

Looks up a place in OpenStreetMap by name or coordinates.

Usage:

bash
npm run lookup:osm -- "Coffee Shop Name"
npm run lookup:osm -- --lat=32.7157 --lng=-117.1611

review-closure-reports.mjs ​

Reviews and processes venue closure reports.

Usage:

bash
npm run review:closures

Firebase Emulators ​

bash
npm run emulators:firestore   # Start Firestore emulator only

Use emulators for local testing without affecting dev/prod databases.

Build & Development ​

generate-version.mjs ​

Generates public/version.json with build metadata.

Usage:

bash
node scripts/generate-version.mjs

What it does:

  • Creates version.json with current version, build timestamp, and git commit
  • Auto-runs via predev and prebuild hooks
  • Used by PWA for cache busting and version display

build-all.sh ​

Builds all deployable assets (app, Storybook, docs).

Usage:

bash
./scripts/build-all.sh

What it does:

  • Builds main app (npm run build:app)
  • Builds Storybook (npm run build-storybook)
  • Builds documentation (npm run docs:build)

Admin Portal & Cloudflare Pages ​

Commands for managing the admin portal deployment to Cloudflare Pages.

Create Cloudflare Pages Projects ​

bash
# Create dev project (one-time setup)
npm run admin:pages:create:dev

# Create prod project (one-time setup)
npm run admin:pages:create:prod

Prerequisites:

  • Wrangler CLI authenticated (npx wrangler login)
  • Cloudflare account with Pages access

Deploy Admin Portal ​

bash
# Deploy to preview (creates preview.lantern-admin-dev.pages.dev)
npm run admin:deploy:preview

# Deploy to dev (production URL for dev project)
npm run admin:deploy:dev

# Deploy to prod (requires approval)
npm run admin:deploy:prod

What it does:

  • Builds the admin portal (npm run admin:build)
  • Deploys admin/dist to Cloudflare Pages
  • Preview deploys to preview.lantern-admin-dev.pages.dev (safe for testing)
  • Dev deploys to lantern-admin-dev.pages.dev
  • Prod deploys to lantern-admin-prod.pages.dev

⚠️ Important: Per project NON-NEGOTIABLES, do not run admin:deploy:prod without explicit approval. All production deployments should go through Pull Requests.

See: Admin Portal Setup

Cloudflare Cache Rules ​

bash
# Setup cache rules for dev
npm run cf:setup-cache-rules:dev

# Setup cache rules for prod
npm run cf:setup-cache-rules:prod

What it does:

  • Configures Cloudflare cache rules for static assets
  • Sets appropriate TTLs for different file types
  • Optimizes CDN performance

start-storybook-logs.sh ​

Starts Storybook with logging to file.

Usage:

bash
./scripts/start-storybook-logs.sh

What it does:

  • Starts Storybook dev server
  • Logs output to logs/storybook/storybook.log
  • Useful for debugging component issues

Financial Calculators ​

fund_allocation_calculator.py ​

Python-based financial calculator for Four Pillars fund allocation.

Usage:

bash
python scripts/fund_allocation_calculator.py

What it does:

  • Models budget allocation across Four Pillars
  • Calculates safe space contributions
  • Computes profit sharing distributions
  • Validates allocation percentages

Note: Web-based Vue calculators are available in the docs site: npm run docs:dev

Validation & Audit Scripts ​

audit-production.js ​

Runs security audit on production dependencies only (ignores devDependencies).

Usage:

bash
npm run audit   # Runs with --level=moderate

What it does:

  • Filters audit to production dependencies only
  • Exits with error if moderate+ vulnerabilities found
  • Used in CI/CD validation pipeline

validate-headers.js ​

Validates security headers in public/_headers and public/_redirects.

Usage:

bash
npm run validate:headers

validate-triage-consistency.js ​

Validates AI triage configuration consistency.

Usage:

bash
node scripts/validate-triage-consistency.js

Part of npm run test:workflows:validate.

Cache Management ​

purge-cache.sh ​

Purges Cloudflare cache for the application.

Usage:

bash
./scripts/purge-cache.sh

Note: Requires Cloudflare API credentials configured. Build & Development

build-all.sh ​

Builds all deployable assets (app, Storybook, docs).

Usage:

bash
./scripts/build-all.sh

What it does:

  • Builds main app (npm run build:app)
  • Builds Storybook (npm run build-storybook)
  • Builds documentation (npm run docs:build)

start-storybook-logs.sh ​

Starts Storybook with logging to file.

Usage:

bash
./scripts/start-storybook-logs.sh

What it does:

  • Starts Storybook dev server
  • Logs output to logs/storybook/storybook.log
  • Useful for debugging component issues

Financial Calculators ​

fund_allocation_calculator.py ​

Python-based financial calculator for Four Pillars fund allocation.

Usage:

bash
python scripts/fund_allocation_calculator.py

What it does:

  • Models budget allocation across Four Pillars
  • Calculates safe space contributions
  • Computes profit sharing distributions
  • Validates allocation percentages

Note: Web-based Vue calculators are available in the docs site: npm run docs:dev

Adding New Scripts ​

  1. Naming: Use kebab-case (e.g., my-new-script.mjs).
  2. Executable: Make executable with chmod +x scripts/my-new-script.mjs.
  3. Shebang: Add #!/usr/bin/env node at top for Node scripts.
  4. npm script: Add to package.json scripts section.
  5. Documentation: Update this guide with usage instructions (do not create scripts/README.md).
  6. Help flag: Support --help for usage instructions.

Example Script Template ​

javascript
#!/usr/bin/env node

/**
 * Script Name
 * 
 * Brief description of what the script does.
 * 
 * Usage:
 *   npm run script:name              # Basic usage
 *   npm run script:name -- --option  # With options
 */

import fs from 'fs';
import path from 'path';

function parseArgs() {
  const args = process.argv.slice(2);
  return {
    help: args.includes('--help') || args.includes('-h'),
    dryRun: args.includes('--dry-run')
  };
}

function showHelp() {
  console.log(`
Script Name

Usage:
  npm run script:name              Basic usage
  npm run script:name -- --help    Show help
  npm run script:name -- --dry-run Preview mode
  `);
}

async function main() {
  const args = parseArgs();
  
  if (args.help) {
    showHelp();
    process.exit(0);
  }
  
  // Your script logic here
  console.log('Script running...');
}

main().catch(error => {
  console.error('Error:', error);
  process.exit(1);
});

Troubleshooting ​

Permission Denied ​

bash
chmod +x scripts/your-script.mjs

Node Version ​

All scripts require Node.js 20+. Check version:

bash
node --version

Missing Dependencies ​

Install all dependencies:

bash
npm install
cd discord-bot && npm install

See Also ​

Built with VitePress

Copyright © 2026 Lantern