@monster-orange/den 0.0.0-stage → 0.1.0

package/src/shared/manifest/validate-manifest.ts

@@ -0,0 +1,140 @@
+/**
+ * .den.yml manifest validator.
+ *
+ * Accepts a parsed object or a raw YAML string.
+ * Returns a ValidationResult describing any errors or warnings.
+ */
+
+import * as yaml from "yaml";
+import { z } from "zod";
+import {
+  CURRENT_SCHEMA_VERSION,
+  KNOWN_VERSIONS,
+  schemaByVersion,
+} from "./schema.js";
+import type { ValidationError, ValidationResult } from "../types/index.js";
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+/** Convert a Zod issue path to a dot-separated string. */
+function zodPathToString(path: (string | number)[]): string {
+  return path
+    .map((p, i) => (typeof p === "number" ? `[${p}]` : i === 0 ? p : `.${p}`))
+    .join("");
+}
+
+/** Friendly message for common Zod issue codes. */
+function zodIssueMessage(issue: z.ZodIssue): string {
+  switch (issue.code) {
+    case z.ZodIssueCode.invalid_type:
+      if (issue.received === "undefined")
+        return `"${issue.path.at(-1)}" is required`;
+      return `expected ${issue.expected}, received ${issue.received}`;
+    case z.ZodIssueCode.invalid_enum_value:
+      return `invalid value "${issue.received}" — must be one of: ${issue.options.join(", ")}`;
+    case z.ZodIssueCode.invalid_union:
+      return "value does not match any valid shape";
+    default:
+      return issue.message;
+  }
+}
+
+/** Suggestion text for specific paths / issues. */
+function suggestionFor(issue: z.ZodIssue): string | undefined {
+  const pathStr = zodPathToString(issue.path);
+
+  // auth arrays in smoke / synthetics
+  if (pathStr.includes("auth")) {
+    return 'Valid roles are: "admin", "user", "beta"';
+  }
+
+  // health with missing url/cmd
+  if (pathStr.includes("health")) {
+    return 'HTTP checks need "url"; shell checks need "type: shell" and "cmd"';
+  }
+
+  return undefined;
+}
+
+// ── Main export ───────────────────────────────────────────────────────────────
+
+/**
+ * Validate a .den.yml manifest.
+ *
+ * @param input - A parsed object or a raw YAML string.
+ * @returns A ValidationResult with errors, warnings, and the detected version.
+ */
+export function validateManifest(input: unknown): ValidationResult {
+  // 1. Parse YAML string if needed
+  let parsed: unknown = input;
+  if (typeof input === "string") {
+    try {
+      parsed = yaml.parse(input);
+    } catch (err: unknown) {
+      return {
+        valid: false,
+        version: 1,
+        errors: [
+          {
+            path: "",
+            message: `Could not parse YAML: ${(err as Error).message}`,
+          },
+        ],
+        warnings: [],
+      };
+    }
+  }
+
+  // 2. Detect version
+  const rawVersion =
+    parsed !== null &&
+    typeof parsed === "object" &&
+    "version" in (parsed as object)
+      ? (parsed as Record<string, unknown>).version
+      : undefined;
+
+  const detectedVersion = rawVersion === undefined ? 1 : Number(rawVersion);
+
+  const warnings: ValidationError[] = [];
+
+  // 3. Warn on unknown future versions but still validate with the latest schema
+  const isKnown = KNOWN_VERSIONS.includes(
+    detectedVersion as (typeof KNOWN_VERSIONS)[number],
+  );
+  if (rawVersion !== undefined && !isKnown) {
+    warnings.push({
+      path: "version",
+      message: `Unknown schema version ${detectedVersion}. Validating against v${CURRENT_SCHEMA_VERSION} (latest known).`,
+    });
+  }
+
+  // 4. Pick schema — fall back to latest for unknown future versions
+  const schema =
+    schemaByVersion[detectedVersion] ?? schemaByVersion[CURRENT_SCHEMA_VERSION];
+
+  // 5. Run Zod validation
+  const result = schema.safeParse(parsed);
+
+  if (result.success) {
+    return {
+      valid: true,
+      version: detectedVersion,
+      errors: [],
+      warnings,
+    };
+  }
+
+  // 6. Map Zod issues → ValidationError[]
+  const errors: ValidationError[] = result.error.issues.map((issue) => ({
+    path: zodPathToString(issue.path),
+    message: zodIssueMessage(issue),
+    suggestion: suggestionFor(issue),
+  }));
+
+  return {
+    valid: false,
+    version: detectedVersion,
+    errors,
+    warnings,
+  };
+}

