@monster-orange/den 0.0.0-stage → 0.1.0

package/scripts/setup-secrets.ts

@@ -0,0 +1,149 @@
+/**
+ * Backend-agnostic developer-secrets setup.
+ *
+ * Dispatches to the strategy selected by `secrets.provider` in
+ * config/den.yml (override: DEN_SECRETS_PROVIDER or
+ * config/local/user.yml). See src/shared/secrets.
+ *
+ * Usage:
+ *   make den-setup-secrets                 — interactive setup
+ *   npx tsx scripts/setup-secrets.ts --check    — non-interactive; exit 0 when ready
+ *   npx tsx scripts/setup-secrets.ts --cli      — print "<provider> <binary> <formula>"
+ *   npx tsx scripts/setup-secrets.ts --gate     — like --check, but a backend that
+ *                                                 is not ready only warns unless
+ *                                                 secrets.required is true
+ */
+import { spawnSync } from "child_process";
+import * as path from "path";
+import { fileURLToPath } from "url";
+import chalk from "chalk";
+import {
+  getSecretsProvider,
+  readSecretsConfig,
+} from "../src/shared/secrets/index.js";
+
+import { envKey, product } from "../src/shared/product.js";
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const check = process.argv.includes("--check");
+const gate = process.argv.includes("--gate");
+
+function run(cmd: string, args: string[]): number {
+  return spawnSync(cmd, args, { stdio: "inherit", cwd: ROOT }).status ?? 1;
+}
+
+function installed(cmd: string): boolean {
+  return !spawnSync(cmd, ["--version"], { stdio: "ignore" }).error;
+}
+
+const INSTALL: Record<string, string> = {
+  doppler: "brew install dopplerhq/cli/doppler",
+  op: "brew install 1password-cli",
+};
+
+function otherBackends(current: string): string {
+  return (
+    "Or pick another backend for just you (config/local/user.yml):\n" +
+    "    secrets:\n" +
+    `      provider: env        # or 1password / doppler (team default: ${current})\n` +
+    `  or for one shell: ${envKey("SECRETS_PROVIDER")}=env make web`
+  );
+}
+
+async function main(): Promise<number> {
+  const provider = getSecretsProvider();
+  const cfg = readSecretsConfig();
+  const label = `secrets backend: ${provider.name}`;
+
+  // `--cli`: print "<provider> <binary> <brew formula>" for make setup's
+  // install step ("env -" when the backend needs no CLI).
+  if (process.argv.includes("--cli")) {
+    const bin =
+      provider.name === "doppler"
+        ? "doppler"
+        : provider.name === "1password"
+          ? "op"
+          : "";
+    const formula = bin ? INSTALL[bin].replace(/^brew install /, "") : "";
+    console.log(`${provider.name} ${bin || "-"} ${formula || "-"}`);
+    return 0;
+  }
+
+  if (check || gate) {
+    const r = await provider.preflight();
+    if (r.ok) return 0;
+    if (gate && !cfg.required) {
+      console.error(
+        chalk.yellow(
+          `⚠️  ${label} is not ready — continuing.\n` +
+            "   Test logins and the saved sudo password need it; run " +
+            `\`make ${product().cli}-setup-secrets\` when you want them.`,
+        ),
+      );
+      return 0;
+    }
+    console.error(chalk.red(`✗ ${label}\n${r.message ?? ""}`));
+    return 1;
+  }
+
+  console.log(
+    chalk.bold(`\n${product().title} developer secrets (${label})\n`),
+  );
+  switch (provider.name) {
+    case "doppler": {
+      if (!installed("doppler")) {
+        console.error(
+          chalk.red("✗ The Doppler CLI is not installed.\n") +
+            `  Install it:  ${INSTALL.doppler}\n  then re-run: make ${product().cli}-setup-secrets\n\n  ` +
+            otherBackends(provider.name),
+        );
+        return 1;
+      }
+      if (!(await provider.isReady())) {
+        console.log("→ doppler login");
+        if (run("doppler", ["login"]) !== 0) return 1;
+      }
+      const scope: string[] = [];
+      if (cfg.doppler?.project) scope.push("--project", cfg.doppler.project);
+      if (cfg.doppler?.config) scope.push("--config", cfg.doppler.config);
+      console.log(`→ doppler setup ${scope.join(" ")}`.trim());
+      if (
+        run("doppler", ["setup", "--no-interactive", ...scope]) !== 0 &&
+        scope.length === 0
+      ) {
+        run("doppler", ["setup"]);
+      }
+      break;
+    }
+    case "1password":
+      if (!installed("op")) {
+        console.error(
+          chalk.red("✗ The 1Password CLI (op) is not installed.\n") +
+            `  Install it:  ${INSTALL.op}\n\n  ` +
+            otherBackends(provider.name),
+        );
+        return 1;
+      }
+      return run(path.join(ROOT, "node_modules", ".bin", "tsx"), [
+        path.join(ROOT, "scripts", "setup-1password.ts"),
+      ]);
+    case "env":
+      console.log(
+        "The env backend reads secrets from the process environment.\n" +
+          `Export them yourself (direnv, CI secrets, \`doppler run -- ${product().cli} up\`).`,
+      );
+      break;
+  }
+  const r = await provider.preflight();
+  console.log(
+    r.ok ? chalk.green(`✓ ${label} ready`) : chalk.red(`✗ ${r.message}`),
+  );
+  return r.ok ? 0 : 1;
+}
+
+main().then(
+  (code) => process.exit(code),
+  (err: unknown) => {
+    console.error(err instanceof Error ? err.message : err);
+    process.exit(1);
+  },
+);

