Skip to content

SCRIPTS.md

Latest commit

 

History

History
89 lines (57 loc) · 4.61 KB

SCRIPTS.md

File metadata and controls

89 lines (57 loc) · 4.61 KB
Raw

Scripts

What Lives Here

This folder contains Node.js scripts that run outside the browser — validation and setup tools. These are CLI tools you run with npm run <script>.

Script Command What it does
validate-config.ts npm run validate Validates config/*.json files against Zod schemas
check-env.ts npm run check-env Validates required environment variables are set before dev server starts
init.ts npm run init Copies a reference PAL into your Tavus account and writes its persona_id into config/presets.config.json

Setup

Setup is manual. Copy .env.example to .env and fill in TAVUS_API_KEY. Set persona_id / replica_id in config/presets.config.json — the single source of truth. Then run npm run dev.

PALs are managed on Tavus directly. The PAL (system prompt, objectives, guardrails, layers) is created and edited via the Tavus dashboard or the Tavus API — the deployed PAL is the source of truth. Point presets[0].persona_id at it. There is no local PAL-deployment script.

validate-config.ts — Config Validation

Validates config/*.json files against Zod schemas.

What it does

  1. Reads each config file (presets.config.json, branding.config.json)
  2. Strips _ prefixed keys
  3. Parses against the Zod schema defined in src/lib/config/schema.ts
  4. Reports success or failure with error details
  5. Exits with code 1 on failure (blocks npm run dev from starting)

What it catches

Schema validation (per-file):

  • Missing required fields (e.g., persona_id field missing from preset)
  • Wrong types (string where number expected, etc.)
  • Empty arrays where at least one entry is required
  • Structural mismatches (e.g., a feature chip missing the desc field)

What it does NOT catch

This validator does not cross-validate objective_name values against config entries, because the medical intake app fetches objectives dynamically from the Tavus API at runtime. There is no static objective-to-label mapping in config that could go stale. The dynamic fetch means no manual sync is required.

When to modify

  • You've added new fields to a config file — update the Zod schema in src/lib/config/schema.ts and the TypeScript types in src/types/
  • You want to add cross-file checks (e.g., verify that persona_id in presets.config.json is non-empty before allowing npm run dev)

check-env.ts — Environment Health Check

Validates that required environment variables are set before the dev server starts. Runs automatically as part of npm run dev.

What it checks

Variable Required Notes
TAVUS_API_KEY Yes Must be set — copy .env.example to .env and paste in your key from maker.tavus.io/dev/api-keys

persona_id and replica_id are not env vars — they live in config/presets.config.json (presets[0]), the single source of truth. check-env does not check them; pick an existing PAL at maker.tavus.io/dev/pals and paste its ID in.

All Tavus API calls go to production (https://tavusapi.com) — the base URL is hardcoded in api/_lib/handlers/tavus.ts, not an env var.

When to modify

  • You've added new required environment variables (e.g., a HIPAA-compliant logging endpoint)
  • You want to add a connectivity check (e.g., ping the Tavus API on startup)

init.ts — Reference PAL Setup

Copies a reference PAL into your Tavus account and writes the new persona_id into config/presets.config.json (under presets[0]). Run it once after setting TAVUS_API_KEY in .env, unless the preset already points at a custom PAL.

How Scripts Connect to Other Parts

  • config/*.json — validate-config.ts validates these. Both must be valid for npm run dev to start.
  • src/lib/config/schema.ts — Zod schemas shared between the validation script and the runtime config loader
  • config/presets.config.json — holds presets[0].persona_id / replica_id, pointing at a PAL in your Tavus account

Adding a New Script

  1. Create the script in scripts/
  2. Add an entry to package.json under scripts: 
    "your-script": "tsx scripts/your-script.ts"
  3. The script can import from src/ (like Zod schemas) — the tsx runner handles TypeScript

Common Patterns

  • Tavus API calls: Use x-api-key header, not Bearer token. Base URL is https://tavusapi.com.
  • Stripping comments: Scripts that read config JSON use the stripComments helper to remove _ prefixed keys before parsing.