@monster-orange/den 0.0.0 → 0.2.0

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

@@ -0,0 +1,229 @@
+/**
+ * Validate a repo's manifest layer by layer: the base (repo or held), the
+ * override, then the merged result. Each layer's errors name its file.
+ *
+ * The override is partial, so it is not checked against the whole schema
+ * (it need not repeat `name`, say). Instead each value it sets is checked
+ * against the schema at that path, and every key it names must exist in the
+ * base (see overrideKeyErrors).
+ *
+ * The schema and the single-file validator come in as `SchemaTools`, so this
+ * file stays under the typecheck gate: schema.ts and validate-manifest.ts are
+ * still baseline-excluded (zod v4 drift), and importing them here would pull
+ * them back into the checked program. validate-manifest.ts wires them in and
+ * exports validateManifestLayers(repoPath).
+ */
+
+import * as fs from "fs";
+import { z } from "zod";
+import type { ValidationError, ValidationResult } from "../types/index.js";
+import {
+  isPlainMap,
+  mergeOverride,
+  overrideKeyErrors,
+  type ManifestMap,
+} from "./merge-override.js";
+import {
+  loadManifest,
+  orphanOverrideMessage,
+  parseManifestText,
+  type ManifestLayer,
+} from "./read-manifest.js";
+
+/** What layered validation needs from the schema module. */
+export interface SchemaTools {
+  /** The current schema version and its schema. */
+  version: number;
+  schema: z.ZodType;
+  /** Validate one whole manifest (validateManifest). */
+  validate: (input: unknown) => ValidationResult;
+  /** Map Zod issues to ValidationErrors, as validateManifest does. */
+  issuesToErrors: (issues: z.core.$ZodIssue[]) => ValidationError[];
+}
+
+export interface LayerValidation {
+  layer: ManifestLayer | "merged";
+  /** The layer's file; null for the merged result. */
+  file: string | null;
+  result: ValidationResult;
+}
+
+export interface LayeredValidation {
+  valid: boolean;
+  /**
+   * Base first, then override, then merged (only when there is an override
+   * and both layers pass on their own). Empty when no manifest file exists.
+   */
+  layers: LayerValidation[];
+}
+
+/** Strip optional/nullable/default wrappers to the schema underneath. */
+function unwrap(schema: z.ZodType): z.ZodType {
+  let s = schema;
+  for (;;) {
+    if (s instanceof z.ZodOptional || s instanceof z.ZodNullable)
+      s = s.unwrap() as z.ZodType;
+    else if (s instanceof z.ZodDefault) s = s.def.innerType as z.ZodType;
+    else return s;
+  }
+}
+
+/**
+ * Schema errors in `value`, an override's value at `at`, merging into
+ * `base` (the base's value there). Maps are walked key by key where the
+ * schema is an object or a record; anything else is checked whole (a map
+ * merged onto its base first, so a partial union member still passes).
+ */
+function overrideSchemaErrors(
+  tools: SchemaTools,
+  schema: z.ZodType,
+  value: unknown,
+  base: unknown,
+  at: string[],
+): ValidationError[] {
+  if (value === null) return []; // a delete: overrideKeyErrors checks the key
+  const node = unwrap(schema);
+  const baseAt = (key: string): unknown =>
+    isPlainMap(base) ? base[key] : undefined;
+  if (isPlainMap(value) && node instanceof z.ZodObject) {
+    const shape = node.shape as Record<string, z.ZodType>;
+    return Object.entries(value).flatMap(([key, v]) =>
+      key in shape
+        ? overrideSchemaErrors(tools, shape[key], v, baseAt(key), [...at, key])
+        : [],
+    );
+  }
+  if (isPlainMap(value) && node instanceof z.ZodRecord) {
+    const inner = node.valueType as z.ZodType;
+    return Object.entries(value).flatMap(([key, v]) =>
+      overrideSchemaErrors(tools, inner, v, baseAt(key), [...at, key]),
+    );
+  }
+  const candidate =
+    isPlainMap(value) && isPlainMap(base) ? mergeOverride(base, value) : value;
+  const result = node.safeParse(candidate);
+  return result.success
+    ? []
+    : tools.issuesToErrors(
+        result.error.issues.map((i) => ({ ...i, path: [...at, ...i.path] })),
+      );
+}
+
+/** Validate an override against the schema and against its base's keys. */
+export function validateOverride(
+  tools: SchemaTools,
+  override: unknown,
+  base: ManifestMap,
+): ValidationResult {
+  const { version } = tools;
+  if (!isPlainMap(override))
+    return {
+      valid: false,
+      version,
+      errors: [{ path: "", message: "an override must be a map" }],
+      warnings: [],
+    };
+  const errors = [
+    ...overrideKeyErrors(base, override),
+    ...overrideSchemaErrors(tools, tools.schema, override, base, []),
+  ];
+  return { valid: errors.length === 0, version, errors, warnings: [] };
+}
+
+function withFile(result: ValidationResult, file: string): ValidationResult {
+  const tag = (e: ValidationError): ValidationError => ({ ...e, file });
+  return {
+    ...result,
+    errors: result.errors.map(tag),
+    warnings: result.warnings.map(tag),
+  };
+}
+
+function failure(
+  version: number,
+  file: string,
+  message: string,
+): ValidationResult {
+  return {
+    valid: false,
+    version,
+    errors: [{ path: "", message, file }],
+    warnings: [],
+  };
+}
+
+/** Read and parse a layer file, or the reason it cannot be used. */
+function readLayer(file: string): { value: unknown } | { error: string } {
+  try {
+    const raw = fs.readFileSync(file, "utf-8");
+    // A non-map (scalar, list, empty file) is passed on as is, so the
+    // validator reports it the way it reports any other bad manifest.
+    let value: unknown;
+    try {
+      value = parseManifestText(file, raw);
+    } catch (e) {
+      return { error: `could not parse: ${(e as Error).message}` };
+    }
+    return { value: value ?? (raw.trim() ? raw : null) };
+  } catch (e) {
+    return { error: `could not read: ${(e as Error).message}` };
+  }
+}
+
+/** Validate every manifest layer of `repoPath`, then the merged result. */
+export function validateLayers(
+  tools: SchemaTools,
+  repoPath: string,
+): LayeredValidation {
+  const { baseFile, baseLayer, overrideFile } = loadManifest(repoPath);
+  const layers: LayerValidation[] = [];
+
+  if (!baseFile || !baseLayer) {
+    if (overrideFile)
+      layers.push({
+        layer: "override",
+        file: overrideFile,
+        result: failure(tools.version, overrideFile, orphanOverrideMessage()),
+      });
+    return { valid: false, layers };
+  }
+
+  const base = readLayer(baseFile);
+  const baseResult =
+    "error" in base
+      ? failure(tools.version, baseFile, base.error)
+      : withFile(tools.validate(base.value), baseFile);
+  layers.push({ layer: baseLayer, file: baseFile, result: baseResult });
+
+  if (overrideFile) {
+    const override = readLayer(overrideFile);
+    const baseMap = "value" in base && isPlainMap(base.value) ? base.value : {};
+    const overrideResult =
+      "error" in override
+        ? failure(tools.version, overrideFile, override.error)
+        : withFile(
+            validateOverride(tools, override.value, baseMap),
+            overrideFile,
+          );
+    layers.push({
+      layer: "override",
+      file: overrideFile,
+      result: overrideResult,
+    });
+    // The merged result is checked once both layers pass on their own, so a
+    // layer's error is reported once, against its own file.
+    if (
+      baseResult.valid &&
+      overrideResult.valid &&
+      "value" in override &&
+      isPlainMap(override.value)
+    )
+      layers.push({
+        layer: "merged",
+        file: null,
+        result: tools.validate(mergeOverride(baseMap, override.value)),
+      });
+  }
+
+  return { valid: layers.every((l) => l.result.valid), layers };
+}

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