package/scripts/view-results.js

@@ -0,0 +1,156 @@
+#!/usr/bin/env node
+/**
+ * View JSONL test results
+ * Shows summary, trends, and flaky tests
+ */
+
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const RESULTS_DIR = path.join(__dirname, "../results");
+
+// Read all JSONL files
+function readResults(pillar, environment, days = 7) {
+  const filename = path.join(RESULTS_DIR, `${pillar}-${environment}.jsonl`);
+
+  if (!fs.existsSync(filename)) {
+    return [];
+  }
+
+  const content = fs.readFileSync(filename, "utf8");
+  const lines = content
+    .trim()
+    .split("\n")
+    .filter((line) => line);
+
+  const cutoffDate = new Date();
+  cutoffDate.setDate(cutoffDate.getDate() - days);
+
+  return lines
+    .map((line) => JSON.parse(line))
+    .filter((result) => new Date(result.timestamp) > cutoffDate);
+}
+
+// Calculate summary stats
+function calculateStats(results) {
+  const total = results.length;
+  const passed = results.filter((r) => r.status === "passed").length;
+  const failed = results.filter((r) => r.status === "failed").length;
+  const skipped = results.filter((r) => r.status === "skipped").length;
+
+  const avgDuration = results.reduce((sum, r) => sum + r.duration, 0) / total;
+
+  return {
+    total,
+    passed,
+    failed,
+    skipped,
+    avgDuration,
+    passRate: ((passed / total) * 100).toFixed(1),
+  };
+}
+
+// Find flaky tests (tests that sometimes pass, sometimes fail)
+function findFlakyTests(results) {
+  const testResults = {};
+
+  results.forEach((result) => {
+    if (!testResults[result.test]) {
+      testResults[result.test] = { passed: 0, failed: 0, total: 0 };
+    }
+    testResults[result.test].total++;
+    if (result.status === "passed") testResults[result.test].passed++;
+    if (result.status === "failed") testResults[result.test].failed++;
+  });
+
+  return Object.entries(testResults)
+    .filter(([test, stats]) => stats.passed > 0 && stats.failed > 0)
+    .map(([test, stats]) => ({
+      test,
+      passRate: ((stats.passed / stats.total) * 100).toFixed(1),
+      runs: stats.total,
+    }))
+    .sort((a, b) => parseFloat(a.passRate) - parseFloat(b.passRate));
+}
+
+// Performance trends
+function getPerformanceTrends(results, testName) {
+  return results
+    .filter((r) => r.test === testName)
+    .slice(-10) // Last 10 runs
+    .map((r) => ({
+      timestamp: new Date(r.timestamp).toLocaleString(),
+      duration: r.duration,
+      status: r.status,
+    }));
+}
+
+// Main
+const command = process.argv[2] || "summary";
+const pillar = process.argv[3] || "synthetic";
+const environment = process.argv[4] || "local";
+
+console.log(`\n📊 Test Results - ${pillar}/${environment}\n`);
+
+const results = readResults(pillar, environment);
+
+if (results.length === 0) {
+  console.log("No results found. Run some tests first!\n");
+  process.exit(0);
+}
+
+if (command === "summary") {
+  const stats = calculateStats(results);
+  console.log(`Total Tests:    ${stats.total}`);
+  console.log(`✅ Passed:      ${stats.passed} (${stats.passRate}%)`);
+  console.log(`❌ Failed:      ${stats.failed}`);
+  console.log(`⏭️  Skipped:     ${stats.skipped}`);
+  console.log(`⏱️  Avg Duration: ${stats.avgDuration.toFixed(0)}ms\n`);
+
+  // Recent failures
+  const recentFailures = results.filter((r) => r.status === "failed").slice(-5);
+  if (recentFailures.length > 0) {
+    console.log("Recent Failures:");
+    recentFailures.forEach((r) => {
+      console.log(`  • ${r.test}`);
+      if (r.error) console.log(`    ${r.error.substring(0, 80)}...`);
+    });
+    console.log();
+  }
+}
+
+if (command === "flaky") {
+  const flaky = findFlakyTests(results);
+  if (flaky.length === 0) {
+    console.log("✅ No flaky tests detected!\n");
+  } else {
+    console.log(`⚠️  Found ${flaky.length} flaky tests:\n`);
+    flaky.forEach(({ test, passRate, runs }) => {
+      console.log(`  ${passRate}% pass rate (${runs} runs)`);
+      console.log(`  ${test}\n`);
+    });
+  }
+}
+
+if (command === "trends") {
+  const testName = process.argv[5];
+  if (!testName) {
+    console.log(
+      "Usage: node view-results.js trends <pillar> <environment> <testName>\n",
+    );
+    process.exit(1);
+  }
+
+  const trends = getPerformanceTrends(results, testName);
+  console.log(`Performance trend for: ${testName}\n`);
+  trends.forEach(({ timestamp, duration, status }) => {
+    const statusIcon = status === "passed" ? "✅" : "❌";
+    console.log(`${statusIcon} ${timestamp}: ${duration}ms`);
+  });
+  console.log();
+}
+
+console.log(`📁 Results file: results/${pillar}-${environment}.jsonl`);
+console.log(`📅 Showing last 7 days\n`);

