@monster-orange/den 0.1.0 → 0.2.0

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

@@ -8,6 +8,9 @@
  * copy is used: `manifests/<github-repo>.den.yml` in the Den repo, keyed by
  * the checkout's `origin` repo name. That covers repos whose manifest is not
  * merged yet and repos Den should not commit to.
+ *
+ * Whichever base won, `manifests/<github-repo>.override.yml` (when present)
+ * is deep-merged on top: see merge-override.ts for the rules.
  */
 
 import * as fs from "fs";
@@ -18,6 +21,7 @@ import { parse as parseYaml } from "yaml";
 import type { RawManifest } from "../types/index.js";
 
 import { product } from "../product.js";
+import { mergeOverride } from "./merge-override.js";
 /** Names probed in order. First match wins. */
 const MANIFEST_NAMES = [
   `${product().manifestYml}`,
@@ -76,59 +80,179 @@ function managedCloneRepo(repoPath: string): string | null {
     : null;
 }
 
-/** The den-held manifest for `repoPath`, or null. */
-export function heldManifestPath(repoPath: string): string | null {
-  const keys = [
+/** The names `repoPath` is known by: origin repo, managed clone, folder. */
+function repoKeys(repoPath: string): string[] {
+  return [
     originRepoName(repoPath),
     // A managed clone lives at .den-services/<repo>/<branch>,
     // and need not be cloned yet.
     managedCloneRepo(repoPath),
     path.basename(repoPath),
-  ];
-  for (const key of keys) {
-    if (!key) continue;
-    const p = path.join(heldManifestsDir(), `${key}${product().manifestYml}`);
+  ].filter((k): k is string => !!k);
+}
+
+/** The first `manifests/<key><suffix>` that exists, or null. */
+function heldFile(repoPath: string, suffix: string): string | null {
+  for (const key of repoKeys(repoPath)) {
+    const p = path.join(heldManifestsDir(), `${key}${suffix}`);
     if (fs.existsSync(p)) return p;
   }
   return null;
 }
 
+/** The den-held manifest for `repoPath`, or null. */
+export function heldManifestPath(repoPath: string): string | null {
+  return heldFile(repoPath, `${product().manifestYml}`);
+}
+
+/**
+ * The override suffix: `.override` plus the manifest's extension, so a
+ * profile whose manifest is `.acme.yml` reads `manifests/<repo>.override.yml`.
+ */
+export function overrideSuffix(): string {
+  return `.override${path.extname(product().manifestYml) || ".yml"}`;
+}
+
 /**
- * Resolve the manifest for `repoPath`: the repo's own .den.yml (or
+ * The override for `repoPath` (`manifests/<repo>.override.yml`), or null.
+ * Matched by the same names, in the same order, as the held manifest.
+ */
+export function overrideManifestPath(repoPath: string): string | null {
+  return heldFile(repoPath, overrideSuffix());
+}
+
+/**
+ * Resolve the base manifest for `repoPath`: the repo's own .den.yml (or
  * .json), else the one den holds for it. Returns null if neither exists.
+ * An override is layered on top by readManifest; it is never a base.
  */
 export function resolveManifestPath(repoPath: string): string | null {
   return repoManifestPath(repoPath) ?? heldManifestPath(repoPath);
 }
 
-/** Where `repoPath`'s manifest comes from. */
+/** Where `repoPath`'s base manifest comes from. */
 export function manifestSource(repoPath: string): "repo" | "held" | null {
   if (repoManifestPath(repoPath)) return "repo";
   return heldManifestPath(repoPath) ? "held" : null;
 }
 
+// ── Layers ───────────────────────────────────────────────────────────────
+
+/** A layer of a resolved manifest. The base comes first. */
+export type ManifestLayer = "repo" | "held" | "override";
+
+export interface ManifestLoad {
+  /** The merged manifest, or null when none is usable. */
+  manifest: RawManifest | null;
+  /** The layers that applied, base first: e.g. ["repo", "override"]. */
+  layers: ManifestLayer[];
+  /** The base manifest file (repo or held), or null. */
+  baseFile: string | null;
+  /** The base's layer, or null when there is no base. */
+  baseLayer: "repo" | "held" | null;
+  /** The override file, or null. */
+  overrideFile: string | null;
+  /** Why no manifest is usable, when files exist but cannot be used. */
+  error?: string;
+}
+
+/** Parse a manifest file's text: a map, or null for anything else. */
+export function parseManifestText(
+  filePath: string,
+  raw: string,
+): Record<string, unknown> | null {
+  const parsed: unknown = filePath.endsWith(".json")
+    ? JSON.parse(raw)
+    : parseYaml(raw);
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed))
+    return null; // scalar/array/empty manifest is not usable
+  return parsed as Record<string, unknown>;
+}
+
+/** The message for an override that has no base to apply to. */
+export function orphanOverrideMessage(): string {
+  return `an override with no base manifest is not a manifest: add a ${product().manifestYml} to the repo, or to manifests/`;
+}
+
+interface Located {
+  baseFile: string | null;
+  baseLayer: "repo" | "held" | null;
+  overrideFile: string | null;
+}
+
+function locate(repoPath: string): Located {
+  const own = repoManifestPath(repoPath);
+  const held = own ? null : heldManifestPath(repoPath);
+  return {
+    baseFile: own ?? held,
+    baseLayer: own ? "repo" : held ? "held" : null,
+    overrideFile: overrideManifestPath(repoPath),
+  };
+}
+
+/** Parse and merge the located files' texts. Never throws. */
+function combine(
+  at: Located,
+  baseRaw: string | null,
+  overrideRaw: string | null,
+): ManifestLoad {
+  const out: ManifestLoad = { manifest: null, layers: [], ...at };
+  const parse = (file: string, raw: string): Record<string, unknown> => {
+    const parsed = parseManifestText(file, raw);
+    if (!parsed) throw new Error(`${file}: not a map`);
+    return parsed;
+  };
+  if (!at.baseFile || !at.baseLayer || baseRaw === null) {
+    if (at.overrideFile)
+      out.error = `${at.overrideFile}: ${orphanOverrideMessage()}`;
+    return out;
+  }
+  try {
+    let manifest = parse(at.baseFile, baseRaw);
+    const layers: ManifestLayer[] = [at.baseLayer];
+    if (at.overrideFile && overrideRaw !== null) {
+      manifest = mergeOverride(manifest, parse(at.overrideFile, overrideRaw));
+      layers.push("override");
+    }
+    out.manifest = manifest as unknown as RawManifest;
+    out.layers = layers;
+  } catch (e) {
+    out.error = (e as Error).message;
+  }
+  return out;
+}
+
+/** Resolve, read and merge `repoPath`'s manifest layers. Never throws. */
+export function loadManifest(repoPath: string): ManifestLoad {
+  const at = locate(repoPath);
+  try {
+    return combine(
+      at,
+      at.baseFile && fs.readFileSync(at.baseFile, "utf-8"),
+      at.overrideFile && fs.readFileSync(at.overrideFile, "utf-8"),
+    );
+  } catch (e) {
+    return { manifest: null, layers: [], ...at, error: (e as Error).message };
+  }
+}
+
+/** The layers of `repoPath`'s manifest that applied, e.g. ["held", "override"]. */
+export function manifestLayers(repoPath: string): ManifestLayer[] {
+  return loadManifest(repoPath).layers;
+}
+
+/** "repo", "held + override", … ("none" when no manifest applied). */
+export function manifestLayersLabel(layers: readonly ManifestLayer[]): string {
+  return layers.length > 0 ? layers.join(" + ") : "none";
+}
+
 /**
- * Read and parse the manifest from `repoPath`.
+ * Read and parse the manifest from `repoPath`, its override merged in.
  * Supports both YAML and JSON.
  * Returns null if no manifest file exists or parsing fails.
  */
 export function readManifest(repoPath: string): RawManifest | null {
-  const filePath = resolveManifestPath(repoPath);
-  if (!filePath) return null;
-  try {
-    const raw = fs.readFileSync(filePath, "utf-8");
-    const parsed = filePath.endsWith(".yml") ? parseYaml(raw) : JSON.parse(raw);
-    if (
-      parsed === null ||
-      typeof parsed !== "object" ||
-      Array.isArray(parsed)
-    ) {
-      return null; // scalar/array/empty manifest is not usable
-    }
-    return parsed as RawManifest;
-  } catch {
-    return null;
-  }
+  return loadManifest(repoPath).manifest;
 }
 
 /**
@@ -137,20 +261,14 @@ export function readManifest(repoPath: string): RawManifest | null {
 export async function readManifestAsync(
   repoPath: string,
 ): Promise<RawManifest | null> {
-  const filePath = resolveManifestPath(repoPath);
-  if (!filePath) return null;
+  const at = locate(repoPath);
   try {
     const { readFile } = await import("fs/promises");
-    const raw = await readFile(filePath, "utf-8");
-    const parsed = filePath.endsWith(".yml") ? parseYaml(raw) : JSON.parse(raw);
-    if (
-      parsed === null ||
-      typeof parsed !== "object" ||
-      Array.isArray(parsed)
-    ) {
-      return null; // scalar/array/empty manifest is not usable
-    }
-    return parsed as RawManifest;
+    return combine(
+      at,
+      at.baseFile && (await readFile(at.baseFile, "utf-8")),
+      at.overrideFile && (await readFile(at.overrideFile, "utf-8")),
+    ).manifest;
   } catch {
     return null;
   }

package/src/shared/manifest/schema.ts

@@ -90,7 +90,21 @@ const httpUrlString = z
   .string()
   .regex(/^https?:\/\/\S+$/, "must be an http(s) URL");
 
+// Placement (R13): where a service runs per env, and where a remote one is.
+// Env names are checked against the org's environments in placement.ts.
+const statusCode = z.number().int().min(100).max(599);
+const serviceTarget = z
+  .object({
+    env: z.string().min(1),
+    account: z.string().min(1).optional(),
+    url: httpUrlString.optional(),
+    expect: z.union([statusCode, z.array(statusCode).min(1)]).optional(),
+  })
+  .strict();
+
 const serviceManagementConfig = z.object({
+  runs: z.record(z.string(), z.enum(["local", "remote"])).optional(),
+  target: serviceTarget.optional(),
   depends_on: z.array(dependsOnEntry).optional(),
   commands: z.record(z.string(), z.record(z.string(), commandDef)).optional(),
   logs: z.record(z.string(), logSource).optional(),

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

@@ -13,6 +13,13 @@ import {
   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 ───────────────────────────────────────────────────────────────────
 
@@ -56,6 +63,17 @@ function suggestionFor(issue: z.ZodIssue): string | undefined {
   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 ───────────────────────────────────────────────────────────────
 
 /**
@@ -64,7 +82,26 @@ function suggestionFor(issue: z.ZodIssue): string | undefined {
  * @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 {
+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") {
@@ -116,6 +153,15 @@ export function validateManifest(input: unknown): ValidationResult {
   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,
@@ -125,11 +171,7 @@ export function validateManifest(input: unknown): ValidationResult {
   }
 
   // 6. Map Zod issues → ValidationError[]
-  const errors: ValidationError[] = result.error.issues.map((issue) => ({
-    path: zodPathToString(issue.path),
-    message: zodIssueMessage(issue),
-    suggestion: suggestionFor(issue),
-  }));
+  const errors = issuesToErrors(result.error.issues);
 
   return {
     valid: false,
@@ -138,3 +180,21 @@ export function validateManifest(input: unknown): ValidationResult {
     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/paths.ts

@@ -147,6 +147,18 @@ export function getEngineRoot(): string {
   );
 }
 
+/** Den's own version (its package.json), or undefined when unreadable. */
+export function engineVersion(): string | undefined {
+  try {
+    const pkg = JSON.parse(
+      fs.readFileSync(path.join(getEngineRoot(), "package.json"), "utf-8"),
+    ) as { version?: unknown };
+    return typeof pkg.version === "string" ? pkg.version : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 /** This distribution's profile. */
 export function getProfile(): ProductProfile {
   return loadProfile(getDistRoot());