deepline 0.3.294 → 0.3.295

package/dist/cli/chunk-HUZXWOSK.mjs

@@ -0,0 +1,503 @@
+import {
+  lintMonitorSpecTemplate
+} from "./chunk-TAC3JIFE.mjs";
+
+// ../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 = 2;
+var SUPPORTED_MONITOR_FLEET_AUTHORING_CONTRACT_EDITIONS = [
+  1,
+  2
+];
+var MONITOR_FLEET_AUTHORING_CONTRACT_CHANGELOG = [
+  {
+    edition: 1,
+    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
+  }
+];
+var MONITOR_FLEET_REMOVAL_GRACE_MS = 7 * 24 * 60 * 6e4;
+var MONITOR_FLEET_DOCUMENTATION = {
+  summary: "A Monitor Fleet keeps one bounded, sticky set of ordinary monitors aligned with Customer DB rows.",
+  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.",
+    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: "60s fair bounded source refresh",
+    membership: "sticky",
+    removalGrace: "7d",
+    onRemoved: "deactivate",
+    ownership: "A Fleet may adopt a same-tool ordinary monitor with its deterministic member key. The first Fleet claim wins; another Fleet or a different tool receives a conflict.",
+    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.",
+  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) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+function identifier(value) {
+  return typeof value === "string" && /^[A-Za-z_][A-Za-z0-9_]*$/.test(value);
+}
+function exactKeys(input, keys, path, issues) {
+  if (!input) return;
+  for (const key of Object.keys(input)) {
+    if (keys.includes(key)) continue;
+    issues.push({
+      path: path ? `${path}.${key}` : key,
+      code: "unknown_fleet_field",
+      message: `${path || "Fleet"} does not accept '${key}'.`
+    });
+  }
+}
+function jsonValue(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((item, index) => jsonValue(item, `${path}.${index}`, issues));
+    return;
+  }
+  const input = record(value);
+  if (!input) {
+    issues.push({
+      path,
+      code: "invalid_fleet_json_value",
+      message: "Fleet payload values must be JSON values."
+    });
+    return;
+  }
+  for (const [key, item] of Object.entries(input)) {
+    jsonValue(item, `${path}.${key}`, issues);
+  }
+}
+function fleetColumn(name) {
+  if (!identifier(name)) throw new Error(`Invalid fleet column '${name}'.`);
+  return { $fleet: "column", name };
+}
+function fleetKey(...parts) {
+  if (parts.length === 0)
+    throw new Error("A fleet key needs at least one part.");
+  return { $fleet: "template", parts };
+}
+function defineMonitorFleet(definition) {
+  return definition;
+}
+function validateExpression(value, path, issues) {
+  const input = record(value);
+  if (!input || input.$fleet !== "column" || !identifier(input.name)) {
+    issues.push({
+      path,
+      code: "invalid_fleet_expression",
+      message: "Fleet expressions must be an exact tagged column reference."
+    });
+    return;
+  }
+  exactKeys(input, ["$fleet", "name"], path, issues);
+}
+function walkPayload(value, path, issues) {
+  if (Array.isArray(value)) {
+    value.forEach(
+      (item, index) => walkPayload(item, `${path}.${index}`, issues)
+    );
+    return;
+  }
+  const input = record(value);
+  if (!input) return;
+  if ("$fleet" in input) {
+    validateExpression(input, path, issues);
+    return;
+  }
+  for (const [key, item] of Object.entries(input)) {
+    walkPayload(item, `${path}.${key}`, issues);
+  }
+}
+function validateMonitorFleetDefinitionV1(value) {
+  const issues = [];
+  const input = record(value);
+  if (!input) {
+    return {
+      valid: false,
+      issues: [
+        {
+          path: "",
+          code: "invalid_fleet",
+          message: "Fleet must be an object."
+        }
+      ]
+    };
+  }
+  exactKeys(input, ["id", "source", "member", "selection"], "", issues);
+  if (typeof input.id !== "string" || !/^[a-z][a-z0-9-]{0,199}$/.test(input.id)) {
+    issues.push({
+      path: "id",
+      code: "invalid_fleet_id",
+      message: "Fleet id must be lowercase kebab-case."
+    });
+  }
+  const source = record(input.source);
+  exactKeys(
+    source,
+    ["kind", "schema", "table", "key", "where"],
+    "source",
+    issues
+  );
+  if (!source || source.kind !== "customer_db_table") {
+    issues.push({
+      path: "source.kind",
+      code: "invalid_fleet_source",
+      message: "Beta fleets require customer_db_table."
+    });
+  }
+  if (!identifier(source?.schema) || !identifier(source?.table)) {
+    issues.push({
+      path: "source",
+      code: "invalid_fleet_table",
+      message: "Source schema and table must be SQL identifiers."
+    });
+  }
+  const sourceKey = record(source?.key);
+  exactKeys(sourceKey, ["column", "type"], "source.key", issues);
+  if (!sourceKey || !identifier(sourceKey.column) || !["text", "uuid", "int4", "int8"].includes(String(sourceKey.type))) {
+    issues.push({
+      path: "source.key",
+      code: "invalid_fleet_source_key",
+      message: "Source key must name a supported typed column."
+    });
+  }
+  if (source?.where !== void 0) {
+    const where = record(source.where);
+    if (!where) {
+      issues.push({
+        path: "source.where",
+        code: "invalid_fleet_where",
+        message: "source.where must be an object of equality values."
+      });
+    } else {
+      for (const [column, expected] of Object.entries(where)) {
+        if (!identifier(column)) {
+          issues.push({
+            path: `source.where.${column}`,
+            code: "invalid_fleet_where_column",
+            message: "source.where keys must be SQL identifiers."
+          });
+        }
+        if (expected !== null && typeof expected !== "string" && typeof expected !== "boolean" && !(typeof expected === "number" && Number.isFinite(expected))) {
+          issues.push({
+            path: `source.where.${column}`,
+            code: "invalid_fleet_where_value",
+            message: "source.where values must be finite JSON scalars or null."
+          });
+        }
+      }
+    }
+  }
+  const member = record(input.member);
+  exactKeys(member, ["tool", "key", "payload"], "member", issues);
+  const key = record(member?.key);
+  if (!member || typeof member.tool !== "string" || !member.tool.trim()) {
+    issues.push({
+      path: "member.tool",
+      code: "invalid_fleet_tool",
+      message: "Member tool is required."
+    });
+  }
+  if (!key || key.$fleet !== "template" || !Array.isArray(key.parts) || key.parts.length === 0) {
+    issues.push({
+      path: "member.key",
+      code: "invalid_fleet_key",
+      message: "Member key must be a tagged fleet template."
+    });
+  } else {
+    exactKeys(key, ["$fleet", "parts"], "member.key", issues);
+    for (const [index, part] of key.parts.entries()) {
+      if (typeof part !== "string")
+        validateExpression(part, `member.key.parts.${index}`, issues);
+    }
+    if (sourceKey && !key.parts.some(
+      (part) => record(part)?.$fleet === "column" && record(part)?.name === sourceKey.column
+    )) {
+      issues.push({
+        path: "member.key.parts",
+        code: "fleet_key_missing_source_key",
+        message: "Member key must include the source key column."
+      });
+    }
+  }
+  if (!member || !("payload" in member)) {
+    issues.push({
+      path: "member.payload",
+      code: "invalid_fleet_payload",
+      message: "Member payload is required."
+    });
+  } else {
+    jsonValue(member.payload, "member.payload", issues);
+  }
+  walkPayload(member?.payload, "member.payload", issues);
+  const selection = record(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({
+      path: "selection.limit",
+      code: "MONITOR_FLEET_LIMIT_EXCEEDED",
+      message: "selection.limit must be between 1 and 1,000."
+    });
+  }
+  if (selection?.membership !== "sticky") {
+    issues.push({
+      path: "selection.membership",
+      code: "invalid_fleet_membership",
+      message: `Fleet membership is fixed to ${MONITOR_FLEET_DOCUMENTATION.fixedPolicy.membership}. ${MONITOR_FLEET_DOCUMENTATION.stickyMembership}`
+    });
+  }
+  const orderBy = selection?.orderBy;
+  if (!Array.isArray(orderBy) || orderBy.length === 0) {
+    issues.push({
+      path: "selection.orderBy",
+      code: "invalid_fleet_order",
+      message: "At least one deterministic order field is required."
+    });
+  } else {
+    const orderColumns = /* @__PURE__ */ new Set();
+    for (const [index, order] of orderBy.entries()) {
+      const item = record(order);
+      exactKeys(
+        item,
+        ["column", "direction"],
+        `selection.orderBy.${index}`,
+        issues
+      );
+      if (!item || !identifier(item.column) || !["asc", "desc"].includes(String(item.direction))) {
+        issues.push({
+          path: `selection.orderBy.${index}`,
+          code: "invalid_fleet_order",
+          message: "Order fields need a column and asc/desc direction."
+        });
+      } else if (orderColumns.has(item.column)) {
+        issues.push({
+          path: `selection.orderBy.${index}.column`,
+          code: "duplicate_fleet_order_column",
+          message: "Each selection order column may appear only once."
+        });
+      } else {
+        orderColumns.add(item.column);
+      }
+    }
+    if (sourceKey && record(orderBy.at(-1))?.column !== sourceKey.column) {
+      issues.push({
+        path: "selection.orderBy",
+        code: "fleet_order_missing_key",
+        message: "The final order field must be the source key."
+      });
+    }
+  }
+  for (const removedOption of ["spendLimits", "lifecycle", "reconciliation"]) {
+    if (removedOption in input) {
+      issues.push({
+        path: removedOption,
+        code: "unsupported_fleet_option",
+        message: `${removedOption} is fixed by Monitor Fleets and must be omitted. Fleets sync ${MONITOR_FLEET_DOCUMENTATION.fixedPolicy.cadence} and ${MONITOR_FLEET_DOCUMENTATION.fixedPolicy.onRemoved} members after ${MONITOR_FLEET_DOCUMENTATION.fixedPolicy.removalGrace} absent from the source.`
+      });
+    }
+  }
+  return issues.length === 0 ? { valid: true, definition: value, issues } : { valid: false, issues };
+}
+function v2Issue(issue) {
+  return { path: issue.path, code: issue.code, message: issue.message };
+}
+function validateMonitorFleetDefinitionV2(value) {
+  const issues = [];
+  const input = record(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 = record(input.source);
+  const sourceKey = record(source?.key);
+  const legacyShape = {
+    id: input.id,
+    source: input.source,
+    member: {
+      tool: record(input.monitor)?.tool,
+      key: {
+        $fleet: "template",
+        parts: [
+          "fleet-",
+          {
+            $fleet: "column",
+            name: typeof sourceKey?.column === "string" ? sourceKey.column : "invalid_source_key"
+          }
+        ]
+      },
+      payload: record(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 = record(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 = record(value);
+  return input?.version === 2 || input?.kind === "fleet" ? validateMonitorFleetDefinitionV2(value) : validateMonitorFleetDefinitionV1(value);
+}
+function admitMonitorFleetAuthoringContract(value, edition) {
+  const detectedEdition = edition ?? (record(value)?.version === 2 || record(value)?.kind === "fleet" ? 2 : 1);
+  if (!SUPPORTED_MONITOR_FLEET_AUTHORING_CONTRACT_EDITIONS.includes(
+    detectedEdition
+  )) {
+    return {
+      valid: false,
+      issues: [
+        {
+          path: "authoring_contract_edition",
+          code: "unsupported_fleet_authoring_contract_edition",
+          message: `Monitor Fleet authoring contract edition ${detectedEdition} is not supported.`
+        }
+      ]
+    };
+  }
+  const result = detectedEdition === 2 ? validateMonitorFleetDefinitionV2(value) : validateMonitorFleetDefinitionV1(value);
+  return result.valid && result.definition ? {
+    valid: true,
+    contract: {
+      edition: detectedEdition,
+      // JSON cloning prevents later caller mutation from changing the
+      // admitted snapshot.
+      definition: JSON.parse(
+        JSON.stringify(result.definition)
+      )
+    },
+    issues: []
+  } : { valid: false, issues: result.issues };
+}
+function lintMonitorFleetInput(value) {
+  const input = record(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);
+  if (!input) return value;
+  if (input.$fleet === "column") return row[String(input.name)];
+  if (input.$fleet === "template" && Array.isArray(input.parts)) {
+    return input.parts.map(
+      (part) => typeof part === "string" ? part : String(evaluateMonitorFleetValue(part, row) ?? "")
+    ).join("");
+  }
+  return Object.fromEntries(
+    Object.entries(input).map(([key, item]) => [
+      key,
+      evaluateMonitorFleetValue(item, row)
+    ])
+  );
+}
+
+export {
+  MONITOR_FLEET_MAX_MEMBERS,
+  MONITOR_FLEET_FRONTIER_MAX_ROWS,
+  MONITOR_FLEET_AUTHORING_CONTRACT_EDITION,
+  SUPPORTED_MONITOR_FLEET_AUTHORING_CONTRACT_EDITIONS,
+  MONITOR_FLEET_AUTHORING_CONTRACT_CHANGELOG,
+  MONITOR_FLEET_REMOVAL_GRACE_MS,
+  MONITOR_FLEET_DOCUMENTATION,
+  fleetColumn,
+  fleetKey,
+  defineMonitorFleet,
+  validateMonitorFleetDefinition,
+  admitMonitorFleetAuthoringContract,
+  lintMonitorFleetInput,
+  evaluateMonitorFleetValue
+};

package/dist/cli/chunk-I5YZLGMG.js

@@ -0,0 +1 @@
+"use strict";

package/dist/cli/chunk-ITOFSXIU.mjs

@@ -0,0 +1,15 @@
+// ../plays/enrich-compat-adapter.ts
+var ENRICH_COMPAT_DEFAULT_PLAY_NAME = "deepline-enrich-v1-compat";
+var ENRICH_COMPAT_DEFAULT_MAP_NAME = "deepline_enrich_rows";
+var ENRICH_COMMAND_DEPRECATION_MESSAGE = "The `deepline enrich` command is deprecated. Deepline Plays gives much better results. Run `deepline plays --help` to get started. If you still need the legacy command, submit feedback explaining why.";
+function buildEnrichCompatibilityPlan(options = {}) {
+  return {
+    playName: options.playName?.trim() || ENRICH_COMPAT_DEFAULT_PLAY_NAME,
+    mapName: options.mapName?.trim() || ENRICH_COMPAT_DEFAULT_MAP_NAME
+  };
+}
+
+export {
+  ENRICH_COMMAND_DEPRECATION_MESSAGE,
+  buildEnrichCompatibilityPlan
+};