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

package/client/board-config.schema.json

@@ -0,0 +1,121 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "board-config.schema.json",
+  "title": "Ze Great Dashboard board configuration",
+  "type": "object",
+  "required": ["boards"],
+  "additionalProperties": true,
+  "properties": {
+    "sources": { "type": "object", "additionalProperties": { "$ref": "#/$defs/source" } },
+    "boards": {
+      "type": "object",
+      "minProperties": 1,
+      "additionalProperties": { "$ref": "#/$defs/board" }
+    },
+    "auth": { "$ref": "#/$defs/auth" }
+  },
+  "$defs": {
+    "duration": { "type": "string", "pattern": "^[1-9][0-9]*(?:ms|s|m|h)$" },
+    "position": {
+      "oneOf": [
+        {
+          "type": "object",
+          "required": ["x", "y", "w", "h"],
+          "properties": {
+            "x": { "type": "integer", "minimum": 0 },
+            "y": { "type": "integer", "minimum": 0 },
+            "w": { "type": "integer", "minimum": 1, "maximum": 12 },
+            "h": { "type": "integer", "minimum": 1 }
+          },
+          "additionalProperties": true
+        },
+        {
+          "type": "object",
+          "required": ["x", "y", "w", "h"],
+          "properties": {
+            "x": { "const": 0 },
+            "y": { "const": 0 },
+            "w": { "const": 0 },
+            "h": { "const": 0 }
+          },
+          "additionalProperties": true
+        }
+      ]
+    },
+    "panel": {
+      "type": "object",
+      "required": ["id", "type"],
+      "additionalProperties": true,
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "type": { "type": "string", "minLength": 1 },
+        "label": { "type": "string", "minLength": 1 },
+        "source": { "type": "string", "minLength": 1 },
+        "pipeline": { "oneOf": [{ "type": "string" }, { "type": "number" }] },
+        "density": { "enum": ["auto", "comfortable", "compact"] },
+        "position": { "$ref": "#/$defs/position" },
+        "refresh": { "$ref": "#/$defs/duration" },
+        "running_refresh": { "$ref": "#/$defs/duration" },
+        "running_completion_refresh": { "$ref": "#/$defs/duration" },
+        "running_completion_window": { "$ref": "#/$defs/duration" },
+        "running_animation": {
+          "enum": [
+            "radial",
+            "runway",
+            "orbit",
+            "signal-field",
+            "telemetry-bloom",
+            "release-transit",
+            "status-weather",
+            "falling-shapes",
+            "off"
+          ]
+        },
+        "demo_run_duration": { "$ref": "#/$defs/duration" },
+        "demo_review_duration": { "$ref": "#/$defs/duration" },
+        "link": { "type": "string", "format": "uri" },
+        "url": { "type": "string", "format": "uri" },
+        "json_path": {
+          "type": "string",
+          "pattern": "^\\$(?:\\.[A-Za-z_][A-Za-z0-9_]*|\\[\\d+\\])*$"
+        }
+      }
+    },
+    "board": {
+      "type": "object",
+      "required": ["panels"],
+      "additionalProperties": true,
+      "properties": {
+        "refresh": { "$ref": "#/$defs/duration" },
+        "running_refresh": { "$ref": "#/$defs/duration" },
+        "running_completion_refresh": { "$ref": "#/$defs/duration" },
+        "running_completion_window": { "$ref": "#/$defs/duration" },
+        "panels": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/panel" } }
+      }
+    },
+    "source": {
+      "type": "object",
+      "required": ["type"],
+      "additionalProperties": true,
+      "properties": {
+        "type": { "type": "string", "minLength": 1 },
+        "token_env": { "type": "string", "minLength": 1 }
+      }
+    },
+    "auth": {
+      "type": "object",
+      "required": ["issuer"],
+      "properties": {
+        "issuer": { "type": "string", "format": "uri" },
+        "client_id": { "type": "string", "minLength": 1 },
+        "allow": {
+          "type": "object",
+          "properties": {
+            "groups": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+            "subjects": { "type": "array", "items": { "type": "string", "minLength": 1 } }
+          }
+        }
+      }
+    }
+  }
+}

package/dist/cli.js

@@ -46,33 +46,87 @@ function computeMode(config) {
 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({
@@ -82,13 +136,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);
@@ -102,15 +361,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()
 });
@@ -123,13 +382,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),
@@ -137,7 +401,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"
@@ -147,7 +415,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 },