package/src/shared/manifest/workspace-manifests.ts

@@ -0,0 +1,92 @@
+/**
+ * Every service of the active workspaces, with its repo's manifest: the one
+ * list the security scan, the repo suites and the release check walk.
+ *
+ * Mirrors the server's health walk: the focused workspace first, then the
+ * other active ones; an address listed twice keeps its first owner.
+ */
+
+import { readCatalog } from "../environment-manager/catalog.js";
+import {
+  getActiveWorkspaces,
+  getFocusedWorkspaceName,
+  getWorkspaceByName,
+  listWorkspaceServices,
+  readManifestAnyBranch,
+} from "../environment-manager/workspaces.js";
+import type {
+  RawManifest,
+  ServiceCatalog,
+  ServiceManagementConfig,
+} from "../types/index.js";
+import { orgOf } from "./service-links.js";
+
+export interface WorkspaceService {
+  address: string;
+  repo: string;
+  service: string;
+  repoPath: string;
+  org: string;
+  manifest: RawManifest;
+  config: ServiceManagementConfig | undefined;
+  isEntrypoint: boolean;
+}
+
+export function workspaceNames(workspaceName?: string | null): string[] {
+  if (workspaceName)
+    return getWorkspaceByName(workspaceName) ? [workspaceName] : [];
+  const focus = getFocusedWorkspaceName();
+  return [
+    ...(focus ? [focus] : []),
+    ...getActiveWorkspaces().filter((n) => n !== focus),
+  ];
+}
+
+export function listServicesWithManifests(
+  workspaceName?: string | null,
+  catalog: ServiceCatalog = readCatalog(),
+): WorkspaceService[] {
+  const seen = new Set<string>();
+  const out: WorkspaceService[] = [];
+  for (const name of workspaceNames(workspaceName)) {
+    const ws = getWorkspaceByName(name);
+    if (!ws) continue;
+    for (const svc of listWorkspaceServices(ws.config, catalog, name)) {
+      if (seen.has(svc.address)) continue;
+      seen.add(svc.address);
+      const manifest = readManifestAnyBranch(svc.repoName, svc.repoPath);
+      if (!manifest) continue;
+      out.push({
+        address: svc.address,
+        repo: svc.repoName,
+        service: svc.subsystem,
+        repoPath: svc.repoPath,
+        org: orgOf(svc.repoName, catalog),
+        manifest,
+        config: manifest.services?.[svc.subsystem],
+        isEntrypoint: manifest.entrypoint === svc.subsystem,
+      });
+    }
+  }
+  return out;
+}
+
+/** One entry per repo (its first service carries the manifest). */
+export function listReposWithManifests(
+  workspaceName?: string | null,
+  catalog: ServiceCatalog = readCatalog(),
+): Array<Pick<WorkspaceService, "repo" | "repoPath" | "org" | "manifest">> {
+  const byRepo = new Map<
+    string,
+    Pick<WorkspaceService, "repo" | "repoPath" | "org" | "manifest">
+  >();
+  for (const s of listServicesWithManifests(workspaceName, catalog))
+    if (!byRepo.has(s.repo))
+      byRepo.set(s.repo, {
+        repo: s.repo,
+        repoPath: s.repoPath,
+        org: s.org,
+        manifest: s.manifest,
+      });
+  return [...byRepo.values()];
+}

package/src/shared/open-url.ts

