fix: centralize local script instance targeting

Signed-off-by: zebbern <185730623+zebbern@users.noreply.github.com>

Author: zebbern

AGENTS.md

@@ -99,8 +99,9 @@ Local development runs as **multiple app instances** (PM2) on top of **one share
 - If the user says “use instance N”, prefer either:
   - `just instance use N` then run `just dev` / `bun run test:e2e`, or
   - explicit env override (`SENTRIS_INSTANCE=N just dev ...`) for one-off commands.
-- Backend maintenance scripts that mutate or inspect local Postgres data must use the shared script database resolver (`backend/scripts/lib/script-database-target.ts`) instead of reading `DATABASE_URL` directly. `DATABASE_URL` is for the running backend process, Drizzle CLI, and explicit app env files; local scripts should target `SENTRIS_INSTANCE` / `.sentris-instance` by default and only use script-specific overrides such as `TEMPLATE_SEED_DATABASE_URL` or the generic `SENTRIS_SCRIPT_DATABASE_URL`.
-- Maintenance scripts must print the target database before mutating data.
+- Local maintenance scripts that mutate or inspect local Postgres data must use the shared script runtime (`scripts/lib/local-script-runtime.ts`) instead of reading `DATABASE_URL` directly. `DATABASE_URL` is for the running app process, Drizzle CLI, and explicit app env files; local scripts should target `SENTRIS_INSTANCE` / `.sentris-instance` by default and only use script-specific overrides such as `TEMPLATE_SEED_DATABASE_URL` or the generic `SENTRIS_SCRIPT_DATABASE_URL`.
+- Local scripts that start or inspect Temporal workflows must also use `getScriptTemporalTarget()` from the shared script runtime instead of reading `TEMPORAL_NAMESPACE` / `TEMPORAL_TASK_QUEUE` directly. Use script-specific `*_TEMPORAL_NAMESPACE` + `*_TEMPORAL_TASK_QUEUE` variables or `SENTRIS_SCRIPT_TEMPORAL_NAMESPACE` + `SENTRIS_SCRIPT_TEMPORAL_TASK_QUEUE` when intentionally targeting another namespace.
+- Maintenance scripts must print the target database and/or Temporal target before mutating data or starting workflows.
 
 #### Ports / URLs
 

backend/.env.example

@@ -1,15 +1,15 @@
 # Sentris backend environment defaults
 
 # Primary Postgres database connection
-DATABASE_URL="postgresql://sentris:sentris@localhost:5433/sentris"
+DATABASE_URL="postgresql://sentris:sentris@localhost:5433/sentris_instance_0"
 
 # HTTP server configuration
 PORT="3211"
 
 # Temporal connection details
 TEMPORAL_ADDRESS="localhost:7233"
-TEMPORAL_NAMESPACE="sentris-dev"
-TEMPORAL_TASK_QUEUE="sentris-dev"
+TEMPORAL_NAMESPACE="sentris-dev-0"
+TEMPORAL_TASK_QUEUE="sentris-dev-0"
 
 # MinIO credentials for artifact storage
 MINIO_ROOT_USER="minioadmin"

backend/scripts/__tests__/script-database-target.test.ts

@@ -1,16 +1,19 @@
 import { mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'fs';
 import { tmpdir } from 'os';
-import { dirname, join } from 'path';
+import { dirname, join, resolve } from 'path';
 import { fileURLToPath } from 'url';
 import { afterEach, describe, expect, it } from 'bun:test';
 import {
+  formatTemporalTarget,
   getScriptDatabaseTarget,
+  getScriptTemporalTarget,
   readActiveInstance,
   redactConnectionString,
-} from '../lib/script-database-target';
+} from '../../../scripts/lib/local-script-runtime';
 
 let cleanupDirs: string[] = [];
 const scriptsDir = dirname(dirname(fileURLToPath(import.meta.url)));
+const repoRoot = resolve(scriptsDir, '..', '..');
 
 function createRootWithInstance(instance: string): string {
   const root = mkdtempSync(join(tmpdir(), 'sentris-script-db-target-'));
@@ -97,19 +100,105 @@ describe('script database target resolver', () => {
     ).toBe('postgresql://sentris:***@localhost:5433/sentris_instance_0');
   });
 
