@continuous-excellence/ze-great-dashboard-aws 0.16.0 → 0.17.0

package/dist/index.js

@@ -728,33 +728,87 @@ import { parseDocument, Scalar } from "yaml";
 import { createHash } from "node:crypto";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { join, resolve } from "node:path";
-import { parse, stringify } from "yaml";
+
+// packages/shared/src/board-config.ts
 import { z as z2 } from "zod";
 
-// packages/aws/src/internal-board.ts
+// packages/shared/src/duration.ts
 import { z } from "zod";
-var durationSchema = z.string().regex(/^\d+(?:ms|s|m|h)$/).refine((value2) => Number.parseInt(value2, 10) > 0).brand();
-var positionSchema = z.union([
-  z.object({
-    x: z.number().int().min(0),
-    y: z.number().int().min(0),
-    w: z.number().int().min(1).max(12),
-    h: z.number().int().min(1)
+var DURATION_PATTERN = /^(\d+)(ms|s|m|h)$/;
+var UNIT_MILLIS = {
+  ms: 1,
+  s: 1e3,
+  m: 6e4,
+  h: 36e5
+};
+function parseDuration(value2) {
+  const match = DURATION_PATTERN.exec(value2);
+  if (!match) return null;
+  const [, rawAmount, rawUnit] = match;
+  if (rawAmount === void 0 || rawUnit === void 0) return null;
+  const amount = Number(rawAmount);
+  if (amount <= 0) return null;
+  return amount * UNIT_MILLIS[rawUnit];
+}
+var durationSchema = z.string().refine((value2) => parseDuration(value2) !== null, {
+  message: 'must be a positive duration like "30s", "5m", or "1h"'
+}).brand();
+
+// packages/shared/src/board-config.ts
+var positionSchema = z2.union([
+  z2.object({
+    x: z2.number().int().min(0),
+    y: z2.number().int().min(0),
+    w: z2.number().int().min(1).max(12),
+    h: z2.number().int().min(1)
   }),
-  z.object({ x: z.literal(0), y: z.literal(0), w: z.literal(0), h: z.literal(0) })
+  z2.object({ x: z2.literal(0), y: z2.literal(0), w: z2.literal(0), h: z2.literal(0) })
 ]);
-var panelSchema = z.looseObject({
-  // Presentation-only; ids still address proxy calls and the generated allowlist.
-  label: z.string().min(1).optional(),
-  id: z.string().min(1),
-  type: z.string().min(1),
-  source: z.string().min(1).optional(),
-  density: z.enum(["auto", "comfortable", "compact"]).optional(),
+var panelDensities = ["auto", "comfortable", "compact"];
+var panelDensitySchema = z2.enum(panelDensities);
+var visibleRunningAnimations = [
+  "radial",
+  "runway",
+  "orbit",
+  "signal-field",
+  "telemetry-bloom",
+  "release-transit",
+  "status-weather",
+  "falling-shapes"
+];
+var runningAnimationSchema = z2.enum([...visibleRunningAnimations, "off"]);
+var panelSchema = z2.looseObject({
+  /** Presentation-only wall label. `id` remains the stable proxy and allowlist address. */
+  label: z2.string().min(1).optional(),
+  id: z2.string().min(1),
+  type: z2.string().min(1),
+  source: z2.string().min(1).optional(),
+  pipeline: z2.union([z2.string(), z2.number()]).optional(),
+  /** Resolved public source branch, supplied by the board endpoint for client memory scoping. */
+  branch: z2.string().min(1).optional(),
+  /** Content-density bias; position still controls the panel's explicit grid placement. */
+  density: panelDensitySchema.optional(),
+  /** Advisory in v1 — a panel without a position renders in config order rather than not at all. */
   position: positionSchema.optional(),
   refresh: durationSchema.optional(),
-  link: z.url().optional(),
-  url: z.url().optional(),
-  json_path: z.string().regex(/^\$(?:\.[A-Za-z_][A-Za-z0-9_]*|\[\d+\])*$/).optional()
+  /** Active pipeline runs are checked more often than normal panels. */
+  running_refresh: durationSchema.optional(),
+  /** Polling cadence around the estimated completion boundary. */
+  running_completion_refresh: durationSchema.optional(),
+  /** Maximum length of the tighter completion polling burst. */
+  running_completion_window: durationSchema.optional(),
+  /** Optional active-run treatment. Omitted selects a visible treatment at random. */
+  running_animation: runningAnimationSchema.optional(),
+  /** Local animation-demo cycle duration; ignored by other panel types. */
+  demo_run_duration: durationSchema.optional(),
+  /** Local animation-demo focused-review duration; ignored by other panel types. */
+  demo_review_duration: durationSchema.optional(),
+  /** A deliberate override only. Adapters derive links; hand-written ones drift. */
+  link: z2.url().optional(),
+  /** Source-agnostic endpoint used by the http-value signal. */
+  url: z2.url().optional(),
+  /** Small, deliberate JSON path subset: $.version, $.deployment.version, or $.response.docs[0].latestVersion. */
+  json_path: z2.string().regex(/^\$(?:\.[A-Za-z_][A-Za-z0-9_]*|\[\d+\])*$/, "must be a simple JSON path").optional()
 }).superRefine((panel, ctx) => {
   if ("display" in panel) {
     ctx.addIssue({
@@ -764,13 +818,218 @@ var panelSchema = z.looseObject({
     });
   }
 });
-var sourceSchema = z.looseObject({
-  type: z.string().min(1),
-  token_env: z.string().min(1).optional()
+var sourceSchema = z2.looseObject({
+  type: z2.string().min(1),
+  /** Credentials are never in the config — only the name of the env var holding one. */
+  token_env: z2.string().min(1).optional()
 });
-var boardSchema = z.object({
+var boardSchema = z2.object({
   refresh: durationSchema.optional(),
-  panels: z.array(panelSchema).min(1).superRefine((panels, ctx) => {
+  running_refresh: durationSchema.optional(),
+  running_completion_refresh: durationSchema.optional(),
+  running_completion_window: durationSchema.optional(),
+  panels: z2.array(panelSchema).min(1).superRefine((panels, ctx) => {
+    const seen = /* @__PURE__ */ new Map();
+    panels.forEach((panel, index) => {
+      const firstIndex = seen.get(panel.id);
+      if (firstIndex === void 0) {
+        seen.set(panel.id, index);
+        return;
+      }
+      ctx.addIssue({
+        code: "custom",
+        path: [index, "id"],
+        message: `duplicate panel id "${panel.id}" (already used by panel at index ${firstIndex})`
+      });
+    });
+  })
+});
+var authSchema = z2.object({
+  issuer: z2.url(),
+  /** Absent in gateway mode — the gateway does the flow, the proxy still validates. */
+  client_id: z2.string().min(1).optional(),
+  allow: z2.object({
+    groups: z2.array(z2.string().min(1)).optional(),
+    subjects: z2.array(z2.string().min(1)).optional()
+  }).optional()
+});
+var boardConfigSchema = z2.object({
+  sources: z2.record(z2.string().min(1), sourceSchema).default({}),
+  boards: z2.record(z2.string().min(1), boardSchema),
+  auth: authSchema.optional()
+});
+
+// packages/shared/src/board-config-modeline.ts
+var MODEL_LINE = /^# yaml-language-server:\s*\$schema=(\S+)\s*$/;
+var SCHEMA_FILE = "board-config.schema.json";
+function readBoardSchemaModeline(source) {
+  const line = source.split(/\r?\n/).find((candidate) => candidate.includes("yaml-language-server"));
+  if (!line) throw new Error(`Board configuration must include a ${SCHEMA_FILE} modeline`);
+  const match = MODEL_LINE.exec(line);
+  if (!match?.[1]) {
+    throw new Error(
+      `Malformed board schema modeline; expected "# yaml-language-server: $schema=<URL>/${SCHEMA_FILE}"`
+    );
+  }
+  let url;
+  try {
+    url = new URL(match[1]);
+  } catch {
+    throw new Error(`Malformed board schema modeline; schema URL is not a valid URL: ${match[1]}`);
+  }
+  if (!["http:", "https:"].includes(url.protocol) || !url.pathname.endsWith(`/${SCHEMA_FILE}`)) {
+    throw new Error(`Malformed board schema modeline; URL must end in /${SCHEMA_FILE}: ${match[1]}`);
+  }
+  return match[1];
+}
+function boardSchemaModeline(url) {
+  return `# yaml-language-server: $schema=${url}`;
+}
+var boardSchemaFileName = SCHEMA_FILE;
+
+// packages/shared/src/client-env.ts
+import { z as z3 } from "zod";
+var clientEnvSchema = z3.object({
+  /** Where the immutable client assets live. The one variable that repoints the whole client. */
+  assetPath: z3.string().min(1),
+  /** Same-origin path the proxy is mounted at, so there is no CORS and no cookie problem. */
+  proxyPath: z3.string().min(1),
+  /** Which board this is, resolved server-side so the client parses no URLs. */
+  board: z3.string().min(1),
+  /** The client version being served, so two published versions are visibly distinguishable. */
+  clientVersion: z3.string().min(1),
+  /** Omitted entirely when unauthenticated — presence is what turns auth on. */
+  auth: z3.object({
+    issuer: z3.string().min(1),
+    clientId: z3.string().min(1).optional()
+  }).optional()
+});
+var clientIdentitySchema = clientEnvSchema.pick({ assetPath: true, clientVersion: true });
+
+// packages/shared/src/envelope.ts
+import { z as z4 } from "zod";
+var errorKindSchema = z4.enum([
+  "unreachable",
+  "unauthorized",
+  "not-found",
+  "no-runs",
+  "upstream-error"
+]);
+var envelopeErrorSchema = z4.object({
+  kind: errorKindSchema,
+  message: z4.string()
+});
+var envelopeSchema = z4.discriminatedUnion("state", [
+  z4.object({
+    panelId: z4.string().min(1),
+    state: z4.literal("ok"),
+    /** From the upstream response `Date`. A cached value must never be shown without its age. */
+    observedAt: z4.iso.datetime(),
+    /** Adapter-derived. The authority for this panel; the dashboard itself asserts nothing. */
+    link: z4.url().nullable(),
+    signal: z4.unknown()
+  }),
+  z4.object({
+    panelId: z4.string().min(1),
+    state: z4.literal("error"),
+    /**
+     * Populated even on error: knowing *when* a failure was observed is the difference between
+     * "broken just now" and "broken all morning", and a panel that can't reach its source is
+     * exactly when a viewer most wants to click through.
+     */
+    observedAt: z4.iso.datetime(),
+    link: z4.url().nullable(),
+    error: envelopeErrorSchema
+  })
+]);
+var pipelineActivitySchema = z4.object({
+  kind: z4.enum(["job", "stage", "step"]),
+  name: z4.string().min(1),
+  parent: z4.string().min(1).optional()
+});
+var pipelineStatusSchema = z4.object({
+  type: z4.literal("pipeline-status"),
+  status: z4.enum(["passed", "failed", "running", "cancelled", "unknown"]),
+  /** The source's unmodified status/result vocabulary, for an honest display. */
+  rawStatus: z4.string(),
+  name: z4.string().min(1),
+  /** The branch represented by this status, when the upstream supplies or filters by one. */
+  branch: z4.string().min(1).optional(),
+  /** Elapsed execution time, supplied only after the upstream run has completed. */
+  durationMs: z4.number().int().nonnegative().optional(),
+  /** When an active run began, so the client can advance its elapsed display between polls. */
+  runStartedAt: z4.iso.datetime().optional(),
+  /** Stable source-run identity, when the adapter provides one. */
+  sourceRunId: z4.string().min(1).optional(),
+  /** Best-effort live work detail; adapters may describe a job, stage, or step. */
+  activity: pipelineActivitySchema.optional(),
+  /** Advisory duration from recent completed runs remembered by this browser. */
+  estimatedDurationMs: z4.number().int().positive().optional(),
+  /** When this workflow run was last updated by its source, distinct from our observation time. */
+  sourceUpdatedAt: z4.iso.datetime().optional()
+});
+var pullRequestHealthItemSchema = z4.object({
+  label: z4.string().min(1),
+  status: pipelineStatusSchema.shape.status,
+  detail: z4.string().min(1),
+  link: z4.url().nullable()
+});
+var pullRequestHealthSchema = z4.object({
+  type: z4.literal("pull-request-health"),
+  status: pipelineStatusSchema.shape.status,
+  summary: z4.string().min(1),
+  workflows: z4.array(pullRequestHealthItemSchema),
+  pullRequests: z4.array(pullRequestHealthItemSchema)
+});
+var httpValueSchema = z4.object({
+  type: z4.literal("http-value"),
+  value: z4.union([z4.string(), z4.number(), z4.boolean()])
+});
+
+// packages/aws/src/release.ts
+import { parse, stringify } from "yaml";
+import { z as z6 } from "zod";
+
+// packages/aws/src/internal-board.ts
+import { z as z5 } from "zod";
+var durationSchema2 = z5.string().regex(/^\d+(?:ms|s|m|h)$/).refine((value2) => Number.parseInt(value2, 10) > 0).brand();
+var positionSchema2 = z5.union([
+  z5.object({
+    x: z5.number().int().min(0),
+    y: z5.number().int().min(0),
+    w: z5.number().int().min(1).max(12),
+    h: z5.number().int().min(1)
+  }),
+  z5.object({ x: z5.literal(0), y: z5.literal(0), w: z5.literal(0), h: z5.literal(0) })
+]);
+var panelSchema2 = z5.looseObject({
+  // Presentation-only; ids still address proxy calls and the generated allowlist.
+  label: z5.string().min(1).optional(),
+  id: z5.string().min(1),
+  type: z5.string().min(1),
+  source: z5.string().min(1).optional(),
+  density: z5.enum(["auto", "comfortable", "compact"]).optional(),
+  position: positionSchema2.optional(),
+  refresh: durationSchema2.optional(),
+  link: z5.url().optional(),
+  url: z5.url().optional(),
+  json_path: z5.string().regex(/^\$(?:\.[A-Za-z_][A-Za-z0-9_]*|\[\d+\])*$/).optional()
+}).superRefine((panel, ctx) => {
+  if ("display" in panel) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["display"],
+      message: "display was removed; use density"
+    });
+  }
+});
+var sourceSchema2 = z5.looseObject({
+  type: z5.string().min(1),
+  token_env: z5.string().min(1).optional()
+});
+var boardSchema2 = z5.object({
+  refresh: durationSchema2.optional(),
+  panels: z5.array(panelSchema2).min(1).superRefine((panels, ctx) => {
     const seen = /* @__PURE__ */ new Map();
     panels.forEach((panel, index) => {
       const firstIndex = seen.get(panel.id);
@@ -784,15 +1043,15 @@ var boardSchema = z.object({
     });
   })
 });
-var boardConfigSchema = z.object({
-  sources: z.record(z.string().min(1), sourceSchema).default({}),
-  boards: z.record(z.string().min(1), boardSchema),
-  auth: z.object({
-    issuer: z.url(),
-    client_id: z.string().min(1).optional(),
-    allow: z.object({
-      groups: z.array(z.string().min(1)).optional(),
-      subjects: z.array(z.string().min(1)).optional()
+var boardConfigSchema2 = z5.object({
+  sources: z5.record(z5.string().min(1), sourceSchema2).default({}),
+  boards: z5.record(z5.string().min(1), boardSchema2),
+  auth: z5.object({
+    issuer: z5.url(),
+    client_id: z5.string().min(1).optional(),
+    allow: z5.object({
+      groups: z5.array(z5.string().min(1)).optional(),
+      subjects: z5.array(z5.string().min(1)).optional()
     }).optional()
   }).optional()
 });
@@ -805,13 +1064,18 @@ function clientAssetUrl(version, domain = CANONICAL_ASSET_DOMAIN) {
     throw new Error(`Invalid dashboard version: ${version}`);
   return `${domain.replace(/\/+$/, "")}/dashboard/${version}`;
 }
-async function validateBoardConfig(path) {
+async function validateBoardConfig(path, expectedSchemaUrl) {
   const source = await readFile(resolve(path), "utf8");
-  const result = boardConfigSchema.safeParse(parse(source));
-  if (!result.success)
+  const authoredSchemaUrl = readBoardSchemaModeline(source);
+  const result = boardConfigSchema2.safeParse(parse(source));
+  if (!result.success) {
+    const stale = authoredSchemaUrl !== expectedSchemaUrl ? `
+Stale schema modeline: expected ${expectedSchemaUrl}` : "";
     throw new Error(`Invalid board configuration:
-${z2.prettifyError(result.error)}`);
-  const yaml = stringify(result.data, { sortMapEntries: true });
+${z6.prettifyError(result.error)}${stale}`);
+  }
+  const yaml = `${boardSchemaModeline(expectedSchemaUrl)}
+${stringify(result.data, { sortMapEntries: true })}`;
   return {
     yaml,
     sha256: sha256(yaml),
@@ -819,7 +1083,11 @@ ${z2.prettifyError(result.error)}`);
   };
 }
 async function assembleRelease(input) {
-  const board = await validateBoardConfig(input.boardConfigPath);
+  const assetUrl = clientAssetUrl(input.version, input.assetDomain);
+  const board = await validateBoardConfig(
+    input.boardConfigPath,
+    `${assetUrl}/${boardSchemaFileName}`
+  );
   if (board.usesCredentials && !input.secretReference)
     throw new Error(
       "Board config uses token_env; SecretReference must name a Secrets Manager credential-map or Parameter Store SecureString ARN"
@@ -829,7 +1097,7 @@ async function assembleRelease(input) {
   await writeFile(join(outputDir, "board.yaml"), board.yaml);
   const metadata = {
     dashboardVersion: input.version,
-    clientAssetUrl: clientAssetUrl(input.version, input.assetDomain),
+    clientAssetUrl: assetUrl,
     serverRuntimeVersion: CORE_RUNTIME_VERSION,
     supportedProviders: input.providers ?? ["aws-lambda"],
     artifactChecksums: { "board.yaml": board.sha256 },

package/dist/lambda.mjs

@@ -64060,6 +64060,36 @@ var boardConfigSchema = external_exports.object({
   auth: authSchema.optional()
 });
 
+// packages/shared/src/board-config-modeline.ts
+var MODEL_LINE = /^# yaml-language-server:\s*\$schema=(\S+)\s*$/;
+var SCHEMA_FILE = "board-config.schema.json";
+function schemaUrlForAssetPath(assetPath) {
+  return `${assetPath.replace(/\/+$/, "")}/${SCHEMA_FILE}`;
+}
+function readBoardSchemaModeline(source) {
+  const line = source.split(/\r?\n/).find((candidate) => candidate.includes("yaml-language-server"));
+  if (!line) throw new Error(`Board configuration must include a ${SCHEMA_FILE} modeline`);
+  const match2 = MODEL_LINE.exec(line);
+  if (!match2?.[1]) {
+    throw new Error(
+      `Malformed board schema modeline; expected "# yaml-language-server: $schema=<URL>/${SCHEMA_FILE}"`
+    );
+  }
+  let url2;
+  try {
+    url2 = new URL(match2[1]);
+  } catch {
+    throw new Error(`Malformed board schema modeline; schema URL is not a valid URL: ${match2[1]}`);
+  }
+  if (!["http:", "https:"].includes(url2.protocol) || !url2.pathname.endsWith(`/${SCHEMA_FILE}`)) {
+    throw new Error(`Malformed board schema modeline; URL must end in /${SCHEMA_FILE}: ${match2[1]}`);
+  }
+  return match2[1];
+}
+function boardSchemaModeline(url2) {
+  return `# yaml-language-server: $schema=${url2}`;
+}
+
 // packages/shared/src/client-env.ts
 var clientEnvSchema = external_exports.object({
   /** Where the immutable client assets live. The one variable that repoints the whole client. */
@@ -67039,12 +67069,16 @@ function createApp(deps) {
       ...deps.boardConfig.auth ? { auth: deps.boardConfig.auth } : {}
     };
     const filenameBoard = safeDownloadFilename(boardName);
-    return new Response((0, import_yaml.stringify)(outputConfig, { sortMapEntries: true }), {
-      headers: {
-        "content-type": "text/yaml; charset=utf-8",
-        "content-disposition": `attachment; filename="${filenameBoard}-layout-${mode}.yaml"`
+    return new Response(
+      `${boardSchemaModeline(schemaUrlForAssetPath(config2.assetPath))}
+${(0, import_yaml.stringify)(outputConfig, { sortMapEntries: true })}`,
+      {
+        headers: {
+          "content-type": "text/yaml; charset=utf-8",
+          "content-disposition": `attachment; filename="${filenameBoard}-layout-${mode}.yaml"`
+        }
       }
-    });
+    );
   };
   app.get("/api/boards/:board/rendered", (c5) => layoutDownload(c5, "rendered"));
   app.get("/api/boards/:board/authored", (c5) => layoutDownload(c5, "authored"));
@@ -67138,11 +67172,16 @@ function deriveVersionLabel(assetPath) {
 // packages/server/src/board-config.ts
 import { readFile as readFile3 } from "node:fs/promises";
 var import_yaml2 = __toESM(require_dist(), 1);
-async function loadBoardConfig(location, fetcher = globalThis.fetch) {
+async function loadBoardConfig(location, fetcher = globalThis.fetch, expectedSchemaUrl) {
   const text = isUrl(location) ? await fetchBoardConfig(location, fetcher) : await readFile3(location, "utf-8");
+  const authoredSchemaUrl = readBoardSchemaModeline(text);
   const result = boardConfigSchema.safeParse((0, import_yaml2.parse)(text));
-  if (!result.success) throw new Error(`Invalid board configuration:
-${result.error.message}`);
+  if (!result.success) {
+    const stale = expectedSchemaUrl && authoredSchemaUrl !== expectedSchemaUrl ? `
+Stale schema modeline: expected ${expectedSchemaUrl}` : "";
+    throw new Error(`Invalid board configuration:
+${result.error.message}${stale}`);
+  }
   return result.data;
 }
 function isUrl(value) {
@@ -67218,7 +67257,11 @@ async function startup(options = {}) {
   const fetcher = options.fetcher ?? globalThis.fetch;
   const [, boardConfig] = await Promise.all([
     waitForTemplate(config2, fetcher),
-    loadBoardConfig(config2.boardConfigUrl, fetcher)
+    loadBoardConfig(
+      config2.boardConfigUrl,
+      fetcher,
+      config2.assetPath.includes("__ASSET_PATH__") ? void 0 : schemaUrlForAssetPath(config2.assetPath)
+    )
   ]);
   const board = selectBoard(config2.board, boardConfig);
   const resolvedConfig = { ...config2, board };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@continuous-excellence/ze-great-dashboard-aws",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "type": "module",
   "description": "AWS Lambda and CloudFormation adapter for Ze Great Dashboard.",
   "keywords": [
@@ -29,6 +29,7 @@
   "files": [
     "dist",
     "client",
+    "board-config.schema.json",
     "bootstrap",
     "template.yml",
     "template-ecs.yml",