@monster-orange/den 0.0.0-stage → 0.1.0

package/src/shared/auth/token-refresh.ts

@@ -0,0 +1,273 @@
+/**
+ * Token Refresh Utility
+ * Check a saved browser session before running tests, and refresh it by
+ * letting the app's own auth SDK renew it when it has gone stale.
+ *
+ * "Signed in" means: opening `signedInPath` (environment config
+ * `auth.browser.signedInPath`, default "/") ends on the app origin under
+ * that path, rather than at the IdP or a login page.
+ */
+
+import * as fs from "fs/promises";
+import { chromium } from "@playwright/test";
+import type { BrowserLoginConfig } from "../types/index.js";
+
+interface StorageState {
+  cookies: Array<{
+    name: string;
+    value: string;
+    domain: string;
+    path: string;
+    expires: number;
+    httpOnly: boolean;
+    secure: boolean;
+    // Playwright's storageState cookie type requires the literal union.
+    sameSite: "Strict" | "Lax" | "None";
+  }>;
+  origins: Array<{
+    origin: string;
+    localStorage: Array<{
+      name: string;
+      value: string;
+    }>;
+  }>;
+}
+
+/**
+ * Check if auth tokens are expired and refresh if needed
+ */
+export async function refreshAuthIfNeeded(
+  authFilePath: string,
+  baseUrl: string,
+  login: BrowserLoginConfig = {},
+): Promise<boolean> {
+  const signedInPath = normalisePath(login.signedInPath ?? "/");
+  try {
+    // Check if auth file exists
+    const fileExists = await fs
+      .access(authFilePath)
+      .then(() => true)
+      .catch(() => false);
+    if (!fileExists) {
+      console.log(`⚠️  No auth session found at: ${authFilePath}`);
+      return false;
+    }
+
+    // Read storage state
+    const storageStateContent = await fs.readFile(authFilePath, "utf-8");
+    const storageState: StorageState = JSON.parse(storageStateContent);
+
+    // Check if tokens are still valid
+    const isValid = await checkTokenValidity(
+      storageState,
+      baseUrl,
+      signedInPath,
+    );
+
+    if (isValid) {
+      console.log("✓ Auth session is still valid");
+      return true;
+    }
+
+    console.log("⚠️  Auth session expired, attempting to refresh...");
+
+    // Try to refresh using the saved session
+    const refreshed = await attemptRefresh(
+      authFilePath,
+      baseUrl,
+      storageState,
+      signedInPath,
+    );
+
+    if (refreshed) {
+      console.log("✓ Auth session refreshed successfully");
+      return true;
+    } else {
+      console.log(
+        "❌ Could not refresh auth session - manual re-authentication required",
+      );
+      return false;
+    }
+  } catch (error) {
+    console.warn(`Token refresh check failed: ${(error as Error).message}`);
+    return false;
+  }
+}
+
+function normalisePath(p: string): string {
+  return p.startsWith("/") ? p : `/${p}`;
+}
+
+/** True when `href` is on the app origin under `signedInPath`. */
+export function isSignedInUrl(
+  href: string,
+  baseUrl: string,
+  signedInPath: string,
+): boolean {
+  try {
+    const url = new URL(href);
+    if (url.origin !== new URL(baseUrl).origin) return false;
+    const prefix = signedInPath.replace(/\/+$/, "");
+    return (
+      prefix === "" ||
+      url.pathname === prefix ||
+      url.pathname.startsWith(`${prefix}/`)
+    );
+  } catch {
+    return false;
+  }
+}
+
+/** Wait (briefly) for any IdP redirect to land back on the app origin. */
+async function settleOnApp(
+  page: { waitForURL(fn: (url: URL) => boolean, o: object): Promise<void> },
+  baseUrl: string,
+): Promise<void> {
+  const appOrigin = new URL(baseUrl).origin;
+  try {
+    await page.waitForURL((url) => url.origin === appOrigin, {
+      timeout: 5000,
+    });
+  } catch {
+    // Timeout is OK - the check below decides
+  }
+}
+
+/**
+ * Check if the current session is still valid
+ */
+async function checkTokenValidity(
+  storageState: StorageState,
+  baseUrl: string,
+  signedInPath: string,
+): Promise<boolean> {
+  let browser: Awaited<ReturnType<typeof chromium.launch>> | undefined;
+  try {
+    // Launch headless browser with saved state
+    browser = await chromium.launch({ headless: true });
+    const context = await browser.newContext({ storageState });
+    const page = await context.newPage();
+
+    // Try to navigate to a protected route
+    await page.goto(baseUrl.replace(/\/$/, "") + signedInPath, {
+      waitUntil: "domcontentloaded",
+      timeout: 10000,
+    });
+    await settleOnApp(page, baseUrl);
+
+    // Still on the protected route (not redirected to a login) = signed in
+    return isSignedInUrl(page.url(), baseUrl, signedInPath);
+  } catch (error) {
+    const errorMsg = (error as Error).message;
+    // If the app isn't running, we can't validate - assume tokens might be valid
+    if (
+      errorMsg.includes("ERR_NAME_NOT_RESOLVED") ||
+      errorMsg.includes("ERR_CONNECTION_REFUSED")
+    ) {
+      console.log("  ℹ️  Cannot reach app - skipping validation");
+      return true; // Assume valid, let tests fail naturally if they're not
+    }
+    console.warn(`  Token validity check failed: ${errorMsg}`);
+    return false;
+  } finally {
+    // Close on every path — a thrown goto previously leaked the Chromium process.
+    await browser?.close();
+  }
+}
+
+/**
+ * Attempt to refresh the session
+ */
+async function attemptRefresh(
+  authFilePath: string,
+  baseUrl: string,
+  oldStorageState: StorageState,
+  signedInPath: string,
+): Promise<boolean> {
+  let browser: Awaited<ReturnType<typeof chromium.launch>> | undefined;
+  try {
+    // Refresh tokens usually live in HTTP-only cookies we can't touch
+    // directly. The best approach is to:
+    // 1. Load the page with the old session
+    // 2. Let the app's auth SDK handle the refresh automatically
+    // 3. Save the new session
+
+    browser = await chromium.launch({ headless: true });
+    const context = await browser.newContext({ storageState: oldStorageState });
+    const page = await context.newPage();
+
+    // Navigate to the app - its auth SDK might auto-refresh
+    await page.goto(baseUrl, {
+      waitUntil: "networkidle",
+      timeout: 30000,
+    });
+    await settleOnApp(page, baseUrl);
+
+    // Try to access a protected route
+    await page.goto(baseUrl.replace(/\/$/, "") + signedInPath, {
+      waitUntil: "domcontentloaded",
+      timeout: 15000,
+    });
+    await settleOnApp(page, baseUrl);
+
+    // Check if we made it to the protected route
+    const isAuthenticated = isSignedInUrl(page.url(), baseUrl, signedInPath);
+
+    if (isAuthenticated) {
+      // Save the refreshed session
+      await context.storageState({ path: authFilePath });
+      return true;
+    }
+
+    return false;
+  } catch (error) {
+    const errorMsg = (error as Error).message;
+    // If the app isn't running, we can't refresh - but this is OK
+    if (
+      errorMsg.includes("ERR_NAME_NOT_RESOLVED") ||
+      errorMsg.includes("ERR_CONNECTION_REFUSED")
+    ) {
+      console.log("  ℹ️  Cannot reach app - skipping refresh");
+      return true; // Assume OK, let tests handle the connection error
+    }
+    console.warn(`  Token refresh attempt failed: ${errorMsg}`);
+    return false;
+  } finally {
+    // Close on every path — a thrown goto previously leaked the Chromium process.
+    await browser?.close();
+  }
+}
+
+/**
+ * Get token expiry time in seconds (for manual token inspection)
+ */
+function getTokenExpiry(token: string): number | null {
+  try {
+    // JWT tokens are base64 encoded
+    const parts = token.split(".");
+    if (parts.length !== 3) {
+      return null;
+    }
+
+    // Decode payload
+    const payload = JSON.parse(Buffer.from(parts[1], "base64").toString());
+    return payload.exp || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Check if token is expired
+ */
+export function isTokenExpired(token: string): boolean {
+  const expiry = getTokenExpiry(token);
+  if (!expiry) {
+    return true; // Assume expired if we can't parse
+  }
+
+  const now = Math.floor(Date.now() / 1000);
+  const bufferSeconds = 300; // 5 minute buffer
+
+  return now >= expiry - bufferSeconds;
+}

package/src/shared/banner.ts

@@ -0,0 +1,15 @@
+/**
+ * The startup banner for the CLI and web server: the org's `brand.banner`
+ * lines when configured, else the brand name spelled out. No product's art
+ * is built in.
+ */
+import { readBrand } from "./brand.js";
+
+export const DEN_BANNER_LINES: string[] = (() => {
+  const b = readBrand();
+  if (b.banner?.length) return b.banner;
+  return [`  ${b.name.toUpperCase().split("").join(" ")}`];
+})();
+
+export const DEN_SUBTITLE = `  ${readBrand().tagline}`;
+export const DEN_DIVIDER = "  ──────────────────────────────────";

package/src/shared/brand.ts

@@ -0,0 +1,79 @@
+/**
+ * Product identity shown to people: the banner, web page titles and the help
+ * header. Read from the org config's `brand:` block, defaulting to the
+ * profile's name (den.yml). Runtime names (env vars, files, directories) come
+ * from the profile, never from the brand.
+ *
+ *   brand:
+ *     name: Acme Dev                 # shown in titles and the banner
+ *     tagline: Acme local dev and E2E harness
+ *     banner: [ "...", "..." ]       # optional ASCII art lines
+ */
+import * as fs from "fs";
+import * as path from "path";
+import * as yaml from "yaml";
+import { getDistRoot } from "./paths.js";
+import { product } from "./product.js";
+
+export interface BrandConfig {
+  name: string;
+  tagline: string;
+  banner?: string[];
+}
+
+export function defaultBrand(): BrandConfig {
+  return { name: product().title, tagline: "Local dev and E2E harness" };
+}
+
+let cached: BrandConfig | null = null;
+
+export function readBrand(root: string = getDistRoot()): BrandConfig {
+  if (cached) return cached;
+  const fallback = defaultBrand();
+  let raw: Partial<BrandConfig> = {};
+  try {
+    const parsed = yaml.parse(
+      fs.readFileSync(path.join(root, product().configFile), "utf-8"),
+    ) as { brand?: Partial<BrandConfig> } | null;
+    raw = parsed?.brand ?? {};
+  } catch {
+    /* no config — defaults */
+  }
+  cached = {
+    name: raw.name?.trim() || fallback.name,
+    tagline: raw.tagline?.trim() || fallback.tagline,
+    banner: Array.isArray(raw.banner) ? raw.banner.map(String) : undefined,
+  };
+  return cached;
+}
+
+/** The brand name as a slug: "Acme Dev" → "acme-dev". Names the web route. */
+export function brandSlug(brand: BrandConfig = readBrand()): string {
+  const s = brand.name
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9-]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  return s || product().name;
+}
+
+export function resetBrandCache(): void {
+  cached = null;
+}
+
+/** Put the brand name in an HTML page's <title> (pages carry the product title). */
+export function brandHtmlTitle(html: string, brand: BrandConfig): string {
+  const title = product().title;
+  if (brand.name === title) return html;
+  return html.replace(
+    /<title>([^<]*)<\/title>/i,
+    (_m, t: string) =>
+      `<title>${t.split(title).join(escapeHtml(brand.name))}</title>`,
+  );
+}
+
+function escapeHtml(s: string): string {
+  return s.replace(/[&<>"]/g, (c) =>
+    c === "&" ? "&amp;" : c === "<" ? "&lt;" : c === ">" ? "&gt;" : "&quot;",
+  );
+}

package/src/shared/cli-tabs.ts

@@ -0,0 +1,131 @@
+import * as fs from "fs";
+import * as path from "path";
+import { tabExists, type TerminalApp } from "./terminal/tabs.js";
+import { getStateDir } from "./paths.js";
+
+export interface CliTabRecord {
+  address: string;
+  terminalApp: TerminalApp;
+  tabId: string;
+  startedAt: Date;
+  cwd?: string;
+  command?: string;
+}
+
+type CliTabRecordJSON = Omit<CliTabRecord, "startedAt"> & {
+  startedAt: string;
+};
+
+const _tabRegistry = new Map<string, CliTabRecord>();
+let loadedFromPath: string | null = null;
+
+function getTabsFile(): string {
+  return (
+    process.env.DEN_CLI_TABS_FILE ?? path.join(getStateDir(), "cli-tabs.json")
+  );
+}
+
+function toRecord(json: CliTabRecordJSON): CliTabRecord {
+  return {
+    ...json,
+    startedAt: new Date(json.startedAt),
+  };
+}
+
+function readTabsFile(filePath: string): Map<string, CliTabRecord> {
+  const map = new Map<string, CliTabRecord>();
+  try {
+    if (!fs.existsSync(filePath)) return map;
+    const parsed = JSON.parse(fs.readFileSync(filePath, "utf-8")) as
+      | Record<string, CliTabRecordJSON>
+      | CliTabRecordJSON[];
+    const records = Array.isArray(parsed) ? parsed : Object.values(parsed);
+    for (const item of records) {
+      if (!item.address || !item.tabId || !item.terminalApp) continue;
+      map.set(item.address, toRecord(item));
+    }
+  } catch {
+    // Corrupt sidecar: leave the in-memory map empty.
+  }
+  return map;
+}
+
+function writeTabsFile(filePath: string, map: Map<string, CliTabRecord>): void {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const json: Record<string, CliTabRecordJSON> = {};
+  for (const [address, record] of map.entries()) {
+    json[address] = {
+      ...record,
+      startedAt: record.startedAt.toISOString(),
+    };
+  }
+
+  const tmp = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(json, null, 2) + "\n", "utf-8");
+  fs.renameSync(tmp, filePath);
+}
+
+function loadTabs(force = false): void {
+  const filePath = getTabsFile();
+  if (!force && loadedFromPath === filePath) return;
+  _tabRegistry.clear();
+  for (const [address, record] of readTabsFile(filePath).entries()) {
+    _tabRegistry.set(address, record);
+  }
+  loadedFromPath = filePath;
+}
+
+function reloadForMutation(): string {
+  const filePath = getTabsFile();
+  loadTabs(true);
+  return filePath;
+}
+
+export function recordTab(
+  address: string,
+  info: Omit<CliTabRecord, "address" | "startedAt"> &
+    Partial<Pick<CliTabRecord, "startedAt">>,
+): CliTabRecord {
+  const filePath = reloadForMutation();
+  const record: CliTabRecord = {
+    address,
+    ...info,
+    startedAt: info.startedAt ?? new Date(),
+  };
+  _tabRegistry.set(address, record);
+  writeTabsFile(filePath, _tabRegistry);
+  return record;
+}
+
+export function lookupTab(address: string): CliTabRecord | null {
+  loadTabs();
+  return _tabRegistry.get(address) ?? null;
+}
+
+export function forgetTab(address: string): void {
+  const filePath = reloadForMutation();
+  _tabRegistry.delete(address);
+  writeTabsFile(filePath, _tabRegistry);
+}
+
+export function listTabs(): CliTabRecord[] {
+  loadTabs();
+  return Array.from(_tabRegistry.values());
+}
+
+export function cleanupStaleTabs(): void {
+  const filePath = reloadForMutation();
+  let changed = false;
+  for (const [address, record] of _tabRegistry.entries()) {
+    try {
+      if (!tabExists(record.tabId, record.terminalApp)) {
+        _tabRegistry.delete(address);
+        changed = true;
+      }
+    } catch {
+      // Automation may be denied while a tab still exists. Keep the record so a
+      // later `den down` can retry closing it.
+    }
+  }
+  if (changed) writeTabsFile(filePath, _tabRegistry);
+}

package/src/shared/constants.ts

@@ -0,0 +1,128 @@
+/**
+ * Shared constants — single source of truth for values used across modules.
+ *
+ * If a value appears in 2+ files, it belongs here.
+ * If it's specific to one module (e.g. a Playwright config timeout), keep it local.
+ */
+
+import { envKey } from "./product.js";
+// ── 1Password strategy (only used when secrets.provider: 1password) ──────────────────────────────────────────────────────────────
+
+/**
+ * Default 1Password account domain used by every `op` invocation across den.
+ * Kept in sync with the `OP_ACCOUNT ?= …` default in the Makefile. Scripts that
+ * may run outside `make` (setup-1password, auth-configure)
+ * set `process.env.OP_ACCOUNT ||= OP_ACCOUNT_DEFAULT` at entry so op picks up
+ * the right account even when invoked directly via `npx tsx`.
+ */
+export const OP_ACCOUNT_DEFAULT = "example.1password.com";
+
+/**
+ * Default vault for shared test accounts. Deprecated: the vault is org data —
+ * read it with testAccountsVault() (src/shared/auth/test-accounts.ts), which
+ * honours `test_accounts.vault` in the org config and falls back to this.
+ */
+export const OP_TEST_VAULT = "test-accounts";
+
+/** Vault containing per-engineer API keys (1Password's built-in personal vault). */
+export const OP_API_KEYS_VAULT = "Employee";
+
+/** Item within OP_API_KEYS_VAULT holding the developer's API keys. */
+export const OP_DEV_KEYS_ITEM = "Developer API Keys";
+
+/**
+ * Field within OP_DEV_KEYS_ITEM where the user's local admin (sudo) password
+ * is optionally stored. Populated when the user checks "Save to 1Password" on
+ * the den local-dev unlock banner; read on server startup so subsequent
+ * sessions unlock without prompting.
+ */
+export const OP_DEN_SUDO_FIELD = `${envKey("LOCAL_ADMIN_PWD")}`;
+
+// ── Timeouts ─────────────────────────────────────────────────────────────────
+
+/** Health check HTTP/shell ping timeout. */
+export const HEALTH_CHECK_TIMEOUT_MS = 3_000;
+/** Hosted environments (beta, prod) may be scaled to zero; a cold start takes seconds. */
+export const HOSTED_HEALTH_CHECK_TIMEOUT_MS = 10_000;
+
+/** Timeout for spawning short-lived CLI subprocesses (open, sudo, git). */
+export const CLI_SPAWN_TIMEOUT_MS = 5_000;
+
+/** Timeout for `gh api` calls (branch listing, repo search). */
+export const GH_API_TIMEOUT_MS = 15_000;
+
+/** Timeout for 1Password `op` CLI commands.
+ *  Generous so macOS Touch ID biometric prompts have time to land
+ *  (≤10s killed the loadtest seed mid-mint when the prompt took >10s). */
+export const OP_CLI_TIMEOUT_MS = 60_000;
+
+/** Git remote HEAD check timeout (fast operation, low timeout). */
+export const GIT_REMOTE_TIMEOUT_MS = 2_000;
+
+/** Time to wait for a daemon to produce initial output before retrying. */
+export const DAEMON_QUICK_EXIT_MS = 3_000;
+
+/** Delay between daemon log stream retries. */
+export const DAEMON_RETRY_DELAY_MS = 5_000;
+
+/** Lines of immediate context a live log stream starts with (deeper history
+ *  is paged on demand via /api/service/history). */
+export const LIVE_TAIL_LINES = 500;
+
+/** Window of time to show detached process output before closing the stream. */
+export const DETACH_WINDOW_MS = 5_000;
+
+/** Max time to wait for a `depends_on: { wait: true }` dependency to become healthy before starting the dependent. */
+export const READINESS_TIMEOUT_MS = 60_000;
+
+/** Poll interval while waiting for a `wait: true` dependency to become healthy. */
+export const READINESS_INTERVAL_MS = 1_000;
+
+/** Daemon graceful shutdown timeout. */
+export const DAEMON_SHUTDOWN_GRACE_MS = 5_000;
+
+// ── Cache TTLs ───────────────────────────────────────────────────────────────
+
+/** TTL for cached GitHub branch listings. */
+export const BRANCH_CACHE_TTL_MS = 60_000;
+
+/** TTL for cached GitHub repo/org listings. */
+export const REPO_CACHE_TTL_MS = 5 * 60_000;
+
+// ── Log rotation ─────────────────────────────────────────────────────────────
+
+/**
+ * Size at which a service log is rotated. Service logs are written by DETACHED
+ * children holding an inherited O_APPEND fd, so a chatty one grows without
+ * bound — a localstack tail was measured at 8.6 GB.
+ */
+export const MAX_LOG_BYTES = 128 * 1024 * 1024;
+
+/** How much of the tail is preserved into `<name>.log.1` when rotating. */
+export const ROTATED_KEEP_BYTES = 32 * 1024 * 1024;
+
+/** How often the server sweeps the log tree for oversized files. */
+export const LOG_SWEEP_INTERVAL_MS = 15 * 60_000;
+
+// ── Test file patterns ───────────────────────────────────────────────────────
+
+/** File extension patterns per test pillar. */
+export const TEST_FILE_EXTENSIONS: Record<string, string[]> = {
+  smoke: [".smoke.ts"],
+  synthetic: [".spec.ts", ".test.ts"],
+  integration: [".spec.ts", ".test.ts"],
+  performance: [".js"],
+};
+
+/** Directories to skip when scanning for test modules. */
+export const SKIP_TEST_DIRS = [
+  "user-flows",
+  "helpers",
+  "fixtures",
+  "utils",
+] as const;
+
+// ── Server ───────────────────────────────────────────────────────────────────
+
+/** Default den web server port. */
+export const DEFAULT_PORT = 7777;