@@ -0,0 +1,122 @@
+/**
+ * Where a service's app opens in a browser, per environment, for the UI's
+ * open-in-new-tab links. Health URLs point at /healthz and friends, never the
+ * app, so they only ever contribute their origin.
+ *
+ * Order, first answer wins:
+ *   1. manifest `services.<svc>.urls.<env>`
+ *   2. local only: the edge route for the service's compose container,
+ *      `https://<route>.<stack>.<edge domain>`; the stack-wide service (the
+ *      entrypoint, or one named after the stack) takes the `app` route, else
+ *      the first route
+ *   3. the origin of the env's HTTP health URL
+ * Only http(s) URLs are returned.
+ */
+import { manifestStackName } from "./stacks/config.js";
+import { parseTarget } from "./stacks/render.js";
+import type { RawManifest as DenManifest } from "./types/index.js";
+
+export interface OpenLink {
+  label: string;
+  url: string;
+}
+
+/** The URL if it is absolute http(s), else null. */
+export function httpUrl(raw: unknown): string | null {
+  if (typeof raw !== "string" || !raw) return null;
+  try {
+    const u = new URL(raw);
+    return u.protocol === "http:" || u.protocol === "https:" ? u.href : null;
+  } catch {
+    return null;
+  }
+}
+
+function edgeRouteUrl(
+  manifest: DenManifest,
+  subsystem: string,
+  repoName: string,
+  edgeDomain: string,
+): string | null {
+  const routes = manifest.compose?.routes;
+  if (!routes || !Object.keys(routes).length) return null;
+  const stack = manifestStackName(manifest, repoName);
+  const names = Object.keys(routes).sort();
+  let route = names.find((r) => {
+    try {
+      return parseTarget(routes[r]).service === subsystem;
+    } catch {
+      return false;
+    }
+  });
+  if (!route && (manifest.entrypoint === subsystem || subsystem === stack))
+    route = routes.app ? "app" : names[0];
+  return route ? `https://${route}.${stack}.${edgeDomain}/` : null;
+}
+
+export function openUrlFor(opts: {
+  manifest: DenManifest;
+  subsystem: string;
+  repoName: string;
+  env: string;
+  /** The env's HTTP health URL, when the check is HTTP. */
+  healthUrl?: string | null;
+  /** Primary edge domain; local edge routes are skipped without it. */
+  edgeDomain?: string | null;
+}): string | null {
+  const svc = opts.manifest.services?.[opts.subsystem];
+  const declared = httpUrl(
+    (svc?.urls as Record<string, string> | undefined)?.[opts.env],
+  );
+  if (declared) return declared;
+  if (opts.env === "local" && opts.edgeDomain) {
+    const routed = edgeRouteUrl(
+      opts.manifest,
+      opts.subsystem,
+      opts.repoName,
+      opts.edgeDomain,
+    );
+    if (routed) return routed;
+  }
+  const health = httpUrl(opts.healthUrl);
+  return health ? `${new URL(health).origin}/` : null;
+}
+
+/** Extra named links (`services.<svc>.links`) that have a URL for the env. */
+export function linksFor(
+  manifest: DenManifest,
+  subsystem: string,
+  env: string,
+): OpenLink[] {
+  const out: OpenLink[] = [];
+  for (const l of manifest.services?.[subsystem]?.links ?? []) {
+    const url = httpUrl((l?.urls as Record<string, string> | undefined)?.[env]);
+    if (url && typeof l.label === "string") out.push({ label: l.label, url });
+  }
+  return out;
+}
+
+/**
+ * Swap the primary edge domain for the alias the viewer is on (e.g. the UI was
+ * opened as den.<alias> from another machine), so links resolve there too.
+ */
+export function rehost(
+  url: string,
+  primary: string,
+  host: string | undefined,
+  aliases: string[],
+): string {
+  const h = (host ?? "").split(":")[0].toLowerCase();
+  const alias = aliases.find((a) => h === a || h.endsWith(`.${a}`));
+  if (!alias) return url;
+  try {
+    const u = new URL(url);
+    if (u.hostname === primary || u.hostname.endsWith(`.${primary}`)) {
+      u.hostname = u.hostname.slice(0, -primary.length) + alias;
+      return u.href;
+    }
+  } catch {
+    /* not a URL: leave it */
+  }
+  return url;
+}