package/service/install.sh

@@ -0,0 +1,112 @@
+#!/usr/bin/env bash
+# Run the web UI as a long-lived macOS service (a launchd LaunchAgent):
+# started at login, restarted if it exits, not tied to any terminal.
+#
+#   service/install.sh            install (or refresh) and start it
+#   service/install.sh uninstall  stop it and remove the LaunchAgent
+#   service/install.sh status     launchd's view of it
+#   service/install.sh print      write the LaunchAgent plist to stdout only
+#
+# Works from Den's checkout and from a distribution, where it lives in
+# node_modules/@monster-orange/den/service/. The distribution root is
+# DEN_ROOT, else this checkout when it holds den.yml. The agent runs the
+# engine's server with the node found on PATH now, from the distribution
+# root; re-run install after changing node versions.
+#
+#   DEN_SERVICE_LABEL  launchd label (default local.<dist dir name>.web)
+#   DEN_SERVICE_LOGS   log directory (default ~/Library/Logs/<dist dir name>)
+set -euo pipefail
+
+HERE="$(cd "$(dirname "$0")" && pwd)"
+ENGINE="$(cd "$HERE/.." && pwd)"
+if [ -n "${DEN_ROOT:-}" ]; then
+  DIST="$(cd "$DEN_ROOT" && pwd)"
+elif [ -f "$ENGINE/den.yml" ]; then
+  DIST="$ENGINE"
+else
+  echo "✗ set DEN_ROOT to your distribution's root (the directory with den.yml)" >&2
+  exit 1
+fi
+[ -f "$DIST/den.yml" ] || { echo "✗ $DIST has no den.yml" >&2; exit 1; }
+NAME="$(basename "$DIST")"
+LABEL="${DEN_SERVICE_LABEL:-local.$NAME.web}"
+LOGS="${DEN_SERVICE_LOGS:-$HOME/Library/Logs/$NAME}"
+PLIST="$HOME/Library/LaunchAgents/$LABEL.plist"
+DOMAIN="gui/$(id -u)"
+
+# tsx: the nearest node_modules/tsx at or above the engine (hoisted installs).
+find_tsx() {
+  local d="$ENGINE"
+  while :; do
+    if [ -f "$d/node_modules/tsx/package.json" ]; then echo "$d/node_modules/tsx"; return 0; fi
+    [ "$d" = "/" ] && return 1
+    d="$(dirname "$d")"
+  done
+}
+
+write_plist() { # $1 = output file
+  NODE="$(command -v node)" || { echo "✗ node is not on PATH" >&2; exit 1; }
+  TSX="$(find_tsx)" || { echo "✗ tsx not installed: run npm ci in $DIST" >&2; exit 1; }
+  DOCKER_DIR="$(dirname "$(command -v docker || echo /usr/local/bin/docker)")"
+  SVC_PATH="$(dirname "$NODE"):$DOCKER_DIR:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin"
+  python3 -I - "$1" "$LABEL" "$NODE" "$TSX" "$ENGINE" "$DIST" "$SVC_PATH" "$HOME" "$LOGS" <<'PY'
+import plistlib, sys
+out, label, node, tsx, engine, dist, path, home, logs = sys.argv[1:]
+data = {
+    "Label": label,
+    "ProgramArguments": [node, "--import", f"{tsx}/dist/loader.mjs",
+                         f"{engine}/src/ui/server/index.ts", "--silent"],
+    "WorkingDirectory": dist,
+    "EnvironmentVariables": {"PATH": path, "HOME": home,
+                             "DEN_ROOT": dist, "DEN_ENGINE_ROOT": engine},
+    "RunAtLoad": True,
+    "KeepAlive": True,
+    "ThrottleInterval": 10,
+    "ProcessType": "Background",
+    "StandardOutPath": f"{logs}/web.log",
+    "StandardErrorPath": f"{logs}/web.log",
+}
+if out == "-":
+    sys.stdout.buffer.write(plistlib.dumps(data))
+else:
+    with open(out, "wb") as f:
+        plistlib.dump(data, f)
+PY
+}
+
+case "${1:-install}" in
+  install)
+    mkdir -p "$LOGS" "$(dirname "$PLIST")"
+    write_plist "$PLIST.new"
+    plutil -lint "$PLIST.new" >/dev/null
+    launchctl bootout "$DOMAIN/$LABEL" 2>/dev/null || true
+    # bootout returns before launchd has let go of the label; a bootstrap
+    # straight after fails ("Bootstrap failed: 5") and leaves NO service.
+    # Wait for it to go, then retry bootstrap a few times.
+    for _ in $(seq 1 50); do
+      launchctl print "$DOMAIN/$LABEL" >/dev/null 2>&1 || break
+      sleep 0.2
+    done
+    mv "$PLIST.new" "$PLIST"
+    loaded=0
+    for _ in 1 2 3 4 5; do
+      if launchctl bootstrap "$DOMAIN" "$PLIST" 2>/dev/null; then loaded=1; break; fi
+      sleep 1
+    done
+    [ "$loaded" = 1 ] || { echo "✗ launchctl bootstrap failed for $LABEL (plist: $PLIST)" >&2; exit 1; }
+    launchctl kickstart -k "$DOMAIN/$LABEL"
+    echo "✓ $LABEL running (logs: $LOGS/web.log)"
+    ;;
+  uninstall)
+    launchctl bootout "$DOMAIN/$LABEL" 2>/dev/null || true
+    rm -f "$PLIST"
+    echo "✓ $LABEL removed"
+    ;;
+  print)
+    write_plist -
+    ;;
+  status)
+    launchctl print "$DOMAIN/$LABEL" | grep -E '^\s*(state|pid|last exit code|runs)' || echo "$LABEL is not loaded"
+    ;;
+  *) echo "usage: $0 [install|uninstall|status|print]" >&2; exit 2 ;;
+esac