+  it('uses the active instance instead of stale Temporal env for local scripts', () => {
+    const target = getScriptTemporalTarget({
+      env: {
+        SENTRIS_INSTANCE: '4',
+        TEMPORAL_NAMESPACE: 'sentris-dev',
+        TEMPORAL_TASK_QUEUE: 'sentris-default',
+      },
+      repoRoot: createRootWithInstance('2'),
+    });
+
+    expect(target.namespace).toBe('sentris-dev-4');
+    expect(target.taskQueue).toBe('sentris-dev-4');
+    expect(target.source).toBe('env:SENTRIS_INSTANCE');
+    expect(target.ignoredTemporalEnv).toBe(true);
+    expect(formatTemporalTarget(target)).toContain(
+      'TEMPORAL_NAMESPACE/TEMPORAL_TASK_QUEUE ignored',
+    );
+  });
+
+  it('allows script-specific Temporal overrides when intentionally targeting another namespace', () => {
+    const target = getScriptTemporalTarget({
+      namespaceOverrideEnvVar: 'WORKFLOW_RUNNER_TEMPORAL_NAMESPACE',
+      taskQueueOverrideEnvVar: 'WORKFLOW_RUNNER_TEMPORAL_TASK_QUEUE',
+      env: {
+        SENTRIS_INSTANCE: '4',
+        SENTRIS_SCRIPT_TEMPORAL_NAMESPACE: 'generic-namespace',
+        SENTRIS_SCRIPT_TEMPORAL_TASK_QUEUE: 'generic-task-queue',
+        WORKFLOW_RUNNER_TEMPORAL_NAMESPACE: 'manual-namespace',
+        WORKFLOW_RUNNER_TEMPORAL_TASK_QUEUE: 'manual-task-queue',
+      },
+      repoRoot: createRootWithInstance('2'),
+    });
+
+    expect(target.namespace).toBe('manual-namespace');
+    expect(target.taskQueue).toBe('manual-task-queue');
+    expect(target.source).toBe(
+      'env:WORKFLOW_RUNNER_TEMPORAL_NAMESPACE/env:WORKFLOW_RUNNER_TEMPORAL_TASK_QUEUE',
+    );
+  });
+
   it('prevents backend maintenance scripts from reading DATABASE_URL directly', () => {
     const scriptFiles = readdirSync(scriptsDir)
       .filter((file) => file.endsWith('.ts'))
       .filter((file) => file !== 'generate-openapi.ts' && file !== 'version-check-summary.ts');
 
     for (const file of scriptFiles) {
       const source = readFileSync(join(scriptsDir, file), 'utf-8');
-      expect(source, `${file} should use script-database-target.ts`).not.toContain(
+      expect(source, `${file} should use local-script-runtime.ts`).not.toContain(
         'process.env.DATABASE_URL',
       );
       expect(source, `${file} should not fall back to the legacy sentris database`).not.toContain(
         'postgresql://sentris:sentris@localhost:5433/sentris',
       );
     }
   });
+
+  it('prevents all local database maintenance scripts from reading DATABASE_URL directly', () => {
+    const databaseScriptFiles = [
+      join(scriptsDir, 'delete-all-workflow-runs.ts'),
+      join(scriptsDir, 'migration-smoke.ts'),
+      join(scriptsDir, 'seed-stress-test.ts'),
+      join(scriptsDir, 'seed-templates.ts'),
+      join(repoRoot, 'worker', 'scripts', 'run-long-lived-workflow.ts'),
+      join(repoRoot, 'worker', 'scripts', 'workflow-execute-inline.ts'),
+      join(repoRoot, 'worker', 'scripts', 'workflow-runner.ts'),
+    ];
+
+    for (const file of databaseScriptFiles) {
+      const source = readFileSync(file, 'utf-8');
+      expect(source, `${file} should use the shared script database resolver`).toContain(
+        'getScriptDatabaseTarget',
+      );
+      expect(source, `${file} should not read DATABASE_URL directly`).not.toContain(
+        'process.env.DATABASE_URL',
+      );
+      expect(source, `${file} should not fall back to the legacy sentris database`).not.toContain(
+        'postgresql://sentris:sentris@localhost:5433/sentris',
+      );
+    }
+  });
+
+  it('prevents local Temporal scripts from reading stale Temporal env directly', () => {
+    const temporalScriptFiles = [
+      join(repoRoot, 'worker', 'scripts', 'benchmark-scheduler.ts'),
+      join(repoRoot, 'worker', 'scripts', 'run-long-lived-workflow.ts'),
+      join(repoRoot, 'worker', 'scripts', 'workflow-runner.ts'),
+    ];
+
+    for (const file of temporalScriptFiles) {
+      const source = readFileSync(file, 'utf-8');
+      expect(source, `${file} should use the shared script Temporal resolver`).toContain(
+        'getScriptTemporalTarget',
+      );
+      expect(source, `${file} should not read TEMPORAL_NAMESPACE directly`).not.toContain(
+        'process.env.TEMPORAL_NAMESPACE',
+      );
+      expect(source, `${file} should not read TEMPORAL_TASK_QUEUE directly`).not.toContain(
+        'process.env.TEMPORAL_TASK_QUEUE',
+      );
+    }
+  });
 });

