@hstm-labs/forge-run

Post-deliver stage that updates root package.json scripts and optionally runs the dev stack for verification.

Purpose

• Script updates: Add or fill in infra:up, db:create, db:seed, build, start, and run:all so the delivered project has a consistent dev workflow.
• Optional execute: When config.runVerify.execute is true, run the script sequence and HTTP health checks (for CI or local smoke tests).

Auth mode (Keycloak vs local users)

Run-verify supports two auth modes so dev deployment matches how the application authenticates users:

• authMode: 'oidc' — Application uses an IdP (OIDC/OAuth) and has a local user table that caches IdP data plus app-specific values. For dev, we include Keycloak (or another IdP) in the deployment and seed it with users that match the users seeded in the database. Use this when the app relies on IdP for authentication and you want to test the full flow (Keycloak + DB users aligned).
• authMode: 'local' (or unset) — Application only supports authentication with application-owned users (local users table, no IdP). Keycloak is not included in the dev deployment. Use this when there is no IdP and users exist only in the app DB.

Set in forge.config.json:

{
  "runVerify": {
    "execute": true,
    "authMode": "oidc"
  }
}

When authMode is 'oidc', the stage adds scripts keycloak:up and keycloak:seed and uses a run:all order: infra up → keycloak seed → db create → db seed → build → start. The Keycloak seed step should align users with those from db:seed (same identities/attributes). When authMode is 'local' or omitted, no Keycloak scripts are added.

Config

| Option | Type | Description | |--------|------|-------------| | runVerify.execute | boolean | If true, run script sequence and health checks after updating scripts. | | runVerify.healthUrls | string[] | URLs to GET for health checks (default: localhost:3000/health). | | runVerify.authMode | 'oidc' | 'local' | IdP + Keycloak in dev vs local users only; see above. |

Public API

• RunVerifyStage — Pipeline stage (depends on deliver).
• updatePackageJsonScripts(rootDir, layoutName, authMode?) — Add default scripts to root package.json.
• getDefaultScriptsForLayout(layoutName, authMode?) — Get script map for a layout and optional auth mode.
• runScript, runScriptSequence, healthCheck, healthCheckWithRetry — Execution helpers.
• Types: RunVerifyReport, ScriptRunResult, HealthCheckResult, RunVerifyAuthMode.