@@ -0,0 +1,200 @@
+/**
+ * .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";
+import { placementErrors } from "./placement.js";
+import { builtinEnvironments, orgEnvironments } from "../den-config.js";
+import {
+  validateLayers,
+  type LayeredValidation,
+  type SchemaTools,
+} from "./validate-layers.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;
+}
+
+/** Map Zod issues to ValidationErrors. */
+export function issuesToErrors(
+  issues: readonly z.ZodIssue[],
+): ValidationError[] {
+  return issues.map((issue) => ({
+    path: zodPathToString(issue.path as (string | number)[]),
+    message: zodIssueMessage(issue),
+    suggestion: suggestionFor(issue),
+  }));
+}
+
+// ── 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 interface ValidateOptions {
+  /** The org's environments; default: the org config's (see orgEnvironments). */
+  environments?: readonly string[];
+}
+
+function environmentsFor(opts: ValidateOptions): readonly string[] {
+  if (opts.environments) return opts.environments;
+  try {
+    return orgEnvironments();
+  } catch {
+    // An unreadable org config is reported where it is read; validate the
+    // manifest against Den's built-in environment list meanwhile.
+    return builtinEnvironments();
+  }
+}
+
+export function validateManifest(
+  input: unknown,
+  opts: ValidateOptions = {},
+): 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) {
+    // Env names in `runs` / `target.env` must be the org's (R13).
+    const placement = placementErrors(parsed, environmentsFor(opts));
+    if (placement.length > 0)
+      return {
+        valid: false,
+        version: detectedVersion,
+        errors: placement,
+        warnings,
+      };
+    return {
+      valid: true,
+      version: detectedVersion,
+      errors: [],
+      warnings,
+    };
+  }
+
+  // 6. Map Zod issues → ValidationError[]
+  const errors = issuesToErrors(result.error.issues);
+
+  return {
+    valid: false,
+    version: detectedVersion,
+    errors,
+    warnings,
+  };
+}
+
+// ── Layers ────────────────────────────────────────────────────────────────────
+
+const schemaTools: SchemaTools = {
+  version: CURRENT_SCHEMA_VERSION,
+  schema: schemaByVersion[CURRENT_SCHEMA_VERSION],
+  validate: (input) => validateManifest(input),
+  issuesToErrors: (issues) => issuesToErrors(issues as z.ZodIssue[]),
+};
+
+/**
+ * Validate each manifest layer of the repo at `repoPath` (its own or the
+ * held manifest, then manifests/<repo>.override.yml), then the merge.
+ * See validate-layers.ts.
+ */
+export function validateManifestLayers(repoPath: string): LayeredValidation {
+  return validateLayers(schemaTools, repoPath);
+}

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;
+  }
+}