deepline 0.3.97 → 0.3.98

package/dist/monitor-fleet-contract.mjs

@@ -1,14 +1,207 @@
+// ../integration-contracts/monitor-input-contract.ts
+import Handlebars from "handlebars";
+function authoredMonitorFieldPath(path, field) {
+  const batch = /^monitors\.(\d+)$/.exec(path);
+  return `${batch ? `monitors[${batch[1]}]` : path}.${field}`;
+}
+function record(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+function json(value, path, issues) {
+  if (value === null || typeof value === "string" || typeof value === "boolean" || typeof value === "number" && Number.isFinite(value)) {
+    return;
+  }
+  if (Array.isArray(value)) {
+    value.forEach((child, index) => json(child, `${path}.${index}`, issues));
+    return;
+  }
+  const object = record(value);
+  if (!object) {
+    issues.push({
+      severity: "error",
+      code: "invalid_monitor_json_value",
+      path,
+      message: "Monitor values must be JSON values."
+    });
+    return;
+  }
+  for (const [key, child] of Object.entries(object)) {
+    json(child, `${path}.${key}`, issues);
+  }
+}
+function monitorSpec(value, path, issues) {
+  const input = record(value);
+  if (!input) {
+    issues.push({
+      severity: "error",
+      code: "invalid_monitor_spec",
+      path,
+      message: "A monitor must be a JSON object."
+    });
+    return null;
+  }
+  const allowed = /* @__PURE__ */ new Set(["key", "tool", "name", "payload"]);
+  for (const key2 of Object.keys(input)) {
+    if (!allowed.has(key2)) {
+      if (key2 === "controls") {
+        issues.push({
+          severity: "error",
+          code: "CONTROLS_NOT_SUPPORTED",
+          path: authoredMonitorFieldPath(path, "controls"),
+          message: "Operational controls are managed by Deepline and cannot be authored in Batch or Fleet JSON.",
+          suggestion: "Remove controls. Bind downstream automation in a Play with sqlListeners."
+        });
+        continue;
+      }
+      if (key2 === "play") {
+        issues.push({
+          severity: "error",
+          code: "PLAY_BINDING_NOT_IN_MONITOR_SPEC",
+          path: authoredMonitorFieldPath(path, "play"),
+          message: "A monitor does not own Play bindings.",
+          suggestion: "Declare sqlListeners in the Play, or run: deepline plays bootstrap monitor-triggered --out on-event.play.ts"
+        });
+        continue;
+      }
+      issues.push({
+        severity: "error",
+        code: "unknown_monitor_field",
+        path: `${path}.${key2}`,
+        message: `Monitor definitions do not accept '${key2}'.`
+      });
+    }
+  }
+  const key = typeof input.key === "string" ? input.key.trim() : "";
+  const tool = typeof input.tool === "string" ? input.tool.trim() : "";
+  const name = input.name === void 0 ? void 0 : typeof input.name === "string" && input.name.trim() ? input.name.trim() : null;
+  const payload = record(input.payload);
+  if (!key) {
+    issues.push({
+      severity: "error",
+      code: "invalid_monitor_key",
+      path: `${path}.key`,
+      message: "Monitor key must be a non-empty string."
+    });
+  }
+  if (!tool) {
+    issues.push({
+      severity: "error",
+      code: "invalid_monitor_tool",
+      path: `${path}.tool`,
+      message: "Monitor tool must be a non-empty literal string."
+    });
+  }
+  if (name === null) {
+    issues.push({
+      severity: "error",
+      code: "invalid_monitor_name",
+      path: `${path}.name`,
+      message: "Monitor name must be a non-empty string when supplied."
+    });
+  }
+  if (!payload) {
+    issues.push({
+      severity: "error",
+      code: "invalid_monitor_payload",
+      path: `${path}.payload`,
+      message: "Monitor payload must be an object."
+    });
+  } else {
+    json(payload, `${path}.payload`, issues);
+  }
+  if (!key || !tool || !payload || name === null) {
+    return null;
+  }
+  return {
+    key,
+    tool,
+    ...name ? { name } : {},
+    payload
+  };
+}
+function issueOrder(left, right) {
+  return left.path.localeCompare(right.path) || left.severity.localeCompare(right.severity) || left.code.localeCompare(right.code);
+}
+function validateHandlebars(value, path, issues) {
+  if (!value.includes("{{")) return;
+  try {
+    Handlebars.parse(value);
+  } catch (error) {
+    issues.push({
+      severity: "error",
+      code: "invalid_handlebars_template",
+      path,
+      message: error instanceof Error ? error.message : "Invalid Handlebars template."
+    });
+    return;
+  }
+  const expressions = value.match(/{{[\s\S]*?}}/g) ?? [];
+  if (expressions.some(
+    (expression) => !/^{{\s*[A-Za-z_][A-Za-z0-9_]*\s*}}$/.test(expression)
+  )) {
+    issues.push({
+      severity: "error",
+      code: "unsupported_handlebars_expression",
+      path,
+      message: "Fleet templates allow only direct source-row fields such as {{domain}}; helpers, blocks, partials, paths, and prototype access are disabled."
+    });
+  }
+}
+function walkTemplates(value, path, issues) {
+  if (typeof value === "string") return validateHandlebars(value, path, issues);
+  if (Array.isArray(value)) {
+    value.forEach(
+      (item, index) => walkTemplates(item, `${path}.${index}`, issues)
+    );
+    return;
+  }
+  const input = record(value);
+  if (!input) return;
+  for (const [key, child] of Object.entries(input)) {
+    walkTemplates(child, `${path}.${key}`, issues);
+  }
+}
+function lintMonitorSpecTemplate(value, path = "monitor") {
+  const issues = [];
+  const normalized = monitorSpec(value, path, issues);
+  const input = record(value);
+  if (input && typeof input.tool === "string" && input.tool.includes("{{")) {
+    issues.push({
+      severity: "error",
+      code: "templated_monitor_tool",
+      path: `${path}.tool`,
+      message: "Fleet monitor tool must be literal; only key, name, and payload may be templated."
+    });
+  }
+  if (input) {
+    for (const field of ["key", "name", "payload"]) {
+      if (input[field] !== void 0)
+        walkTemplates(input[field], `${path}.${field}`, issues);
+    }
+  }
+  const ordered = issues.sort(issueOrder);
+  return ordered.some((issue) => issue.severity === "error") ? { issues: ordered } : { normalized, issues: ordered };
+}
+
 // ../integration-contracts/monitor-fleet-contract.ts
 var MONITOR_FLEET_MAX_MEMBERS = 1e3;
 var MONITOR_FLEET_FRONTIER_MAX_ROWS = 1e4;
-var MONITOR_FLEET_AUTHORING_CONTRACT_EDITION = 1;
+var MONITOR_FLEET_AUTHORING_CONTRACT_EDITION = 2;
 var SUPPORTED_MONITOR_FLEET_AUTHORING_CONTRACT_EDITIONS = [
-  MONITOR_FLEET_AUTHORING_CONTRACT_EDITION
+  1,
+  2
 ];
 var MONITOR_FLEET_AUTHORING_CONTRACT_CHANGELOG = [
   {
     edition: 1,
-    changed: "Initial Fleet JSON contract: bounded sticky table membership, one daily sync, and a seven-day removal grace.",
+    changed: "Initial Fleet JSON contract: bounded sticky table membership, source refresh, and a seven-day removal grace.",
+    compatibilityOwner: "Monitors Runtime",
+    newWritesEnd: null,
+    readerRemoval: null
+  },
+  {
+    edition: 2,
+    changed: "Canonical table-backed Fleet envelope with one Handlebars MonitorSpec template.",
     compatibilityOwner: "Monitors Runtime",
     newWritesEnd: null,
     readerRemoval: null
@@ -20,11 +213,11 @@ var MONITOR_FLEET_DOCUMENTATION = {
   authoredFields: {
     id: "Stable lowercase fleet id used by sync, get, and deactivate.",
     source: "Customer DB table, unique row key, and optional equality filters that select candidate rows.",
-    member: "Ordinary monitor tool, stable key template, and payload evaluated for each selected source row.",
+    monitor: "One Batch-compatible MonitorSpec. Direct Handlebars source-row fields such as {{domain}} are rendered for each selected row.",
     selection: "Deterministic ranking and an active-member limit between 1 and 1,000."
   },
   fixedPolicy: {
-    cadence: "daily",
+    cadence: "60s fair bounded source refresh",
     membership: "sticky",
     removalGrace: "7d",
     onRemoved: "deactivate",
@@ -32,9 +225,10 @@ var MONITOR_FLEET_DOCUMENTATION = {
     billing: "No Fleet fee, permit, or renewal. Dry-run reports ordinary monitor lifecycle charges due now."
   },
   stickyMembership: "Ranking fills vacancies but never replaces a current member merely because another row ranks higher.",
-  columnExpression: 'Use { "$fleet": "column", "name": "column_name" } in a member key or payload to read a value from each source row.'
+  templating: "Use direct Handlebars fields such as {{domain}} in monitor key, name, or payload. Helpers, blocks, partials, paths, and prototype access are disabled.",
+  legacyCompatibility: 'Edition 1 member/$fleet files remain readable with a lint warning; new files should use version: 2, kind: "fleet", and monitor.'
 };
-function record(value) {
+function record2(value) {
   return value && typeof value === "object" && !Array.isArray(value) ? value : null;
 }
 function identifier(value) {
@@ -59,7 +253,7 @@ function jsonValue(value, path, issues) {
     value.forEach((item, index) => jsonValue(item, `${path}.${index}`, issues));
     return;
   }
-  const input = record(value);
+  const input = record2(value);
   if (!input) {
     issues.push({
       path,
@@ -85,7 +279,7 @@ function defineMonitorFleet(definition) {
   return definition;
 }
 function validateExpression(value, path, issues) {
-  const input = record(value);
+  const input = record2(value);
   if (!input || input.$fleet !== "column" || !identifier(input.name)) {
     issues.push({
       path,
@@ -103,7 +297,7 @@ function walkPayload(value, path, issues) {
     );
     return;
   }
-  const input = record(value);
+  const input = record2(value);
   if (!input) return;
   if ("$fleet" in input) {
     validateExpression(input, path, issues);
@@ -113,9 +307,9 @@ function walkPayload(value, path, issues) {
     walkPayload(item, `${path}.${key}`, issues);
   }
 }
-function validateMonitorFleetDefinition(value) {
+function validateMonitorFleetDefinitionV1(value) {
   const issues = [];
-  const input = record(value);
+  const input = record2(value);
   if (!input) {
     return {
       valid: false,
@@ -136,7 +330,7 @@ function validateMonitorFleetDefinition(value) {
       message: "Fleet id must be lowercase kebab-case."
     });
   }
-  const source = record(input.source);
+  const source = record2(input.source);
   exactKeys(
     source,
     ["kind", "schema", "table", "key", "where"],
@@ -157,7 +351,7 @@ function validateMonitorFleetDefinition(value) {
       message: "Source schema and table must be SQL identifiers."
     });
   }
-  const sourceKey = record(source?.key);
+  const sourceKey = record2(source?.key);
   exactKeys(sourceKey, ["column", "type"], "source.key", issues);
   if (!sourceKey || !identifier(sourceKey.column) || !["text", "uuid", "int4", "int8"].includes(String(sourceKey.type))) {
     issues.push({
@@ -167,7 +361,7 @@ function validateMonitorFleetDefinition(value) {
     });
   }
   if (source?.where !== void 0) {
-    const where = record(source.where);
+    const where = record2(source.where);
     if (!where) {
       issues.push({
         path: "source.where",
@@ -193,9 +387,9 @@ function validateMonitorFleetDefinition(value) {
       }
     }
   }
-  const member = record(input.member);
+  const member = record2(input.member);
   exactKeys(member, ["tool", "key", "payload"], "member", issues);
-  const key = record(member?.key);
+  const key = record2(member?.key);
   if (!member || typeof member.tool !== "string" || !member.tool.trim()) {
     issues.push({
       path: "member.tool",
@@ -216,7 +410,7 @@ function validateMonitorFleetDefinition(value) {
         validateExpression(part, `member.key.parts.${index}`, issues);
     }
     if (sourceKey && !key.parts.some(
-      (part) => record(part)?.$fleet === "column" && record(part)?.name === sourceKey.column
+      (part) => record2(part)?.$fleet === "column" && record2(part)?.name === sourceKey.column
     )) {
       issues.push({
         path: "member.key.parts",
@@ -235,7 +429,7 @@ function validateMonitorFleetDefinition(value) {
     jsonValue(member.payload, "member.payload", issues);
   }
   walkPayload(member?.payload, "member.payload", issues);
-  const selection = record(input.selection);
+  const selection = record2(input.selection);
   exactKeys(selection, ["limit", "orderBy", "membership"], "selection", issues);
   if (!selection || !Number.isSafeInteger(selection.limit) || Number(selection.limit) < 1 || Number(selection.limit) > MONITOR_FLEET_MAX_MEMBERS) {
     issues.push({
@@ -261,7 +455,7 @@ function validateMonitorFleetDefinition(value) {
   } else {
     const orderColumns = /* @__PURE__ */ new Set();
     for (const [index, order] of orderBy.entries()) {
-      const item = record(order);
+      const item = record2(order);
       exactKeys(
         item,
         ["column", "direction"],
@@ -284,7 +478,7 @@ function validateMonitorFleetDefinition(value) {
         orderColumns.add(item.column);
       }
     }
-    if (sourceKey && record(orderBy.at(-1))?.column !== sourceKey.column) {
+    if (sourceKey && record2(orderBy.at(-1))?.column !== sourceKey.column) {
       issues.push({
         path: "selection.orderBy",
         code: "fleet_order_missing_key",
@@ -303,9 +497,104 @@ function validateMonitorFleetDefinition(value) {
   }
   return issues.length === 0 ? { valid: true, definition: value, issues } : { valid: false, issues };
 }
-function admitMonitorFleetAuthoringContract(value, edition = MONITOR_FLEET_AUTHORING_CONTRACT_EDITION) {
+function v2Issue(issue) {
+  return { path: issue.path, code: issue.code, message: issue.message };
+}
+function validateMonitorFleetDefinitionV2(value) {
+  const issues = [];
+  const input = record2(value);
+  if (!input) {
+    return {
+      valid: false,
+      issues: [
+        {
+          path: "",
+          code: "invalid_fleet",
+          message: "Fleet must be an object."
+        }
+      ]
+    };
+  }
+  exactKeys(
+    input,
+    ["version", "kind", "id", "source", "monitor", "selection"],
+    "",
+    issues
+  );
+  if (input.version !== 2) {
+    issues.push({
+      path: "version",
+      code: "unsupported_fleet_version",
+      message: "Canonical Fleet input version must be 2."
+    });
+  }
+  if (input.kind !== "fleet") {
+    issues.push({
+      path: "kind",
+      code: "invalid_fleet_kind",
+      message: 'Canonical Fleet input kind must be "fleet".'
+    });
+  }
+  const source = record2(input.source);
+  const sourceKey = record2(source?.key);
+  const legacyShape = {
+    id: input.id,
+    source: input.source,
+    member: {
+      tool: record2(input.monitor)?.tool,
+      key: {
+        $fleet: "template",
+        parts: [
+          "fleet-",
+          {
+            $fleet: "column",
+            name: typeof sourceKey?.column === "string" ? sourceKey.column : "invalid_source_key"
+          }
+        ]
+      },
+      payload: record2(input.monitor)?.payload
+    },
+    selection: input.selection
+  };
+  const legacyCheck = validateMonitorFleetDefinitionV1(legacyShape);
+  for (const issue of legacyCheck.issues) {
+    issues.push({
+      ...issue,
+      path: issue.path.replace(/^member\./, "monitor.")
+    });
+  }
+  const monitorInput = record2(input.monitor);
+  const monitorKey = monitorInput?.key;
+  const monitor = lintMonitorSpecTemplate(input.monitor);
+  issues.push(...monitor.issues.map(v2Issue));
+  if (typeof monitorKey === "string" && typeof sourceKey?.column === "string" && !monitorKey.includes(`{{${sourceKey.column}}}`)) {
+    issues.push({
+      path: "monitor.key",
+      code: "fleet_key_missing_source_key",
+      message: "Monitor key must include the source key as a direct Handlebars expression."
+    });
+  }
+  return issues.length === 0 && monitor.normalized ? {
+    valid: true,
+    definition: {
+      version: 2,
+      kind: "fleet",
+      id: String(input.id),
+      source: input.source,
+      monitor: monitor.normalized,
+      selection: input.selection
+    },
+    issues
+  } : { valid: false, issues };
+}
+function validateMonitorFleetDefinition(value) {
+  const input = record2(value);
+  return input?.version === 2 || input?.kind === "fleet" ? validateMonitorFleetDefinitionV2(value) : validateMonitorFleetDefinitionV1(value);
+}
+function admitMonitorFleetAuthoringContract(value, edition) {
+  const detectedEdition = edition ?? (record2(value)?.version === 2 || record2(value)?.kind === "fleet" ? 2 : 1);
   if (!SUPPORTED_MONITOR_FLEET_AUTHORING_CONTRACT_EDITIONS.includes(
-    edition
+    detectedEdition
   )) {
     return {
       valid: false,
@@ -313,16 +602,16 @@ function admitMonitorFleetAuthoringContract(value, edition = MONITOR_FLEET_AUTHO
         {
           path: "authoring_contract_edition",
           code: "unsupported_fleet_authoring_contract_edition",
-          message: `Monitor Fleet authoring contract edition ${edition} is not supported.`
+          message: `Monitor Fleet authoring contract edition ${detectedEdition} is not supported.`
         }
       ]
     };
   }
-  const result = validateMonitorFleetDefinition(value);
+  const result = detectedEdition === 2 ? validateMonitorFleetDefinitionV2(value) : validateMonitorFleetDefinitionV1(value);
   return result.valid && result.definition ? {
     valid: true,
     contract: {
-      edition,
+      edition: detectedEdition,
       // JSON cloning prevents later caller mutation from changing the
       // admitted snapshot.
       definition: JSON.parse(
@@ -332,10 +621,36 @@ function admitMonitorFleetAuthoringContract(value, edition = MONITOR_FLEET_AUTHO
     issues: []
   } : { valid: false, issues: result.issues };
 }
+function lintMonitorFleetInput(value) {
+  const input = record2(value);
+  const legacy = input?.member !== void 0;
+  const admitted = admitMonitorFleetAuthoringContract(value);
+  const issues = admitted.issues.map((issue) => ({
+    ...issue,
+    severity: "error"
+  }));
+  if (legacy) {
+    issues.push({
+      severity: "warning",
+      code: "deprecated_fleet_member",
+      path: "member",
+      message: "Legacy Fleet member syntax remains supported."
+    });
+    if (JSON.stringify(input).includes('"$fleet"')) {
+      issues.push({
+        severity: "warning",
+        code: "deprecated_fleet_expression",
+        path: "member",
+        message: "Legacy $fleet expressions remain supported; use direct Handlebars fields in monitor instead."
+      });
+    }
+  }
+  return admitted.valid && admitted.contract ? { normalized: admitted.contract.definition, issues } : { issues };
+}
 function evaluateMonitorFleetValue(value, row) {
   if (Array.isArray(value))
     return value.map((item) => evaluateMonitorFleetValue(item, row));
-  const input = record(value);
+  const input = record2(value);
   if (!input) return value;
   if (input.$fleet === "column") return row[String(input.name)];
   if (input.$fleet === "template" && Array.isArray(input.parts)) {
@@ -363,5 +678,6 @@ export {
   evaluateMonitorFleetValue,
   fleetColumn,
   fleetKey,
+  lintMonitorFleetInput,
   validateMonitorFleetDefinition
 };

package/dist/monitor-input-contract.d.mts

@@ -0,0 +1,33 @@
+/// <reference path="./text-imports.d.ts" />
+type MonitorInputIssue = {
+    severity: 'error' | 'warning' | 'info';
+    code: string;
+    path: string;
+    message: string;
+    suggestion?: string;
+};
+type MonitorSpec = {
+    key: string;
+    tool: string;
+    name?: string;
+    payload: Record<string, unknown>;
+};
+type BatchMonitorInput = {
+    version: 1;
+    kind: 'batch';
+    monitors: MonitorSpec[];
+};
+declare function lintMonitorBatchInput(value: unknown): {
+    normalized?: BatchMonitorInput;
+    issues: MonitorInputIssue[];
+};
+declare function lintMonitorSpecTemplate(value: unknown, path?: string): {
+    normalized?: MonitorSpec;
+    issues: MonitorInputIssue[];
+};
+declare function renderMonitorSpecTemplate(template: MonitorSpec, row: Record<string, unknown>): {
+    spec?: MonitorSpec;
+    issues: MonitorInputIssue[];
+};
+
+export { type BatchMonitorInput, type MonitorInputIssue, type MonitorSpec, lintMonitorBatchInput, lintMonitorSpecTemplate, renderMonitorSpecTemplate };

package/dist/monitor-input-contract.d.ts

@@ -0,0 +1,33 @@
+/// <reference path="./text-imports.d.ts" />
+type MonitorInputIssue = {
+    severity: 'error' | 'warning' | 'info';
+    code: string;
+    path: string;
+    message: string;
+    suggestion?: string;
+};
+type MonitorSpec = {
+    key: string;
+    tool: string;
+    name?: string;
+    payload: Record<string, unknown>;
+};
+type BatchMonitorInput = {
+    version: 1;
+    kind: 'batch';
+    monitors: MonitorSpec[];
+};
+declare function lintMonitorBatchInput(value: unknown): {
+    normalized?: BatchMonitorInput;
+    issues: MonitorInputIssue[];
+};
+declare function lintMonitorSpecTemplate(value: unknown, path?: string): {
+    normalized?: MonitorSpec;
+    issues: MonitorInputIssue[];
+};
+declare function renderMonitorSpecTemplate(template: MonitorSpec, row: Record<string, unknown>): {
+    spec?: MonitorSpec;
+    issues: MonitorInputIssue[];
+};
+
+export { type BatchMonitorInput, type MonitorInputIssue, type MonitorSpec, lintMonitorBatchInput, lintMonitorSpecTemplate, renderMonitorSpecTemplate };