backend/scripts/delete-all-workflow-runs.ts

@@ -1,5 +1,8 @@
 import { Pool } from 'pg';
-import { formatDatabaseTarget, getScriptDatabaseTarget } from './lib/script-database-target';
+import {
+  formatDatabaseTarget,
+  getScriptDatabaseTarget,
+} from '../../scripts/lib/local-script-runtime';
 
 async function main() {
   const databaseTarget = getScriptDatabaseTarget({

backend/scripts/migration-smoke.ts

@@ -1,7 +1,10 @@
 import { readFileSync, readdirSync } from 'fs';
 import { join, resolve } from 'path';
 import { Pool } from 'pg';
-import { formatDatabaseTarget, getScriptDatabaseTarget } from './lib/script-database-target';
+import {
+  formatDatabaseTarget,
+  getScriptDatabaseTarget,
+} from '../../scripts/lib/local-script-runtime';
 
 async function main() {
   const databaseTarget = getScriptDatabaseTarget({

backend/scripts/seed-stress-test.ts

@@ -2,7 +2,10 @@ import { Pool, PoolClient } from 'pg';
 import { randomUUID } from 'crypto';
 import { SecretEncryption, parseMasterKey } from '@sentris/shared';
 import * as bcrypt from 'bcryptjs';
-import { formatDatabaseTarget, getScriptDatabaseTarget } from './lib/script-database-target';
+import {
+  formatDatabaseTarget,
+  getScriptDatabaseTarget,
+} from '../../scripts/lib/local-script-runtime';
 
 // ─── Configuration ───────────────────────────────────────────────────────────
 

backend/scripts/seed-templates.ts

@@ -14,7 +14,10 @@ import { randomUUID } from 'crypto';
 import { readFileSync, readdirSync } from 'fs';
 import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
-import { formatDatabaseTarget, getScriptDatabaseTarget } from './lib/script-database-target';
+import {
+  formatDatabaseTarget,
+  getScriptDatabaseTarget,
+} from '../../scripts/lib/local-script-runtime';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);

docs/MULTI-INSTANCE-DEV.mdx

@@ -138,17 +138,29 @@ When stopping/cleaning instance 0, Docker infra is also torn down. For non-zero
 
 ## Local Maintenance Scripts
 
-Backend maintenance scripts that mutate or inspect local Postgres data are instance-aware. They resolve their target database in this order:
+Local maintenance scripts use the shared script runtime at `scripts/lib/local-script-runtime.ts`.
+
+Scripts that mutate or inspect local Postgres data are instance-aware. They resolve their target database in this order:
 
 1. Script-specific override, such as `TEMPLATE_SEED_DATABASE_URL`, `DELETE_WORKFLOW_RUNS_DATABASE_URL`, `MIGRATION_SMOKE_DATABASE_URL`, or `SEED_STRESS_DATABASE_URL`
 2. Generic script override: `SENTRIS_SCRIPT_DATABASE_URL`
 3. `SENTRIS_INSTANCE`
 4. `.sentris-instance`
 5. Instance `0`
 
-These scripts intentionally do **not** use plain `DATABASE_URL` by default. `DATABASE_URL` belongs to the running backend process, Drizzle CLI, and app env files; using it for local maintenance scripts can accidentally target the legacy `sentris` database instead of `sentris_instance_N`.
+These scripts intentionally do **not** use plain `DATABASE_URL` by default. `DATABASE_URL` belongs to the running app process, Drizzle CLI, and app env files; using it for local maintenance scripts can accidentally target the legacy `sentris` database instead of `sentris_instance_N`.
+
+Scripts that start or inspect Temporal workflows resolve namespace and task queue in this order:
+
+1. Script-specific override pair, such as `WORKFLOW_RUNNER_TEMPORAL_NAMESPACE` + `WORKFLOW_RUNNER_TEMPORAL_TASK_QUEUE`
+2. Generic override pair: `SENTRIS_SCRIPT_TEMPORAL_NAMESPACE` + `SENTRIS_SCRIPT_TEMPORAL_TASK_QUEUE`
+3. `SENTRIS_INSTANCE`
+4. `.sentris-instance`
+5. Instance `0`
+
+These scripts intentionally do **not** use plain `TEMPORAL_NAMESPACE` / `TEMPORAL_TASK_QUEUE` by default for the same reason: stale app env files can point a script at the wrong local instance.
 
-Every maintenance script should print its target database before mutating data:
+Every maintenance script should print its target database and/or Temporal target before mutating data or starting workflows:
 
 ```bash
 bun --cwd backend scripts/seed-templates.ts
@@ -159,6 +171,9 @@ SENTRIS_INSTANCE=2 bun --cwd backend scripts/seed-templates.ts
 
 TEMPLATE_SEED_DATABASE_URL=postgresql://sentris:sentris@localhost:5433/custom_db bun --cwd backend scripts/seed-templates.ts
 # Target database: custom_db via env:TEMPLATE_SEED_DATABASE_URL
+
+bun --cwd worker scripts/workflow-runner.ts --workflow <workflow-id>
+# Target Temporal: namespace=sentris-dev-0, taskQueue=sentris-dev-0 via default:instance-0
 ```
 
 ## E2E Tests (Instance-Aware)

docs/development/dev-environment.mdx

@@ -231,7 +231,7 @@ Key variables:
 
 | Variable                  | Default                                               | Purpose                            |
 | ------------------------- | ----------------------------------------------------- | ---------------------------------- |
-| `DATABASE_URL`            | `postgresql://sentris:sentris@localhost:5433/sentris` | Postgres connection                |
+| `DATABASE_URL`            | `postgresql://sentris:sentris@localhost:5433/sentris_instance_0` | Postgres connection                |
 | `PORT`                    | `3211`                                                | Backend HTTP port                  |
 | `TEMPORAL_ADDRESS`        | `localhost:7233`                                      | Temporal gRPC endpoint             |
 | `AUTH_PROVIDER`           | `local`                                               | Auth mode (`local` or `clerk`)     |
@@ -245,7 +245,7 @@ Key variables:
 
 | Variable                  | Default                                               | Purpose                       |
 | ------------------------- | ----------------------------------------------------- | ----------------------------- |
-| `DATABASE_URL`            | `postgresql://sentris:sentris@localhost:5433/sentris` | Postgres connection           |
+| `DATABASE_URL`            | `postgresql://sentris:sentris@localhost:5433/sentris_instance_0` | Postgres connection           |
 | `TEMPORAL_ADDRESS`        | `localhost:7233`                                      | Temporal gRPC endpoint        |
 | `MINIO_ENDPOINT`          | `localhost`                                           | MinIO host                    |
 | `SECRET_STORE_MASTER_KEY` | `CHANGE_ME_32_CHAR_SECRET_KEY!!!!`                    | Must match backend            |

scripts/instance-env.sh

@@ -12,7 +12,7 @@ set -euo pipefail
 APPS=(backend worker frontend)
 BASE_BACKEND_PORT=3211
 BASE_FRONTEND_PORT=5173
-BASE_DB_NAME="sentris"
+BASE_DB_NAME="sentris_instance"
 BASE_TEMPORAL_NS="sentris-dev"
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
@@ -48,19 +48,11 @@ get_frontend_port() {
 }
 
 get_db_name() {
-  if [ "$1" -eq 0 ]; then
-    echo "$BASE_DB_NAME"
-  else
-    echo "${BASE_DB_NAME}_instance_$1"
-  fi
+  echo "${BASE_DB_NAME}_$1"
 }
 
 get_temporal_ns() {
-  if [ "$1" -eq 0 ]; then
-    echo "$BASE_TEMPORAL_NS"
-  else
-    echo "${BASE_TEMPORAL_NS}-$1"
-  fi
+  echo "${BASE_TEMPORAL_NS}-$1"
 }
 
 get_db_url() {