package/src/pillars/api/fixtures/index.ts

@@ -0,0 +1,128 @@
+/**
+ * Custom Playwright Fixtures for Integration (API) Tests
+ *
+ * Auth model: Authorization: Bearer <jwt>
+ * Tokens are minted by the environment's token provider (auth0, cognito,
+ * local-jwt) and cached to disk. See shared/auth/api-token.ts for details.
+ *
+ * Prerequisites:
+ *   - Credentials available: the secrets backend (test_accounts in the org
+ *     config) or CI ENV vars
+ *   - For auth0: the "Password" grant type enabled for the app
+ *   - Social-login accounts cannot be used for API token tests
+ */
+
+import { test as base, request } from "@playwright/test";
+import { envSelector } from "../../../shared/environment/env-selector.js";
+import { getApiToken } from "../../../shared/auth/api-token.js";
+import { openApiValidator } from "./openapi-validator.js";
+import type {
+  Environment,
+  EnvironmentConfig,
+} from "../../../shared/types/index.js";
+import type { APIRequestContext } from "@playwright/test";
+
+type CustomFixtures = {
+  environment: Environment;
+  envConfig: EnvironmentConfig;
+  /** Unauthenticated API context — for testing public endpoints or 401 behavior */
+  apiContext: APIRequestContext;
+  /** Admin JWT bearer token */
+  adminToken: string;
+  /** User JWT bearer token */
+  userToken: string;
+  /** Authenticated API context using admin token (Bearer) */
+  adminContext: APIRequestContext;
+  /** Authenticated API context using user token (Bearer) */
+  userContext: APIRequestContext;
+  /** Alias for adminContext — backward compatibility */
+  authenticatedContext: APIRequestContext;
+  /** Alias for adminToken — backward compatibility */
+  accessToken: string;
+  validator: typeof openApiValidator;
+};
+
+export const test = base.extend<CustomFixtures>({
+  // eslint-disable-next-line no-empty-pattern
+  environment: async ({}, use) => {
+    const env = (process.env.E2E_ENVIRONMENT as Environment) || "local";
+    await use(env);
+  },
+
+  envConfig: async ({ environment }, use) => {
+    const config = await envSelector.loadEnvironment(environment);
+    await use(config);
+  },
+
+  // ── JWT token fixtures ────────────────────────────────────────────────────
+
+  adminToken: async ({ environment }, use) => {
+    const token = await getApiToken("admin", environment);
+    await use(token);
+  },
+
+  userToken: async ({ environment }, use) => {
+    const token = await getApiToken("user", environment);
+    await use(token);
+  },
+
+  // Backward-compat alias
+  accessToken: async ({ adminToken }, use) => {
+    await use(adminToken);
+  },
+
+  // ── Request context fixtures ──────────────────────────────────────────────
+
+  /** Unauthenticated — use for testing 401 responses or public endpoints */
+  apiContext: async ({ envConfig }, use) => {
+    const context = await request.newContext({
+      baseURL: envConfig.baseUrls.api,
+      extraHTTPHeaders: {
+        Accept: "application/json",
+        "Content-Type": "application/json",
+      },
+    });
+    await use(context);
+    await context.dispose();
+  },
+
+  /** Admin-authenticated API context — use for admin-only endpoints */
+  adminContext: async ({ envConfig, adminToken }, use) => {
+    const context = await request.newContext({
+      baseURL: envConfig.baseUrls.api,
+      extraHTTPHeaders: {
+        Accept: "application/json",
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${adminToken}`,
+      },
+    });
+    await use(context);
+    await context.dispose();
+  },
+
+  /** User-authenticated API context — use for user-scoped endpoints */
+  userContext: async ({ envConfig, userToken }, use) => {
+    const context = await request.newContext({
+      baseURL: envConfig.baseUrls.api,
+      extraHTTPHeaders: {
+        Accept: "application/json",
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${userToken}`,
+      },
+    });
+    await use(context);
+    await context.dispose();
+  },
+
+  // Backward-compat alias
+  authenticatedContext: async ({ adminContext }, use) => {
+    await use(adminContext);
+  },
+
+  // eslint-disable-next-line no-empty-pattern
+  validator: async ({}, use) => {
+    await use(openApiValidator);
+  },
+});
+
+export { expect } from "@playwright/test";