package/src/shared/org.ts

@@ -0,0 +1,44 @@
+/**
+ * The org this den instance serves: the root of
+ * Org > Application > Repo > Services. One instance = one org.
+ *
+ *   org:
+ *     id: globex      # defaults to edge.org
+ *     title: Globex   # defaults to the id
+ */
+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 OrgConfig {
+  id?: string;
+  title?: string;
+}
+
+export interface Org {
+  id: string;
+  title: string;
+}
+
+/** Pure: the org from a parsed config/den.yml, or undefined if unnamed. */
+export function resolveOrg(
+  parsed: { org?: OrgConfig; edge?: { org?: string } } | null | undefined,
+): Org | undefined {
+  const id = parsed?.org?.id?.trim() || parsed?.edge?.org?.trim();
+  if (!id) return undefined;
+  return { id, title: parsed?.org?.title?.trim() || id };
+}
+
+export function readOrg(root: string = getDistRoot()): Org | undefined {
+  try {
+    return resolveOrg(
+      yaml.parse(
+        fs.readFileSync(path.join(root, product().configFile), "utf-8"),
+      ),
+    );
+  } catch {
+    return undefined;
+  }
+}

package/src/shared/paths.ts

@@ -0,0 +1,178 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import {
+  loadProfile,
+  PROFILE_FILE,
+  readEnv,
+  type ProductProfile,
+} from "./profile.js";
+
+/** Den's package name: the engine root is the directory that has it. */
+export const ENGINE_PACKAGE = "@monster-orange/den";
+
+/** A distribution root is a directory holding den.yml. */
+function isDistRootAt(dir: string): boolean {
+  return fs.existsSync(path.join(dir, PROFILE_FILE));
+}
+
+function isEngineRootAt(dir: string): boolean {
+  try {
+    const raw = fs.readFileSync(path.join(dir, "package.json"), "utf-8");
+    return (JSON.parse(raw) as { name?: unknown }).name === ENGINE_PACKAGE;
+  } catch {
+    return false;
+  }
+}
+
+function walkUp(start: string, test: (dir: string) => boolean): string | null {
+  let dir = path.resolve(start);
+  for (;;) {
+    if (test(dir)) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+const entryDir = (): string | null =>
+  process.argv[1] ? path.dirname(path.resolve(process.argv[1])) : null;
+
+/**
+ * An explicit root from the environment: DEN_ROOT, or `<PREFIX>_ROOT` where
+ * <PREFIX> is the env prefix of the profile found there (ACME_ROOT for a
+ * product named acme). Validated rather than trusted: everything downstream (clone
+ * destinations, the clone-guard allowlist, config writes) anchors here, so a
+ * stale or mistyped value must not re-open the Jun 29 incident.
+ */
+function rootFromEnv(): string | null {
+  const den = process.env.DEN_ROOT?.trim();
+  if (den) {
+    const resolved = path.resolve(den);
+    if (!isDistRootAt(resolved))
+      throw new Error(
+        `DEN_ROOT is set to "${den}" but that directory has no ${PROFILE_FILE}. ` +
+          `Point it at your distribution's checkout, or unset it.`,
+      );
+    return resolved;
+  }
+  for (const [key, value] of Object.entries(process.env)) {
+    if (!/^[A-Z][A-Z0-9_]*_ROOT$/.test(key) || !value?.trim()) continue;
+    const resolved = path.resolve(value.trim());
+    if (
+      isDistRootAt(resolved) &&
+      `${loadProfile(resolved).envPrefix}_ROOT` === key
+    )
+      return resolved;
+  }
+  return null;
+}
+
+/**
+ * The distribution root: where den.yml, config/, manifests/, reports/ and
+ * results/ live. Never process.cwd(): on Jun 29 a cwd-derived root caused a
+ * bulk clone of 13 repos into an unrelated checkout. Anything the walk can't
+ * anchor fails loudly.
+ */
+export function getDistRoot(): string {
+  const fromEnv = rootFromEnv();
+  if (fromEnv) return fromEnv;
+  const start = entryDir();
+  const root = start ? walkUp(start, isDistRootAt) : null;
+  if (root !== null) {
+    // The distribution's own <PREFIX>_ROOT, if set, must have been accepted
+    // above: one that points elsewhere is a mistake, never silently ignored.
+    const key = `${loadProfile(root).envPrefix}_ROOT`;
+    const set = process.env[key]?.trim();
+    if (set)
+      throw new Error(
+        `${key} is set to "${set}" but that directory has no ${PROFILE_FILE} ` +
+          `for this product. Point ${key} at your checkout, or unset it.`,
+      );
+    return root;
+  }
+  // Name any product root variable that was set but pointed nowhere useful.
+  for (const [key, value] of Object.entries(process.env))
+    if (/^[A-Z][A-Z0-9_]*_ROOT$/.test(key) && value?.trim()) {
+      const resolved = path.resolve(value.trim());
+      if (
+        fs.existsSync(resolved) &&
+        !isDistRootAt(resolved) &&
+        isProductRootVar(resolved, key)
+      )
+        throw new Error(
+          `${key} is set to "${value}" but that directory has no ${PROFILE_FILE}. ` +
+            `Point ${key} at your checkout, or unset it.`,
+        );
+    }
+  throw new Error(
+    `cannot locate the distribution root: walked up from ` +
+      `"${start ?? "(no entry script)"}" without finding ${PROFILE_FILE}. ` +
+      `Set DEN_ROOT (or <PRODUCT>_ROOT) to your checkout directory ` +
+      `(the current directory, "${process.cwd()}", is never used as an anchor).`,
+  );
+}
+
+/**
+ * Whether `<PREFIX>_ROOT` is a product root variable (rather than some other
+ * tool's): the active profile, if one is pinned by DEN_PROFILE, owns it.
+ */
+function isProductRootVar(dir: string, key: string): boolean {
+  const pinned = process.env.DEN_PROFILE?.trim();
+  if (!pinned) return false;
+  return `${loadProfile(dir).envPrefix}_ROOT` === key;
+}
+
+/**
+ * Where Den's own files live (src/, public pages, make/): the directory whose
+ * package.json is @monster-orange/den. In a distribution that is
+ * node_modules/@monster-orange/den; in Den's own checkout, its root.
+ */
+export function getEngineRoot(): string {
+  const env = process.env.DEN_ENGINE_ROOT?.trim();
+  if (env) return path.resolve(env);
+  for (const start of [entryDir(), process.cwd()]) {
+    if (!start) continue;
+    const viaWalk = walkUp(start, isEngineRootAt);
+    if (viaWalk) return viaWalk;
+    const nested = path.join(
+      start,
+      "node_modules",
+      ...ENGINE_PACKAGE.split("/"),
+    );
+    if (isEngineRootAt(nested)) return nested;
+  }
+  throw new Error(
+    `cannot locate Den's own files: no package.json named ${ENGINE_PACKAGE} ` +
+      `above the entry script or the current directory. Set DEN_ENGINE_ROOT.`,
+  );
+}
+
+/** This distribution's profile. */
+export function getProfile(): ProductProfile {
+  return loadProfile(getDistRoot());
+}
+
+/**
+ * The caller's cwd, handed over by the CLI wrapper (bin/den) in
+ * DEN_INVOKE_CWD, or the product's own `<PREFIX>_INVOKE_CWD`.
+ */
+export function getInvokeCwd(): string {
+  const handed = process.env.DEN_INVOKE_CWD?.trim();
+  if (handed) return handed;
+  try {
+    return readEnv(getProfile(), "INVOKE_CWD") ?? process.cwd();
+  } catch {
+    return process.cwd(); // no distribution root yet: the caller's cwd
+  }
+}
+
+/**
+ * Per-user state directory for this instance (web server, daemons, logs,
+ * history): the profile's state_dir (~/.<name>), or `<PREFIX>_HOME`, so two
+ * instances on one machine never share or stop each other's processes.
+ */
+export function getStateDir(): string {
+  const profile = getProfile();
+  const home = readEnv(profile, "HOME")?.trim();
+  return home ? path.resolve(home) : profile.stateDir;
+}

package/src/shared/perf/optional-fields.ts

@@ -0,0 +1,105 @@
+/**
+ * Pure resolver for declarative per-perf-test "optional launch fields".
+ *
+ * A perf test declares `PerfOptionalField[]` (in its co-located manifest.yml or
+ * `.den.yml`). The web UI renders these generically and collects raw values;
+ * this resolver turns (fields, values) into the env-var map that gets injected
+ * into THAT test's k6 process. No I/O, no globals — fully unit-tested.
+ */
+
+import type { PerfOptionalField } from "../types/index.js";
+
+type FieldValue = string | number | boolean | undefined;
+
+/** True for the canonical truthy spellings a boolean field may arrive as. */
+function isTruthy(value: FieldValue): boolean {
+  if (typeof value === "boolean") return value;
+  if (typeof value === "number") return value !== 0;
+  if (typeof value === "string") {
+    const v = value.trim().toLowerCase();
+    return v === "true" || v === "1" || v === "yes" || v === "on";
+  }
+  return false;
+}
+
+/**
+ * Resolve declared optional fields against user-supplied values into an env map.
+ *
+ * Rules (applied per field, in declaration order):
+ *  - `disabledWhen` satisfied by the (possibly defaulted) controlling field's
+ *    effective value → SKIP (no env emitted).
+ *  - effective value = values[name] ?? default.
+ *  - boolean: truthy → env = emit ?? "1"; falsy/undefined → omit.
+ *  - select: env set only when the value is one of options[].value; else omit.
+ *  - string/number: env = String(value) when defined and non-empty.
+ */
+export function resolveFieldEnv(
+  fields: PerfOptionalField[],
+  values: Record<string, FieldValue>,
+): Record<string, string> {
+  const effective = (field: PerfOptionalField): FieldValue =>
+    values[field.name] ?? field.default;
+
+  const byName = new Map(fields.map((f) => [f.name, f]));
+
+  const env: Record<string, string> = {};
+
+  for (const field of fields) {
+    if (field.disabledWhen) {
+      const controller = byName.get(field.disabledWhen.field);
+      const controllerValue = controller
+        ? effective(controller)
+        : values[field.disabledWhen.field];
+      if (matchesEquals(controllerValue, field.disabledWhen.equals)) {
+        continue;
+      }
+    }
+
+    const value = effective(field);
+
+    switch (field.type) {
+      case "boolean": {
+        if (isTruthy(value)) {
+          env[field.env] = field.emit ?? "1";
+        }
+        break;
+      }
+      case "select": {
+        const candidate =
+          value === undefined || value === null ? undefined : String(value);
+        const allowed = (field.options ?? []).some(
+          (opt) => opt.value === candidate,
+        );
+        if (candidate !== undefined && allowed) {
+          env[field.env] = candidate;
+        }
+        break;
+      }
+      case "string":
+      case "number": {
+        if (value !== undefined && value !== null && String(value) !== "") {
+          env[field.env] = String(value);
+        }
+        break;
+      }
+    }
+  }
+
+  return env;
+}
+
+/**
+ * Compare a controlling field's value against a `disabledWhen.equals` target.
+ * Booleans compare against the field's canonical truthiness so a checkbox that
+ * arrives as the string "true" still matches `equals: true`.
+ */
+function matchesEquals(
+  value: FieldValue,
+  equals: string | number | boolean,
+): boolean {
+  if (typeof equals === "boolean") {
+    return isTruthy(value) === equals;
+  }
+  if (value === undefined || value === null) return false;
+  return String(value) === String(equals);
+}