package/src/pillars/api/fixtures/openapi-validator.ts

@@ -0,0 +1,111 @@
+/**
+ * OpenAPI Schema Validator
+ * Validates API responses against OpenAPI schemas
+ */
+
+import Ajv from "ajv";
+import addFormats from "ajv-formats";
+import { readFile } from "fs/promises";
+import { resolve } from "path";
+import { enginePath } from "../../../shared/engine.js";
+
+export class OpenAPIValidator {
+  private ajv: Ajv;
+  private schemas: Map<string, unknown> = new Map();
+
+  constructor() {
+    this.ajv = new Ajv({
+      allErrors: true,
+      verbose: true,
+      strict: false,
+    });
+    addFormats(this.ajv);
+  }
+
+  /**
+   * Load OpenAPI spec from file
+   */
+  async loadSpec(specPath: string): Promise<void> {
+    // read-only schema load from Den's own files, so worker cwd is irrelevant
+    const fullPath = resolve(enginePath("src/pillars/api/schemas"), specPath);
+
+    try {
+      const content = await readFile(fullPath, "utf-8");
+      const spec = JSON.parse(content);
+
+      // Extract schemas from OpenAPI spec
+      if (spec.components && spec.components.schemas) {
+        for (const [name, schema] of Object.entries(spec.components.schemas)) {
+          this.schemas.set(name, schema as object);
+          this.ajv.addSchema(schema as object, name);
+        }
+      }
+    } catch (error) {
+      throw new Error(
+        `Failed to load OpenAPI spec from ${specPath}: ${(error as Error).message}`,
+      );
+    }
+  }
+
+  /**
+   * Validate response data against a schema
+   */
+  validate(
+    schemaName: string,
+    data: unknown,
+  ): { valid: boolean; errors: string[] } {
+    const schema = this.schemas.get(schemaName);
+
+    if (!schema) {
+      return {
+        valid: false,
+        errors: [
+          `Schema "${schemaName}" not found. Available schemas: ${Array.from(this.schemas.keys()).join(", ")}`,
+        ],
+      };
+    }
+
+    const valid = this.ajv.validate(schema, data);
+
+    if (!valid && this.ajv.errors) {
+      const errors = this.ajv.errors.map((err) => {
+        const path = err.instancePath || "root";
+        return `${path}: ${err.message}`;
+      });
+
+      return { valid: false, errors };
+    }
+
+    return { valid: true, errors: [] };
+  }
+
+  /**
+   * Validate and throw if invalid
+   */
+  validateOrThrow(schemaName: string, data: unknown): void {
+    const result = this.validate(schemaName, data);
+
+    if (!result.valid) {
+      throw new Error(
+        `Schema validation failed for "${schemaName}":\n${result.errors.join("\n")}`,
+      );
+    }
+  }
+
+  /**
+   * Get list of available schemas
+   */
+  getAvailableSchemas(): string[] {
+    return Array.from(this.schemas.keys());
+  }
+
+  /**
+   * Check if schema exists
+   */
+  hasSchema(schemaName: string): boolean {
+    return this.schemas.has(schemaName);
+  }
+}
+
+// Export singleton instance
+export const openApiValidator = new OpenAPIValidator();