@walkeros/cli 4.8.1-next-1791586788897 → 4.8.1

package/dist/validate.js

@@ -0,0 +1,2077 @@
+// src/commands/validate/index.ts
+import * as fs9 from "fs";
+import * as path3 from "path";
+import chalk2 from "chalk";
+import { isObject as isObject7 } from "@walkeros/core";
+
+// src/core/cli-logger.ts
+import chalk from "chalk";
+import {
+  createCLILogger as createCoreCLILogger,
+  createCLILoggerConfig as createCoreCLILoggerConfig
+} from "@walkeros/core/node";
+var CLI_COLORS = { error: chalk.red };
+
+// src/core/timer.ts
+import { createTimer } from "@walkeros/core";
+
+// src/core/output.ts
+import fs from "fs-extra";
+
+// src/core/tmp.ts
+import {
+  getTmpPath,
+  createTmpResolver,
+  getDefaultTmpRoot
+} from "@walkeros/core/node";
+
+// src/config/utils.ts
+import fs2 from "fs-extra";
+import path from "path";
+
+// src/core/fetch-failure.ts
+function isRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function fetchFailureReason(error, timeoutMs) {
+  if (!isRecord(error)) return String(error);
+  if (error.name === "TimeoutError")
+    return timeoutMs === void 0 ? "timeout" : `timeout after ${timeoutMs} ms`;
+  const message = typeof error.message === "string" ? error.message : String(error);
+  const cause = error.cause;
+  const code = isRecord(cause) && typeof cause.code === "string" ? cause.code : void 0;
+  return code ? `${message} (${code})` : message;
+}
+
+// src/config/utils.ts
+function isUrl(str) {
+  try {
+    const url = new URL(str);
+    return url.protocol === "http:" || url.protocol === "https:";
+  } catch {
+    return false;
+  }
+}
+var ConfigFetchError = class extends Error {
+  url;
+  /** The HTTP status, when the host answered. */
+  status;
+  constructor(message, url, status) {
+    super(message);
+    this.name = "ConfigFetchError";
+    this.url = url;
+    this.status = status;
+  }
+};
+async function fetchContentString(url) {
+  let response;
+  try {
+    response = await fetch(url);
+  } catch (error) {
+    throw new ConfigFetchError(
+      `Could not reach ${url}: ${fetchFailureReason(error)}`,
+      url
+    );
+  }
+  if (!response.ok) {
+    throw new ConfigFetchError(
+      `Failed to fetch ${url}: ${response.status} ${response.statusText}`.trimEnd(),
+      url,
+      response.status
+    );
+  }
+  return response.text();
+}
+async function resolveContent(input) {
+  const trimmed = input.trim();
+  if (isUrl(trimmed)) {
+    return fetchContentString(trimmed);
+  }
+  const absolutePath = path.resolve(trimmed);
+  if (await fs2.pathExists(absolutePath)) {
+    return fs2.readFile(absolutePath, "utf-8");
+  }
+  if (trimmed.startsWith("{") || trimmed.startsWith("[")) {
+    return trimmed;
+  }
+  throw new Error(`Configuration file not found: ${absolutePath}`);
+}
+async function loadConfig(input, options) {
+  const json = options?.json !== false;
+  if (!json) {
+    return resolveContent(input);
+  }
+  const trimmed = input.trim();
+  try {
+    const content = await resolveContent(trimmed);
+    return JSON.parse(content);
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    if (error instanceof ConfigFetchError || errorMessage.includes("not found"))
+      throw error;
+    if (trimmed.startsWith("{") || trimmed.startsWith("[")) {
+      throw new Error(
+        `Input appears to be JSON but contains errors: ${errorMessage}`
+      );
+    }
+    throw new Error(`Invalid JSON in config file: ${input}. ${errorMessage}`);
+  }
+}
+async function loadJsonConfig(configPath) {
+  return loadConfig(configPath, { json: true });
+}
+
+// src/core/utils.ts
+import { getErrorMessage } from "@walkeros/core";
+
+// src/core/local-packages.ts
+import fs3 from "fs-extra";
+
+// src/core/input-detector.ts
+import fs4 from "fs-extra";
+
+// src/core/stdin.ts
+import fs5 from "fs-extra";
+
+// src/core/oauth-client.ts
+import { z as z2 } from "zod";
+
+// src/core/app-fetch.ts
+import { z } from "zod";
+var AppErrorSchema = z.object({
+  error: z.object({ message: z.string().min(1) })
+});
+
+// src/core/oauth-client.ts
+var DeviceAuthorizationSchema = z2.object({
+  device_code: z2.string().min(1),
+  user_code: z2.string().min(1),
+  verification_uri: z2.string().min(1),
+  verification_uri_complete: z2.string().min(1).optional(),
+  expires_in: z2.number().int().nonnegative(),
+  interval: z2.number().int().nonnegative()
+});
+var TokenSchema = z2.object({
+  access_token: z2.string().min(1),
+  expires_in: z2.number().int().nonnegative(),
+  refresh_token: z2.string().min(1).optional()
+});
+var ErrorSchema = z2.object({
+  error: z2.string().min(1),
+  error_description: z2.string().optional()
+});
+
+// src/core/event-validation.ts
+import { schemas } from "@walkeros/core/dev";
+var { PartialEventSchema } = schemas;
+function validateEvent(input, level = "strict") {
+  const errors = [];
+  const warnings = [];
+  const details = {};
+  if (typeof input !== "object" || input === null || Array.isArray(input)) {
+    errors.push({
+      path: "root",
+      message: "Event must be an object",
+      code: "NOT_AN_OBJECT"
+    });
+    return { valid: false, errors, warnings, details };
+  }
+  const event = input;
+  if (!("name" in event) || event.name === void 0) {
+    errors.push({
+      path: "name",
+      message: "Event must have a name field",
+      code: "MISSING_EVENT_NAME"
+    });
+  } else if (typeof event.name !== "string" || event.name.trim() === "") {
+    errors.push({
+      path: "name",
+      message: "Event name cannot be empty",
+      value: event.name,
+      code: "EMPTY_EVENT_NAME"
+    });
+  } else {
+    const name = event.name;
+    if (!name.includes(" ")) {
+      if (level === "strict") {
+        errors.push({
+          path: "name",
+          message: 'Event name must be "entity action" format with space (e.g., "page view")',
+          value: name,
+          code: "INVALID_EVENT_NAME"
+        });
+        details.entity = null;
+        details.action = null;
+      } else if (level === "standard") {
+        warnings.push({
+          path: "name",
+          message: `Event name "${name}" should follow "ENTITY ACTION" format (e.g., "page view")`
+        });
+        details.entity = null;
+        details.action = null;
+      }
+    } else {
+      const parts = name.trim().split(/\s+/);
+      const action = parts.pop();
+      const entity = parts.join(" ");
+      details.entity = entity;
+      details.action = action;
+    }
+  }
+  if (level === "minimal") {
+    return { valid: errors.length === 0, errors, warnings, details };
+  }
+  const zodResult = PartialEventSchema.safeParse(input);
+  if (!zodResult.success) {
+    for (const issue of zodResult.error.issues) {
+      const issuePath = issue.path.join(".");
+      if (issuePath === "name") continue;
+      errors.push({
+        path: issuePath || "root",
+        message: issue.message,
+        code: "SCHEMA_VALIDATION"
+      });
+    }
+  }
+  if (level === "strict") {
+    if (!event.consent) {
+      warnings.push({
+        path: "consent",
+        message: "No consent object provided",
+        suggestion: "Consider adding a consent object for GDPR/privacy compliance"
+      });
+    }
+    details.hasConsent = !!event.consent;
+    details.hasData = !!event.data;
+    details.hasContext = !!event.context;
+  }
+  return { valid: errors.length === 0, errors, warnings, details };
+}
+
+// src/config/validators.ts
+import { isObject } from "@walkeros/core";
+import { schemas as schemas2 } from "@walkeros/core/dev";
+var { safeParseConfig } = schemas2;
+
+// src/config/loader.ts
+import fs7 from "fs-extra";
+import { getFlowSettings, getPlatform } from "@walkeros/core";
+
+// src/core/content-digest.ts
+import { createHash } from "crypto";
+import fs6 from "fs-extra";
+
+// src/config/window-collector.ts
+import { checkWindowCollector } from "@walkeros/core";
+
+// src/commands/validate/validators/contract.ts
+import { isObject as isObject2 } from "@walkeros/core";
+var SECTION_KEYS = ["globals", "context", "custom", "user", "consent"];
+var KNOWN_KEYS = /* @__PURE__ */ new Set([
+  "extend",
+  "tagging",
+  "description",
+  "events",
+  "schema",
+  ...SECTION_KEYS
+]);
+function validateContract(input) {
+  const errors = [];
+  const warnings = [];
+  const details = {};
+  if (typeof input !== "object" || input === null || Array.isArray(input)) {
+    errors.push({
+      path: "root",
+      message: "Contract must be an object of named contract entries",
+      code: "INVALID_CONTRACT"
+    });
+    return { valid: false, type: "contract", errors, warnings, details };
+  }
+  const contracts = input;
+  const contractNames = Object.keys(contracts);
+  details.contractCount = contractNames.length;
+  for (const name of contractNames) {
+    if (name.startsWith("$")) {
+      errors.push({
+        path: name,
+        message: `"${name}" is not a named contract entry. This looks like the flat shape; use named ContractRule entries, lift $tagging to the rule field "tagging", and nest entity-action schemas under "events".`,
+        code: "FLAT_CONTRACT_SHAPE"
+      });
+    }
+  }
+  for (const [name, entry] of Object.entries(contracts)) {
+    if (name.startsWith("$")) {
+      continue;
+    }
+    if (typeof entry !== "object" || entry === null) {
+      errors.push({
+        path: name,
+        message: `Contract "${name}" must be an object`,
+        code: "INVALID_CONTRACT_ENTRY"
+      });
+      continue;
+    }
+    const obj = entry;
+    const keys = Object.keys(obj);
+    const unknownKeys = keys.filter((k) => !KNOWN_KEYS.has(k));
+    const hasKnownKey = keys.some((k) => KNOWN_KEYS.has(k));
+    const objectValuedUnknown = unknownKeys.filter((k) => isObject2(obj[k]));
+    if (!hasKnownKey && objectValuedUnknown.length > 0) {
+      errors.push({
+        path: name,
+        message: `Contract "${name}" looks like a flat entity-action map. Nest entity-action schemas under an "events" key of a named ContractRule.`,
+        code: "FLAT_CONTRACT_SHAPE"
+      });
+      continue;
+    }
+    for (const key of unknownKeys) {
+      warnings.push({
+        path: `${name}.${key}`,
+        message: `Unknown contract key "${key}" is ignored`,
+        code: "UNKNOWN_CONTRACT_KEY"
+      });
+    }
+    if (obj.tagging !== void 0 && typeof obj.tagging !== "number") {
+      errors.push({
+        path: `${name}.tagging`,
+        message: "tagging must be a number",
+        code: "INVALID_TAGGING"
+      });
+    }
+    if (obj.schema !== void 0 && !isObject2(obj.schema)) {
+      errors.push({
+        path: `${name}.schema`,
+        message: "schema must be a JSON Schema object",
+        code: "INVALID_SCHEMA"
+      });
+    }
+    if (obj.extend !== void 0) {
+      if (typeof obj.extend !== "string") {
+        errors.push({
+          path: `${name}.extend`,
+          message: "extend must be a string",
+          code: "INVALID_EXTENDS"
+        });
+      } else if (!contractNames.includes(obj.extend)) {
+        errors.push({
+          path: `${name}.extend`,
+          message: `extend references non-existent contract "${obj.extend}"`,
+          value: obj.extend,
+          code: "INVALID_EXTENDS"
+        });
+      }
+    }
+    for (const key of SECTION_KEYS) {
+      if (key in obj) {
+        if (typeof obj[key] !== "object" || obj[key] === null) {
+          errors.push({
+            path: `${name}.${key}`,
+            message: `Section "${key}" must be a JSON Schema object`,
+            value: obj[key],
+            code: "INVALID_SECTION"
+          });
+        }
+      }
+    }
+    if (obj.events !== void 0) {
+      if (typeof obj.events !== "object" || obj.events === null) {
+        errors.push({
+          path: `${name}.events`,
+          message: "events must be an object",
+          code: "INVALID_EVENTS"
+        });
+      } else {
+        validateEntityActions(
+          obj.events,
+          `${name}.events`,
+          errors
+        );
+      }
+    }
+  }
+  const reportedCycles = /* @__PURE__ */ new Set();
+  for (const name of contractNames) {
+    const chain = [];
+    let current = name;
+    while (current) {
+      const start = chain.indexOf(current);
+      if (start !== -1) {
+        const cycle = chain.slice(start);
+        const key = [...cycle].sort().join("\0");
+        if (!reportedCycles.has(key)) {
+          reportedCycles.add(key);
+          errors.push({
+            path: `${cycle[0]}.extend`,
+            message: `Circular extend chain: ${[...cycle, current].join(" \u2192 ")}`,
+            code: "CIRCULAR_EXTENDS"
+          });
+        }
+        break;
+      }
+      chain.push(current);
+      const entry = contracts[current];
+      current = isObject2(entry) && typeof entry.extend === "string" ? entry.extend : "";
+    }
+  }
+  return {
+    valid: errors.length === 0,
+    type: "contract",
+    errors,
+    warnings,
+    details
+  };
+}
+function validateEntityActions(obj, prefix, errors) {
+  for (const [entityKey, entityValue] of Object.entries(obj)) {
+    if (entityKey.trim() === "") {
+      errors.push({
+        path: `${prefix}.${entityKey}`,
+        message: "Entity key cannot be empty",
+        code: "INVALID_ENTITY_KEY"
+      });
+      continue;
+    }
+    if (typeof entityValue !== "object" || entityValue === null) {
+      errors.push({
+        path: `${prefix}.${entityKey}`,
+        message: `Entity "${entityKey}" must be an object`,
+        value: entityValue,
+        code: "INVALID_ENTITY"
+      });
+      continue;
+    }
+    for (const [actionKey, actionValue] of Object.entries(
+      entityValue
+    )) {
+      if (actionKey.trim() === "") {
+        errors.push({
+          path: `${prefix}.${entityKey}.${actionKey}`,
+          message: "Action key cannot be empty",
+          code: "INVALID_ACTION_KEY"
+        });
+        continue;
+      }
+      if (typeof actionValue !== "object" || actionValue === null || Array.isArray(actionValue)) {
+        errors.push({
+          path: `${prefix}.${entityKey}.${actionKey}`,
+          message: "Contract entry must be a JSON Schema object",
+          value: typeof actionValue,
+          code: "INVALID_SCHEMA_ENTRY"
+        });
+      }
+    }
+  }
+}
+
+// src/commands/validate/validators/event.ts
+function validateEvent2(input) {
+  const result = validateEvent(input, "strict");
+  return {
+    valid: result.valid,
+    type: "event",
+    errors: result.errors,
+    warnings: result.warnings,
+    details: result.details
+  };
+}
+
+// src/commands/validate/validators/flow.ts
+import {
+  checkWindowCollector as checkWindowCollector2,
+  ENV_MARKER_PREFIX as ENV_MARKER_PREFIX2,
+  getByPath,
+  getRouteGraph,
+  isObject as isObject5,
+  REF_CONTRACT,
+  resolveContracts,
+  validateStepEntry
+} from "@walkeros/core";
+import { schemas as schemas3, validateFlowStructure } from "@walkeros/core/dev";
+import {
+  validateEventAgainstContract
+} from "@walkeros/transformer-validate";
+
+// src/commands/validate/scope.ts
+import { isObject as isObject3 } from "@walkeros/core";
+function isFlowJson(value) {
+  return isObject3(value) && "version" in value && isObject3(value.flows);
+}
+var ENTRY_SECTIONS = [
+  "sources",
+  "destinations",
+  "transformers",
+  "stores"
+];
+function isEntrySection(value) {
+  return ENTRY_SECTIONS.some((section) => section === value);
+}
+function resolveScope(config, options = {}) {
+  const flowsValue = isObject3(config) ? config.flows : void 0;
+  const flowMap = isObject3(flowsValue) ? flowsValue : {};
+  const allFlows = Object.keys(flowMap);
+  let flows = allFlows;
+  if (options.flow !== void 0) {
+    if (!allFlows.includes(options.flow)) {
+      return {
+        allFlows,
+        flows: [],
+        entries: [],
+        searchedFlows: [],
+        errors: [
+          {
+            path: "flows",
+            message: `Flow "${options.flow}" not found. Available: ${allFlows.join(", ") || "none"}`,
+            code: "FLOW_NOT_FOUND"
+          }
+        ]
+      };
+    }
+    flows = [options.flow];
+  }
+  const path4 = options.path;
+  if (path4 === void 0) {
+    return { allFlows, flows, entries: [], searchedFlows: [], errors: [] };
+  }
+  const parts = path4.split(".");
+  let sections = ENTRY_SECTIONS;
+  let section;
+  let key;
+  if (parts.length === 2 && parts[0] !== "" && parts[1] !== "") {
+    if (!isEntrySection(parts[0])) {
+      return {
+        allFlows,
+        flows,
+        entries: [],
+        searchedFlows: [],
+        errors: [
+          {
+            path: path4,
+            message: `Section "${parts[0]}" cannot be addressed by --path. Use one of: ${ENTRY_SECTIONS.join(", ")}`,
+            code: "UNSUPPORTED_SECTION"
+          }
+        ]
+      };
+    }
+    section = parts[0];
+    sections = [section];
+    key = parts[1];
+  } else if (parts.length === 1 && parts[0] !== "") {
+    key = parts[0];
+  } else {
+    return {
+      allFlows,
+      flows,
+      entries: [],
+      searchedFlows: [],
+      errors: [
+        {
+          path: path4,
+          message: `Invalid path "${path4}". Use "section.key" or just "key"`,
+          code: "INVALID_PATH"
+        }
+      ]
+    };
+  }
+  const entries = [];
+  for (const flow of flows) {
+    const flowValue = flowMap[flow];
+    if (!isObject3(flowValue)) continue;
+    for (const candidate of sections) {
+      const sectionValue = flowValue[candidate];
+      if (!isObject3(sectionValue)) continue;
+      const entry = sectionValue[key];
+      if (isObject3(entry))
+        entries.push({ flow, section: candidate, key, entry });
+    }
+  }
+  const matched = [...new Set(entries.map((entry) => entry.section))];
+  if (matched.length > 1) {
+    return {
+      allFlows,
+      flows,
+      entries: [],
+      searchedFlows: flows,
+      target: { key },
+      errors: [
+        {
+          path: path4,
+          message: `Ambiguous key "${key}" found in multiple sections: ${matched.join(", ")}. Use dot-notation (e.g., ${matched[0]}.${key})`,
+          code: "AMBIGUOUS_ENTRY"
+        }
+      ]
+    };
+  }
+  const target = { section: section ?? matched[0], key };
+  if (entries.length === 0) {
+    return {
+      allFlows,
+      flows,
+      entries,
+      searchedFlows: flows,
+      target,
+      errors: [
+        {
+          path: path4,
+          message: `Entry "${key}" not found in ${section ?? "any section"} of flow(s): ${flows.join(", ") || "none"}`,
+          code: "ENTRY_NOT_FOUND"
+        }
+      ]
+    };
+  }
+  return {
+    allFlows,
+    flows,
+    entries,
+    searchedFlows: flows,
+    target,
+    errors: []
+  };
+}
+function flowOfPath(path4, flowNames) {
+  return flowNames.find(
+    (name) => path4 === `flows.${name}` || path4.startsWith(`flows.${name}.`)
+  );
+}
+function describeScope(resolved, checks) {
+  const scope = { flows: resolved.flows, checks };
+  if (resolved.target) {
+    const { section, key } = resolved.target;
+    scope.entry = {
+      ...section ? { section } : {},
+      key,
+      flows: [...new Set(resolved.entries.map((entry) => entry.flow))],
+      searchedFlows: resolved.searchedFlows
+    };
+  }
+  return scope;
+}
+
+// src/commands/validate/validators/resolve.ts
+import {
+  FlowCycleError,
+  FlowReferenceError,
+  getFlowSettings as getFlowSettings2,
+  getErrorMessage as getErrorMessage2
+} from "@walkeros/core";
+function resolveFlow(file, name) {
+  try {
+    const flow = getFlowSettings2(file, name, { deferred: true });
+    return { ok: true, flow };
+  } catch (error) {
+    return {
+      ok: false,
+      error: {
+        path: `flows.${name}`,
+        message: getErrorMessage2(error),
+        code: resolutionCode(error)
+      }
+    };
+  }
+}
+function resolutionCode(error) {
+  if (error instanceof FlowReferenceError) return error.code;
+  if (error instanceof FlowCycleError) return error.code;
+  return "UNRESOLVED_REFERENCE";
+}
+
+// src/commands/validate/validators/settings.ts
+import * as fs8 from "fs";
+import * as path2 from "path";
+import Ajv from "ajv";
+import {
+  ENV_MARKER_PREFIX,
+  fetchPackage,
+  getErrorMessage as getErrorMessage3,
+  isObject as isObject4,
+  REF_CODE_PREFIX,
+  REF_STORE,
+  SECRET_MARKER_PREFIX
+} from "@walkeros/core";
+
+// src/core/resolve-export-name.ts
+function getStep(flow, kind, id) {
+  switch (kind) {
+    case "source":
+      return flow.sources?.[id];
+    case "transformer":
+      return flow.transformers?.[id];
+    case "destination":
+      return flow.destinations?.[id];
+    case "store":
+      return flow.stores?.[id];
+  }
+}
+function getBundlePackages(flow) {
+  return flow.config?.bundle?.packages;
+}
+function readFirstImport(packages, packageName) {
+  if (!packages || !packageName) return void 0;
+  const pkg = packages[packageName];
+  if (!pkg || !pkg.imports || pkg.imports.length === 0) return void 0;
+  const first = pkg.imports[0];
+  return typeof first === "string" && first.length > 0 ? first : void 0;
+}
+function resolveExportName(flow, kind, id) {
+  const step = getStep(flow, kind, id);
+  if (!step) return { exportName: void 0, source: "default" };
+  const packageName = step.package;
+  const importName = step.import;
+  if (typeof importName === "string" && importName.length > 0) {
+    return { exportName: importName, source: "import" };
+  }
+  const firstImport = readFirstImport(getBundlePackages(flow), packageName);
+  if (firstImport) {
+    return { exportName: firstImport, source: "imports" };
+  }
+  return { exportName: void 0, source: "default" };
+}
+
+// src/core/step-packages.ts
+import { packageNameToVariable } from "@walkeros/core";
+function parsePackageSpec(spec) {
+  const at = spec.lastIndexOf("@");
+  if (at <= 0) return { name: spec };
+  const version = spec.slice(at + 1);
+  return version ? { name: spec.slice(0, at), version } : { name: spec.slice(0, at) };
+}
+
+// src/commands/validate/validators/settings.ts
+var CLIENT_HEADER = "walkeros-cli/4.8.1";
+function createSettingsContext(configDir) {
+  return { configDir, cache: /* @__PURE__ */ new Map(), compiled: /* @__PURE__ */ new Map() };
+}
+function selectSettingsSchema(pkg, packageLabel, exportName) {
+  if (exportName === void 0) return { ok: true, settings: pkg.settings };
+  if (pkg.exportSchemas) {
+    const entry = Object.prototype.hasOwnProperty.call(
+      pkg.exportSchemas,
+      exportName
+    ) ? pkg.exportSchemas[exportName] : void 0;
+    if (!isObject4(entry))
+      return {
+        ok: false,
+        reason: `${packageLabel} has no export "${exportName}"`
+      };
+    return { ok: true, settings: entry.settings };
+  }
+  if (pkg.exports && pkg.exports.length < 2)
+    return { ok: true, settings: pkg.settings };
+  return {
+    ok: false,
+    reason: `${packageLabel} predates per-export settings schemas; the step imports "${exportName}"`
+  };
+}
+var SECTION_KIND = {
+  sources: "source",
+  transformers: "transformer",
+  destinations: "destination",
+  stores: "store"
+};
+function pointerSegments(pointer) {
+  if (pointer === "") return [];
+  return pointer.split("/").slice(1).map((segment) => segment.replace(/~1/g, "/").replace(/~0/g, "~"));
+}
+function valueAt(root, segments) {
+  let current = root;
+  for (const segment of segments) {
+    if (Array.isArray(current)) current = current[Number(segment)];
+    else if (isObject4(current)) current = current[segment];
+    else return void 0;
+  }
+  return current;
+}
+var MARKER = ENV_MARKER_PREFIX.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+var ENV_MARKER = new RegExp(
+  `${MARKER}([a-zA-Z_][a-zA-Z0-9_]*)(?::((?:(?!${MARKER})[^\\s"'])*))?`,
+  "g"
+);
+function prepareSettings(settings) {
+  const deferred = [];
+  const walk = (value, segments) => {
+    if (Array.isArray(value))
+      return value.map((item, index) => walk(item, [...segments, `${index}`]));
+    if (isObject4(value))
+      return Object.fromEntries(
+        Object.entries(value).map(([key, item]) => [
+          key,
+          walk(item, [...segments, key])
+        ])
+      );
+    if (typeof value !== "string") return value;
+    if (value.startsWith(SECRET_MARKER_PREFIX)) {
+      deferred.push({
+        segments,
+        reference: `$secret.${value.slice(SECRET_MARKER_PREFIX.length)}`
+      });
+      return value;
+    }
+    if (value.includes(ENV_MARKER_PREFIX)) {
+      let runtimeOnly = false;
+      const withDefaults = value.replace(
+        ENV_MARKER,
+        (_match, _name, fallback) => {
+          if (fallback === void 0) runtimeOnly = true;
+          return fallback ?? "";
+        }
+      );
+      if (!runtimeOnly) return withDefaults;
+      deferred.push({
+        segments,
+        reference: value.replace(
+          ENV_MARKER,
+          (_match, name, fallback) => fallback === void 0 ? `$env.${name}` : `$env.${name}:${fallback}`
+        )
+      });
+      return value;
+    }
+    if (REF_STORE.test(value) || value.startsWith(REF_CODE_PREFIX)) {
+      deferred.push({ segments, reference: value });
+    }
+    return value;
+  };
+  return { value: walk(settings, []), deferred };
+}
+function isUnder(segments, prefix) {
+  return prefix.every((segment, index) => segments[index] === segment);
+}
+function bundlePin(rawFlow, name) {
+  const config = isObject4(rawFlow) ? rawFlow.config : void 0;
+  const bundle = isObject4(config) ? config.bundle : void 0;
+  const packages = isObject4(bundle) ? bundle.packages : void 0;
+  const pin = isObject4(packages) ? packages[name] : void 0;
+  if (!isObject4(pin)) return {};
+  return {
+    ...typeof pin.version === "string" ? { version: pin.version } : {},
+    ...typeof pin.path === "string" ? { path: pin.path } : {}
+  };
+}
+function packageSource(spec, rawFlow) {
+  if (spec.startsWith(".") || spec.startsWith("/"))
+    return { name: spec, localPath: spec };
+  const { name, version } = parsePackageSpec(spec);
+  const pin = bundlePin(rawFlow, name);
+  if (pin.path) return { name, localPath: pin.path };
+  const pinned = pin.version ?? version;
+  return pinned ? { name, version: pinned } : { name };
+}
+function readJson(file) {
+  return JSON.parse(fs8.readFileSync(file, "utf-8"));
+}
+function readLocalSchema(source, configDir) {
+  const localPath = source.localPath ?? "";
+  const root = path2.isAbsolute(localPath) ? localPath : path2.resolve(configDir, localPath);
+  const file = [
+    path2.join(root, "dist", "walkerOS.json"),
+    path2.join(root, "walkerOS.json")
+  ].find((candidate) => fs8.existsSync(candidate));
+  if (!file) throw new Error(`no walkerOS.json under ${root}`);
+  const meta = readJson(file);
+  const pkgFile = path2.join(root, "package.json");
+  const pkg = fs8.existsSync(pkgFile) ? readJson(pkgFile) : void 0;
+  const schemas5 = isObject4(meta) ? meta.schemas : void 0;
+  const exportSchemas = isObject4(meta) ? meta.exportSchemas : void 0;
+  const declared = isObject4(meta) && isObject4(meta.$meta) ? meta.$meta.exports : void 0;
+  const version = isObject4(pkg) && typeof pkg.version === "string" ? pkg.version : void 0;
+  return {
+    ...version ? { version } : {},
+    settings: isObject4(schemas5) ? schemas5.settings : void 0,
+    ...isObject4(exportSchemas) ? { exportSchemas } : {},
+    ...isObject4(declared) ? { exports: Object.keys(declared) } : {}
+  };
+}
+async function loadSchema(source, context) {
+  if (source.localPath !== void 0) {
+    const configDir = context.configDir;
+    if (configDir === void 0)
+      throw new Error(
+        "it is a local path package and the input is not a file, so there is no directory to read it from"
+      );
+    return readLocalSchema(source, configDir);
+  }
+  const info = await fetchPackage(source.name, {
+    ...source.version ? { version: source.version } : {},
+    client: CLIENT_HEADER
+  });
+  return {
+    version: info.version,
+    settings: info.schemas.settings,
+    ...info.exportSchemas ? { exportSchemas: info.exportSchemas } : {},
+    ...info.exports ? { exports: Object.keys(info.exports) } : {}
+  };
+}
+function compileSettings(settings) {
+  if (!isObject4(settings)) return void 0;
+  const ajv = new Ajv({ allErrors: true, validateFormats: false });
+  try {
+    return { ok: true, validate: ajv.compile(settings) };
+  } catch (error) {
+    return { ok: false, message: getErrorMessage3(error) };
+  }
+}
+function sourceKey(source) {
+  return source.localPath ? `path:${source.localPath}` : `${source.name}@${source.version ?? "latest"}`;
+}
+function cachedSchema(source, context) {
+  const key = sourceKey(source);
+  let pending = context.cache.get(key);
+  if (!pending) {
+    pending = loadSchema(source, context);
+    context.cache.set(key, pending);
+  }
+  return pending;
+}
+function cachedCompile(source, exportName, settings, context) {
+  const key = `${sourceKey(source)}#${exportName ?? ""}`;
+  if (context.compiled.has(key)) return context.compiled.get(key);
+  const compiled = compileSettings(settings);
+  context.compiled.set(key, compiled);
+  return compiled;
+}
+async function checkStepSettings(target, resolvedFlow, rawFlow, check, context) {
+  const at = `flows.${target.flow}.${target.section}.${target.key}`;
+  const outcome = { findings: [], skipped: [], deferred: [] };
+  const spec = typeof target.entry.package === "string" ? target.entry.package : "";
+  if (!spec) {
+    outcome.skipped.push({
+      path: at,
+      check,
+      reason: "No package field, so there is no settings schema to fetch",
+      code: "NO_PACKAGE"
+    });
+    return outcome;
+  }
+  const source = packageSource(spec, rawFlow);
+  let schema;
+  try {
+    schema = await cachedSchema(source, context);
+  } catch (error) {
+    outcome.skipped.push({
+      path: at,
+      check,
+      reason: `Schema for ${source.name}${source.version ? `@${source.version}` : ""} could not be loaded: ${getErrorMessage3(error)}`,
+      code: "SCHEMA_UNAVAILABLE"
+    });
+    return outcome;
+  }
+  outcome.checked = {
+    path: at,
+    package: source.name,
+    ...schema.version ? { version: schema.version } : {}
+  };
+  const { exportName } = resolveExportName(
+    resolvedFlow,
+    SECTION_KIND[target.section],
+    target.key
+  );
+  const version = schema.version ?? source.version;
+  const selection = selectSettingsSchema(
+    schema,
+    version ? `${source.name}@${version}` : source.name,
+    exportName
+  );
+  if (!selection.ok) {
+    outcome.skipped.push({
+      path: at,
+      check,
+      reason: selection.reason,
+      code: "NO_SETTINGS_SCHEMA"
+    });
+    return outcome;
+  }
+  const compiled = cachedCompile(
+    source,
+    exportName,
+    selection.settings,
+    context
+  );
+  if (!compiled) {
+    outcome.skipped.push({
+      path: at,
+      check,
+      reason: `Package ${source.name} has no settings schema`,
+      code: "NO_SETTINGS_SCHEMA"
+    });
+    return outcome;
+  }
+  if (!compiled.ok) {
+    outcome.skipped.push({
+      path: at,
+      check,
+      reason: `The settings schema of ${source.name} cannot be compiled: ${compiled.message}`,
+      code: "SCHEMA_UNAVAILABLE"
+    });
+    return outcome;
+  }
+  const validate2 = compiled.validate;
+  const step = stepOf(resolvedFlow, target.section, target.key);
+  const config = isObject4(step?.config) ? step.config : {};
+  const prepared = prepareSettings(config.settings ?? {});
+  const base = `${at}.config.settings`;
+  for (const { segments, reference } of prepared.deferred) {
+    outcome.deferred.push({
+      path: [base, ...segments].join("."),
+      reference
+    });
+  }
+  if (validate2(prepared.value)) return outcome;
+  for (const e of validate2.errors || []) {
+    const segments = pointerSegments(e.instancePath);
+    if (prepared.deferred.some((d) => isUnder(segments, d.segments))) continue;
+    const finding = {
+      path: [base, ...segments].join("."),
+      message: describeAjvError(e),
+      code: "ENTRY_SCHEMA",
+      keyword: e.keyword
+    };
+    if (segments.length > 0) finding.value = valueAt(prepared.value, segments);
+    outcome.findings.push(finding);
+  }
+  return outcome;
+}
+function describeAjvError(error) {
+  const message = error.message || "Unknown error";
+  const extra = error.params.additionalProperty;
+  return error.keyword === "additionalProperties" && typeof extra === "string" ? `${message}: "${extra}"` : message;
+}
+function stepOf(flow, section, key) {
+  switch (section) {
+    case "sources":
+      return flow.sources?.[key];
+    case "destinations":
+      return flow.destinations?.[key];
+    case "transformers":
+      return flow.transformers?.[key];
+    case "stores":
+      return flow.stores?.[key];
+  }
+}
+
+// src/commands/validate/validators/flow.ts
+var { validateFlowConfig: validateFlowConfig2 } = schemas3;
+var DEPRECATED_PACKAGES = {
+  "@walkeros/store-memory": "has been removed. Use the built-in cache by omitting cache.store, or remove the store declaration if it was only used as a cache target."
+};
+var OPEN_STEP_KINDS = [
+  ["destinations", "Destination"],
+  ["stores", "Store"]
+];
+async function validateFlowWithPackages(input, options = {}) {
+  const run = runFlowChecks(input, options);
+  const { result, scope } = run;
+  if (options.offline) {
+    const described = describeScope(scope, run.checks);
+    described.offline = true;
+    result.details.scope = described;
+    return result;
+  }
+  run.checks.push("flow:package-settings");
+  const context = createSettingsContext(options.configDir);
+  const deferred = [];
+  const packages = [];
+  const pending = [];
+  for (const name of scope.flows) {
+    const flow = run.resolved.get(name);
+    const rawFlow = run.typed?.flows[name];
+    const reason = run.gate(name);
+    if (!flow || !rawFlow || reason) {
+      run.skipped.push({
+        path: `flows.${name}`,
+        check: "flow:package-settings",
+        reason: reason ?? `flows.${name} did not resolve`,
+        code: "GATED_BY_ERRORS"
+      });
+      continue;
+    }
+    for (const section of ENTRY_SECTIONS) {
+      const steps = isObject5(rawFlow[section]) ? rawFlow[section] : {};
+      for (const [key, entry] of Object.entries(steps)) {
+        if (!isObject5(entry) || entry.package === void 0) continue;
+        const target = { flow: name, section, key, entry };
+        pending.push(
+          checkStepSettings(
+            target,
+            flow,
+            rawFlow,
+            "flow:package-settings",
+            context
+          )
+        );
+      }
+    }
+  }
+  for (const outcome of await Promise.all(pending)) {
+    result.warnings.push(...outcome.findings);
+    run.skipped.push(...outcome.skipped);
+    deferred.push(...outcome.deferred);
+    if (outcome.checked) packages.push(outcome.checked);
+  }
+  result.details.scope = describeScope(scope, run.checks);
+  result.details.deferred = [...result.details.deferred ?? [], ...deferred];
+  if (packages.length > 0) result.details.packages = packages;
+  return result;
+}
+function runFlowChecks(input, options) {
+  const errors = [];
+  const warnings = [];
+  const skipped = [];
+  const checks = ["file:schema", "flow:schema"];
+  const details = {};
+  const resolved = /* @__PURE__ */ new Map();
+  const result = {
+    valid: false,
+    type: "flow",
+    errors,
+    warnings,
+    details
+  };
+  let json;
+  const scope = resolveScope(input, { flow: options.flow });
+  try {
+    json = JSON.stringify(input, null, 2);
+  } catch {
+    errors.push({
+      path: "root",
+      message: "Input cannot be serialized to JSON",
+      code: "SERIALIZATION_ERROR"
+    });
+    return {
+      result,
+      scope,
+      resolved,
+      checks,
+      skipped,
+      gate: () => "the input cannot be serialized"
+    };
+  }
+  errors.push(...scope.errors);
+  const config = isObject5(input) ? input : {};
+  const flowsValue = config.flows;
+  const flows = isObject5(flowsValue) ? flowsValue : void 0;
+  const allFlows = scope.allFlows;
+  const inScope = (path4) => {
+    const flow = flowOfPath(path4, allFlows);
+    return flow === void 0 || scope.flows.includes(flow);
+  };
+  let contractErrors = 0;
+  if ("contract" in config) {
+    checks.push("file:contract");
+    const contract = validateContract(config.contract);
+    contractErrors = contract.errors.length;
+    for (const error of contract.errors)
+      errors.push({ ...error, path: `contract.${error.path}` });
+    for (const warning of contract.warnings)
+      warnings.push({ ...warning, path: `contract.${warning.path}` });
+  }
+  const coreResult = validateFlowConfig2(json);
+  for (const issue of coreResult.errors) {
+    const path4 = issue.path || "root";
+    if (!inScope(path4)) continue;
+    if (path4 === "contract" && contractErrors > 0) continue;
+    errors.push({ path: path4, message: issue.message, code: "SCHEMA_VALIDATION" });
+  }
+  for (const issue of coreResult.warnings) {
+    const path4 = issue.path || "root";
+    if (!inScope(path4)) continue;
+    warnings.push({ path: path4, message: issue.message, code: "CONFIG_WARNING" });
+  }
+  if (flows && allFlows.length === 0) {
+    errors.push({
+      path: "flows",
+      message: "At least one flow is required",
+      code: "EMPTY_FLOWS"
+    });
+  }
+  checks.push("flow:steps");
+  for (const flowName of scope.flows) {
+    const flowValue = flows?.[flowName];
+    if (!isObject5(flowValue)) continue;
+    const transformersValue = flowValue.transformers;
+    if (isObject5(transformersValue)) {
+      for (const [name, transformerValue] of Object.entries(
+        transformersValue
+      )) {
+        if (!isObject5(transformerValue)) continue;
+        const result2 = validateStepEntry(transformerValue, "Transformer");
+        if (!result2.ok) {
+          errors.push({
+            path: `flows.${flowName}.transformers.${name}`,
+            message: result2.reason || "Invalid transformer entry.",
+            code: result2.code
+          });
+        }
+      }
+    }
+    for (const [section, kind] of OPEN_STEP_KINDS) {
+      const steps = flowValue[section];
+      if (!isObject5(steps)) continue;
+      for (const [name, step] of Object.entries(steps)) {
+        if (!isObject5(step)) continue;
+        const at = `flows.${flowName}.${section}.${name}`;
+        for (const key of unknownStepKeys(step, kind)) {
+          warnings.push({
+            path: `${at}.${key}`,
+            message: `Unknown key "${key}" on ${kind} is ignored by the runtime`,
+            suggestion: "Remove the key, or move it to where it belongs.",
+            code: "UNKNOWN_KEY"
+          });
+        }
+        const pkg = step.package;
+        if (typeof pkg === "string" && pkg in DEPRECATED_PACKAGES) {
+          warnings.push({
+            path: at,
+            message: `${kind} "${name}" uses ${pkg}, which ${DEPRECATED_PACKAGES[pkg]}`,
+            code: "DEPRECATED_PACKAGE"
+          });
+        }
+      }
+    }
+  }
+  if (flows) {
+    details.flowNames = allFlows;
+    details.flowCount = allFlows.length;
+  }
+  checks.push("flow:package-versions");
+  let totalPackageCount = 0;
+  for (const flowName of scope.flows) {
+    const flowValue = flows?.[flowName];
+    if (!isObject5(flowValue)) continue;
+    const flowConfig = flowValue.config;
+    if (!isObject5(flowConfig)) continue;
+    const bundle = flowConfig.bundle;
+    if (!isObject5(bundle)) continue;
+    const packages = bundle.packages;
+    if (!isObject5(packages)) continue;
+    for (const [pkgName, pkgConfigValue] of Object.entries(packages)) {
+      if (!isObject5(pkgConfigValue)) continue;
+      if (!pkgConfigValue.version && !pkgConfigValue.path) {
+        warnings.push({
+          path: `flows.${flowName}.config.bundle.packages.${pkgName}`,
+          message: `Package "${pkgName}" has no version specified`,
+          suggestion: "Consider specifying a version for reproducible builds",
+          code: "PACKAGE_VERSION_MISSING"
+        });
+      }
+    }
+    totalPackageCount += Object.keys(packages).length;
+  }
+  if (totalPackageCount > 0) {
+    details.packageCount = totalPackageCount;
+  }
+  if (coreResult.context) {
+    details.context = coreResult.context;
+  }
+  const typed = isFlowJson(input) ? input : void 0;
+  const gate = (name) => {
+    if (!typed || errors.some((e) => flowOfPath(e.path, allFlows) === void 0))
+      return "file-level errors: the file shape or its contract is not valid";
+    if (errors.some((e) => flowOfPath(e.path, allFlows) === name))
+      return `earlier errors in flows.${name}`;
+    return void 0;
+  };
+  const perFlow = (stageChecks, run) => {
+    checks.push(...stageChecks);
+    for (const name of scope.flows) {
+      const reason = gate(name);
+      const flow = typed?.flows[name];
+      if (reason || !typed || !flow) {
+        for (const check of stageChecks) {
+          skipped.push({
+            path: `flows.${name}`,
+            check,
+            reason: reason ?? `flows.${name} is not a flow object`,
+            code: "GATED_BY_ERRORS"
+          });
+        }
+        continue;
+      }
+      run(name, flow, typed);
+    }
+  };
+  perFlow(["flow:structure"], (name, flow, file) => {
+    const structure = validateFlowStructure({
+      ...file,
+      flows: { [name]: flow }
+    });
+    errors.push(...structure.errors);
+    warnings.push(...structure.warnings);
+  });
+  perFlow(["flow:routes"], (name, flow) => {
+    lintFlowRoutes(name, flow, errors, warnings);
+  });
+  const resolutions = /* @__PURE__ */ new Map();
+  const resolutionOf = (name, file) => {
+    let resolution = resolutions.get(name);
+    if (!resolution) {
+      resolution = resolveFlow(file, name);
+      resolutions.set(name, resolution);
+    }
+    return resolution;
+  };
+  let totalConnections;
+  perFlow(
+    ["flow:examples", "flow:contract-examples", "flow:mapping-keys"],
+    (name, flow, file) => {
+      const connections = buildConnectionGraph(flow);
+      for (const conn of connections) {
+        checkCompatibility(name, conn, errors, warnings);
+      }
+      totalConnections = (totalConnections ?? 0) + connections.length;
+      const resolution = resolutionOf(name, file);
+      for (const [stepName, transformer] of Object.entries(
+        flow.transformers || {}
+      )) {
+        if (!isValidateStep(transformer)) continue;
+        const resolvedConfig = resolution.ok ? resolution.flow.transformers?.[stepName]?.config : void 0;
+        checkValidateStepExamples(
+          `flows.${name}.transformers.${stepName}`,
+          transformer,
+          file.contract,
+          errors,
+          warnings,
+          options.strict === true,
+          skipped,
+          isObject5(resolvedConfig) && isObject5(resolvedConfig.settings) ? resolvedConfig.settings : void 0
+        );
+      }
+      for (const [destName, dest] of Object.entries(flow.destinations || {})) {
+        if (!isObject5(dest.config)) continue;
+        const mapping = dest.config.mapping;
+        if (!isObject5(mapping)) continue;
+        for (const key of Object.keys(mapping)) {
+          if (key.includes(".") && !key.includes(" ")) {
+            const parts = key.split(".");
+            warnings.push({
+              path: `flows.${name}.destinations.${destName}.config.mapping`,
+              message: `Mapping key "${key}" looks like dot-notation. Mapping uses nested entity \u2192 action structure.`,
+              suggestion: `Use nested format: { "${parts[0]}": { "${parts.slice(1).join(".")}": { ... } } }`,
+              code: "MAPPING_DOT_KEY"
+            });
+          }
+        }
+      }
+    }
+  );
+  if (totalConnections !== void 0) {
+    details.connectionsChecked = totalConnections;
+  }
+  const deferred = [];
+  perFlow(["flow:resolve"], (name, flow, file) => {
+    const resolution = resolutionOf(name, file);
+    if (!resolution.ok) {
+      errors.push(resolution.error);
+      return;
+    }
+    resolved.set(name, resolution.flow);
+    checkResolvedWindowCollector(name, flow, resolution.flow, errors, deferred);
+  });
+  details.scope = describeScope(scope, checks);
+  details.skipped = skipped;
+  details.deferred = deferred;
+  result.valid = errors.length === 0;
+  return {
+    result,
+    scope,
+    typed,
+    resolved,
+    checks,
+    skipped,
+    gate
+  };
+}
+function checkResolvedWindowCollector(name, raw, flow, errors, deferred) {
+  const written = raw.config?.settings?.windowCollector;
+  const value = flow.config?.settings?.windowCollector;
+  if (flow.config?.platform !== "web" || typeof written !== "string" || !/\$(?:var|env)\./.test(written))
+    return;
+  const path4 = `flows.${name}.config.settings.windowCollector`;
+  if (typeof value === "string" && value.includes(ENV_MARKER_PREFIX2)) {
+    deferred.push({ path: path4, reference: written });
+    return;
+  }
+  const check = checkWindowCollector2(value);
+  if (check.ok) return;
+  errors.push({
+    path: path4,
+    message: `${JSON.stringify(written)} resolved to ${JSON.stringify(value)}, which ${check.reason}`,
+    code: "SCHEMA_VALIDATION"
+  });
+}
+function unknownStepKeys(step, kind) {
+  const unknown = [];
+  const rest = { ...step };
+  for (; ; ) {
+    const verdict = validateStepEntry(rest, kind);
+    if (verdict.code !== "UNKNOWN_KEY" || verdict.key === void 0) break;
+    unknown.push(verdict.key);
+    Reflect.deleteProperty(rest, verdict.key);
+  }
+  return unknown;
+}
+function routeTargets(spec) {
+  if (spec === void 0) return [];
+  const targets = /* @__PURE__ */ new Set();
+  for (const node of getRouteGraph(spec)) {
+    for (const target of node.targets) targets.add(target);
+  }
+  return [...targets];
+}
+function buildConnectionGraph(config) {
+  const connections = [];
+  for (const [name, source] of Object.entries(config.sources || {})) {
+    if (!source.next || !source.examples) continue;
+    const nextNames = routeTargets(source.next);
+    for (const nextName of nextNames) {
+      const transformer = config.transformers?.[nextName];
+      if (transformer?.examples) {
+        connections.push({
+          from: { type: "source", name, examples: source.examples },
+          to: {
+            type: "transformer",
+            name: nextName,
+            examples: transformer.examples
+          }
+        });
+      }
+    }
+  }
+  for (const [name, transformer] of Object.entries(config.transformers || {})) {
+    if (!transformer.next || !transformer.examples) continue;
+    const nextNames = routeTargets(transformer.next);
+    for (const nextName of nextNames) {
+      const nextTransformer = config.transformers?.[nextName];
+      if (nextTransformer?.examples) {
+        connections.push({
+          from: {
+            type: "transformer",
+            name,
+            examples: transformer.examples
+          },
+          to: {
+            type: "transformer",
+            name: nextName,
+            examples: nextTransformer.examples
+          }
+        });
+      }
+    }
+  }
+  for (const [name, dest] of Object.entries(config.destinations || {})) {
+    if (!dest.before || !dest.examples) continue;
+    const beforeNames = routeTargets(dest.before);
+    for (const beforeName of beforeNames) {
+      const transformer = config.transformers?.[beforeName];
+      if (transformer?.examples) {
+        connections.push({
+          from: {
+            type: "transformer",
+            name: beforeName,
+            examples: transformer.examples
+          },
+          to: { type: "destination", name, examples: dest.examples }
+        });
+      }
+    }
+  }
+  return connections;
+}
+function checkCompatibility(flowName, conn, errors, warnings) {
+  const fromOuts = Object.entries(conn.from.examples).filter(([, ex]) => hasComparableOut(ex.out)).map(([name, ex]) => ({ name, value: ex.out }));
+  const toIns = Object.entries(conn.to.examples).filter(([, ex]) => ex.in !== void 0 && !ex.command).map(([name, ex]) => ({ name, value: ex.in }));
+  const path4 = `flows.${flowName}.${conn.from.type}s.${conn.from.name} \u2192 ${conn.to.type}s.${conn.to.name}`;
+  if (fromOuts.length === 0 || toIns.length === 0) {
+    warnings.push({
+      path: path4,
+      message: "Cannot check compatibility: missing out or in examples",
+      suggestion: "Add out examples to the source step or in examples to the target step",
+      code: "EXAMPLES_INCOMPLETE"
+    });
+    return;
+  }
+  const hasMatch = fromOuts.some(
+    (out) => outEvents(out.value).some(
+      (event) => toIns.some((inp) => isStructurallyCompatible(event, inp.value))
+    )
+  );
+  if (!hasMatch) {
+    errors.push({
+      path: path4,
+      message: "No compatible out/in pair found between connected steps",
+      code: "INCOMPATIBLE_EXAMPLES"
+    });
+  }
+}
+function isStepOut(value) {
+  return Array.isArray(value) && value.every((entry) => Array.isArray(entry) && typeof entry[0] === "string");
+}
+function returnedEvents(value) {
+  if (isObject5(value)) return [isObject5(value.event) ? value.event : value];
+  if (Array.isArray(value)) return value.flatMap(returnedEvents);
+  return [];
+}
+function outEvents(out) {
+  if (isStepOut(out)) {
+    return out.flatMap(([head, first]) => {
+      if (head === "elb") return isObject5(first) ? [first] : [];
+      if (head === "return") return returnedEvents(first);
+      return [];
+    });
+  }
+  if (Array.isArray(out) || typeof out === "string")
+    return out.length > 0 ? [out] : [];
+  return isObject5(out) && Object.keys(out).length > 0 ? [out] : [];
+}
+function hasComparableOut(out) {
+  return outEvents(out).length > 0;
+}
+function isStructurallyCompatible(a, b) {
+  if (typeof a !== typeof b) return false;
+  if (a === null || b === null) return a === b;
+  if (Array.isArray(a) && Array.isArray(b)) return true;
+  if (typeof a === "object" && typeof b === "object") {
+    const keysA = Object.keys(a);
+    const keysB = Object.keys(b);
+    const shared = keysA.filter((k) => keysB.includes(k));
+    return shared.length >= Math.min(keysA.length, keysB.length) * 0.5;
+  }
+  return true;
+}
+function lintFlowRoutes(flowName, flow, errors, warnings) {
+  const known = new Set(Object.keys(flow.transformers || {}));
+  const check = (spec, position) => {
+    if (spec !== void 0) lintRoute(spec, position, known, errors, warnings);
+  };
+  const at = `flows.${flowName}`;
+  for (const [name, source] of Object.entries(flow.sources || {})) {
+    check(source.before, `${at}.sources.${name}.before`);
+    check(source.next, `${at}.sources.${name}.next`);
+  }
+  for (const [name, transformer] of Object.entries(flow.transformers || {})) {
+    check(transformer.before, `${at}.transformers.${name}.before`);
+    check(transformer.next, `${at}.transformers.${name}.next`);
+  }
+  check(flow.collector?.next, `${at}.collector.next`);
+  for (const [name, dest] of Object.entries(flow.destinations || {})) {
+    check(dest.before, `${at}.destinations.${name}.before`);
+    check(dest.next, `${at}.destinations.${name}.next`);
+  }
+}
+function routeAt(spec, path4) {
+  let current = spec;
+  for (const key of path4) {
+    if (typeof key === "number")
+      current = Array.isArray(current) ? current[key] : void 0;
+    else current = isObject5(current) ? current[key] : void 0;
+  }
+  return current;
+}
+function lintRoute(spec, position, known, errors, warnings) {
+  const where = (path4) => path4.length > 0 ? `${position}.${path4.join(".")}` : position;
+  const reported = /* @__PURE__ */ new Set();
+  const once = (key) => {
+    if (reported.has(key)) return false;
+    reported.add(key);
+    return true;
+  };
+  for (const node of getRouteGraph(spec)) {
+    for (const target of node.targets) {
+      if (known.has(target) || !once(`unknown:${target}`)) continue;
+      errors.push({
+        path: position,
+        message: `Unknown transformer "${target}" in route at ${position}`,
+        code: "UNKNOWN_ROUTE_TARGET"
+      });
+    }
+    const last = node.path[node.path.length - 1];
+    if (node.stop && !node.match && node.kind !== "many") {
+      const self = routeAt(spec, node.path);
+      const list = routeAt(spec, node.path.slice(0, -1));
+      if (isObject5(self) && self.stop === true && typeof last === "number" && Array.isArray(list) && last < list.length - 1 && once(`stop:${where(node.path)}`)) {
+        const at = where(node.path);
+        warnings.push({
+          path: at,
+          message: `dead code after stop at ${at}: entries after an unconditional stop never run`,
+          code: "ROUTE_DEAD_CODE",
+          suggestion: "Remove the entries after the stop, or give the stop a match."
+        });
+      }
+    }
+    if (node.kind === "many" && last === "many" && node.targets.length === 0 && once(`empty:${where(node.path)}`)) {
+      const at = where(node.path.slice(0, -1));
+      warnings.push({
+        path: at,
+        message: `empty many at ${at}: selects no branch, so it has no effect`,
+        code: "ROUTE_EMPTY_MANY",
+        suggestion: "Add two or more branch targets to many, or remove it."
+      });
+    }
+    for (const decision of [...node.via ?? [], node]) {
+      const index = decision.path[decision.path.length - 1];
+      if (typeof index !== "number") continue;
+      const listPath = decision.path.slice(0, -1);
+      const list = routeAt(spec, listPath);
+      if (!Array.isArray(list)) continue;
+      const at = where(listPath);
+      if (decision.kind === "many" && list.length === 1 && once(`single:${at}`)) {
+        const only = list[0];
+        const hint = typeof only === "string" ? `use 'next: "${only}"' for clarity` : `use 'next' for clarity`;
+        warnings.push({
+          path: at,
+          message: `single-entry many at ${at}: ${hint}`,
+          code: "ROUTE_SINGLE_MANY",
+          suggestion: "Replace many with next when only one branch exists."
+        });
+      }
+      const explicitOne = listPath[listPath.length - 1] === "one";
+      if (decision.kind === "one" && !explicitOne && list.length > 1 && once(`first-match:${at}`)) {
+        warnings.push({
+          path: at,
+          message: `first-match array at ${at}: an array made only of route configs is an implicit one, the first matching entry wins`,
+          code: "ROUTE_FIRST_MATCH",
+          suggestion: 'Write { "one": [...] } explicitly, or add the step ids as a sequence to run every entry in order.'
+        });
+      }
+    }
+  }
+}
+var VALIDATE_PACKAGE = "@walkeros/transformer-validate";
+function isValidateStep(step) {
+  return step.package === VALIDATE_PACKAGE;
+}
+function resolveStepContracts(entries, contract) {
+  let resolved = {};
+  if (contract) {
+    try {
+      resolved = resolveContracts(contract);
+    } catch (error) {
+      return {
+        ok: false,
+        message: `the root contract does not resolve (${error instanceof Error ? error.message : String(error)})`
+      };
+    }
+  }
+  const sources = [];
+  for (const [index, entry] of entries.entries()) {
+    if (isObject5(entry)) {
+      sources.push(entry);
+      continue;
+    }
+    const match = typeof entry === "string" ? entry.match(REF_CONTRACT) : null;
+    if (!match)
+      return {
+        ok: false,
+        index,
+        message: "an entry must be a $contract reference or a JSON Schema"
+      };
+    if (!(match[1] in resolved))
+      return {
+        ok: false,
+        index,
+        message: `contract "${match[1]}" is not defined in the root contract (defined: ${Object.keys(resolved).join(", ") || "none"})`
+      };
+    const rule = match[2] ? getByPath(resolved[match[1]], match[2]) : resolved[match[1]];
+    if (!isObject5(rule))
+      return {
+        ok: false,
+        index,
+        message: `${match[0]} does not point at a contract rule object`
+      };
+    sources.push(rule);
+  }
+  return { ok: true, sources };
+}
+function checkValidateStepExamples(stepPath, step, contract, errors, warnings, strict, skipped, resolvedSettings) {
+  const settings = resolvedSettings ?? (isObject5(step.config) && isObject5(step.config.settings) ? step.config.settings : {});
+  const contractPath = `${stepPath}.config.settings.contract`;
+  if (settings.contract !== void 0 && !Array.isArray(settings.contract)) {
+    if (step.examples)
+      skipped?.push({
+        path: stepPath,
+        check: "flow:contract-examples",
+        reason: "config.settings.contract is not a list, so the step cannot be judged statically",
+        code: "CONTRACT_NOT_STATIC"
+      });
+    return;
+  }
+  const resolution = Array.isArray(settings.contract) ? resolveStepContracts(settings.contract, contract) : { ok: true, sources: [] };
+  if (!resolution.ok) {
+    errors.push({
+      path: resolution.index === void 0 ? contractPath : `${contractPath}.${resolution.index}`,
+      message: `The validate step's contract does not resolve: ${resolution.message}`,
+      code: "UNRESOLVED_CONTRACT"
+    });
+    return;
+  }
+  if (!step.examples) return;
+  const contracts = resolution.sources;
+  const mode = settings.mode === "strict" ? "strict" : "pass";
+  const format = settings.format === true;
+  const output = isObject5(settings.output) ? settings.output : {};
+  const isValidPath = typeof output.isValid === "string" ? output.isValid : "source.valid";
+  for (const [exName, example] of Object.entries(step.examples)) {
+    if (example.command || !isObject5(example.in)) continue;
+    if (example.out === void 0) continue;
+    const event = example.in;
+    const verdict = validateEventAgainstContract(event, void 0, {
+      contracts,
+      format
+    });
+    const passed = outEvents(example.out);
+    const dropped = isStepOut(example.out) && example.out.some(([head, first]) => head === "return" && first === false);
+    let agrees;
+    if (mode === "strict" && !verdict.isValid) {
+      agrees = dropped && passed.length === 0;
+    } else {
+      agrees = passed.length > 0 && passed.every((out) => {
+        if (!isValidPath) return true;
+        const flag = getByPath(out, isValidPath);
+        return verdict.isValid ? flag !== false : flag === false;
+      });
+    }
+    if (agrees) continue;
+    const reason = verdict.isValid ? "the event satisfies the contract" : `the event breaks the contract (${verdict.errors.map((e) => `${e.path || "/"}: ${e.message}`).join("; ")})`;
+    const expected = mode === "strict" && !verdict.isValid ? 'drops it (["return", false])' : `passes it on${isValidPath ? ` with ${isValidPath} ${verdict.isValid}` : ""}`;
+    const path4 = `${stepPath}.examples.${exName}.out`;
+    const message = `Example out disagrees with the validate step: ${reason}, so with mode "${mode}" the step ${expected}.`;
+    if (strict) {
+      errors.push({ path: path4, message, code: "CONTRACT_VIOLATION" });
+    } else {
+      warnings.push({
+        path: path4,
+        message,
+        suggestion: "Make the example out show what the validate step does with its settings.",
+        code: "CONTRACT_VIOLATION"
+      });
+    }
+  }
+}
+
+// src/commands/validate/validators/mapping.ts
+import { isObject as isObject6 } from "@walkeros/core";
+import { schemas as schemas4 } from "@walkeros/core/dev";
+var { RuleSchema } = schemas4.MappingSchemas;
+function isRule(value) {
+  return isObject6(value) && RuleSchema.safeParse(value).success;
+}
+function isNestedActions(key, value) {
+  if (key.includes(" ") || !isObject6(value)) return false;
+  const rules = Object.values(value);
+  return rules.length > 0 && rules.every(
+    (rule) => Array.isArray(rule) ? rule.length > 0 && rule.every(isRule) : isRule(rule)
+  );
+}
+function validateMapping(input) {
+  const errors = [];
+  const warnings = [];
+  const details = {};
+  if (!isObject6(input)) {
+    errors.push({
+      path: "root",
+      message: "Mapping must be an object with event patterns as keys",
+      code: "INVALID_MAPPING_TYPE"
+    });
+    return { valid: false, type: "mapping", errors, warnings, details };
+  }
+  const mapping = input;
+  const nestedPatterns = [];
+  const flatPatterns = [];
+  for (const [key, value] of Object.entries(mapping)) {
+    if (isNestedActions(key, value)) {
+      for (const action of Object.keys(value))
+        nestedPatterns.push(`${key} ${action}`);
+    } else {
+      flatPatterns.push(key);
+    }
+  }
+  const patterns = [...nestedPatterns, ...flatPatterns];
+  details.eventPatterns = patterns;
+  details.patternCount = patterns.length;
+  flatPatterns.forEach((pattern, index) => {
+    const isWildcard = pattern.includes("*");
+    const hasSpace = pattern.includes(" ");
+    if (!isWildcard && !hasSpace) {
+      errors.push({
+        path: pattern,
+        message: `Invalid event pattern "${pattern}". Must be "entity action" format or contain wildcard (*)`,
+        code: "INVALID_EVENT_PATTERN"
+      });
+    }
+    if (pattern === "*" && index !== flatPatterns.length - 1) {
+      warnings.push({
+        path: "*",
+        code: "CATCH_ALL_NOT_LAST",
+        message: "Catch-all pattern (*) should be last",
+        suggestion: "Move the catch-all pattern (*) to last position for predictable matching"
+      });
+    }
+    const rule = mapping[pattern];
+    const isValidRule = Array.isArray(rule) ? rule.every((r) => typeof r === "object" && r !== null) : typeof rule === "object" && rule !== null;
+    if (!isValidRule) {
+      errors.push({
+        path: pattern,
+        message: "Mapping rule must be an object or array of objects",
+        code: "INVALID_RULE_TYPE"
+      });
+    }
+  });
+  return {
+    valid: errors.length === 0,
+    type: "mapping",
+    errors,
+    warnings,
+    details
+  };
+}
+
+// src/commands/validate/validators/entry.ts
+async function validateEntry(path4, flowConfig, options = {}) {
+  const resolved = resolveScope(flowConfig, { flow: options.flow, path: path4 });
+  const errors = [...resolved.errors];
+  const skipped = [];
+  const deferred = [];
+  const packages = [];
+  const context = createSettingsContext(options.configDir);
+  const file = isFlowJson(flowConfig) ? flowConfig : void 0;
+  const resolutions = /* @__PURE__ */ new Map();
+  for (const target of resolved.entries) {
+    const at = `flows.${target.flow}.${target.section}.${target.key}`;
+    let resolution = resolutions.get(target.flow);
+    if (!resolution && file) {
+      resolution = resolveFlow(file, target.flow);
+      resolutions.set(target.flow, resolution);
+      if (!resolution.ok) errors.push(resolution.error);
+    }
+    if (!resolution?.ok) {
+      skipped.push({
+        path: at,
+        check: "entry:settings",
+        reason: `flows.${target.flow} does not resolve, so its settings cannot be checked`,
+        code: "GATED_BY_ERRORS"
+      });
+      continue;
+    }
+    const outcome = await checkStepSettings(
+      target,
+      resolution.flow,
+      file?.flows[target.flow],
+      "entry:settings",
+      context
+    );
+    errors.push(...outcome.findings);
+    skipped.push(...outcome.skipped);
+    deferred.push(...outcome.deferred);
+    if (outcome.checked) packages.push(outcome.checked);
+  }
+  return {
+    valid: errors.length === 0,
+    type: "entry",
+    errors,
+    warnings: [],
+    details: {
+      scope: describeScope(resolved, ["entry:settings"]),
+      skipped,
+      deferred,
+      ...packages.length > 0 ? { packages } : {}
+    }
+  };
+}
+
+// src/commands/validate/types.ts
+var VALIDATE_CODES = [
+  // Input and options
+  "INPUT_ERROR",
+  "SERIALIZATION_ERROR",
+  "OPTION_NOT_APPLICABLE",
+  // Scope (--flow, --path)
+  "FLOW_NOT_FOUND",
+  "ENTRY_NOT_FOUND",
+  "AMBIGUOUS_ENTRY",
+  "UNSUPPORTED_SECTION",
+  "INVALID_PATH",
+  // Flow file
+  "SCHEMA_VALIDATION",
+  "CONFIG_WARNING",
+  "EMPTY_FLOWS",
+  "UNKNOWN_KEY",
+  "CONFLICT",
+  "MISSING_PACKAGE",
+  "OBSOLETE_CODE_STRING",
+  "INVALID_IMPORT",
+  "INVALID_CODE_SHAPE",
+  "PACKAGE_VERSION_MISSING",
+  "DEPRECATED_PACKAGE",
+  "UNKNOWN_ROUTE_TARGET",
+  "ROUTE_DEAD_CODE",
+  "ROUTE_EMPTY_MANY",
+  "ROUTE_SINGLE_MANY",
+  "ROUTE_FIRST_MATCH",
+  "INCOMPATIBLE_EXAMPLES",
+  "EXAMPLES_INCOMPLETE",
+  "CONTRACT_VIOLATION",
+  "MAPPING_DOT_KEY",
+  "FLOW_REF_WARNING",
+  "FLOW_CYCLE",
+  "VAR_CYCLE",
+  // Structure (the bundler's own preflight, validateFlowStructure)
+  "INVALID_COMPONENT_NAME",
+  "INVALID_REFERENCE",
+  "STORE_REFERENCE_NOT_FOUND",
+  "STATE_STORE_UNKNOWN",
+  "STATE_STORE_FILE",
+  "TRANSFORMER_MAPPING_NO_OP",
+  // Resolution (getFlowSettings, as the bundler resolves the flow)
+  "UNRESOLVED_REFERENCE",
+  "MISSING_ENV",
+  "WEB_SECRET_REF",
+  "UNRESOLVED_CONTRACT",
+  // Entry settings against the package schema
+  "ENTRY_SCHEMA",
+  // Contract
+  "NO_CONTRACT_SECTION",
+  "INVALID_CONTRACT",
+  "FLAT_CONTRACT_SHAPE",
+  "INVALID_CONTRACT_ENTRY",
+  "UNKNOWN_CONTRACT_KEY",
+  "INVALID_TAGGING",
+  "INVALID_SCHEMA",
+  "INVALID_EXTENDS",
+  "INVALID_SECTION",
+  "INVALID_EVENTS",
+  "CIRCULAR_EXTENDS",
+  "INVALID_ENTITY_KEY",
+  "INVALID_ENTITY",
+  "INVALID_ACTION_KEY",
+  "INVALID_SCHEMA_ENTRY",
+  // Event
+  "NOT_AN_OBJECT",
+  "MISSING_EVENT_NAME",
+  "EMPTY_EVENT_NAME",
+  "INVALID_EVENT_NAME",
+  // Mapping
+  "INVALID_MAPPING_TYPE",
+  "INVALID_EVENT_PATTERN",
+  "INVALID_RULE_TYPE",
+  "CATCH_ALL_NOT_LAST",
+  // Skips (details.skipped[].code)
+  "GATED_BY_ERRORS",
+  "CONTRACT_NOT_STATIC",
+  "NO_PACKAGE",
+  "NO_SETTINGS_SCHEMA",
+  "SCHEMA_UNAVAILABLE"
+];
+
+// src/commands/validate/index.ts
+function inapplicableOptions(type, options) {
+  const errors = [];
+  if (options.offline === true && (type !== "flow" || options.path)) {
+    errors.push({
+      path: "options.offline",
+      message: type === "flow" ? "--offline removes the package settings check, which is all --path checks; drop one of them" : `--offline applies to a whole flow file and does not apply to -t ${type}`,
+      code: "OPTION_NOT_APPLICABLE"
+    });
+  }
+  if (type === "flow") return errors;
+  if (options.path !== void 0) {
+    errors.push({
+      path: "options.path",
+      message: `--path addresses an entry in a flow file and does not apply to -t ${type}`,
+      code: "OPTION_NOT_APPLICABLE"
+    });
+  }
+  if (options.flow !== void 0) {
+    errors.push({
+      path: "options.flow",
+      message: `--flow names a flow in a flow file and does not apply to -t ${type}`,
+      code: "OPTION_NOT_APPLICABLE"
+    });
+  }
+  return errors;
+}
+function validateContractInput(input) {
+  if (!isFlowJson(input)) return validateContract(input);
+  const contract = isObject7(input) ? input.contract : void 0;
+  if (contract === void 0) {
+    return {
+      valid: false,
+      type: "contract",
+      errors: [
+        {
+          path: "contract",
+          message: "The flow file has no contract section to validate",
+          code: "NO_CONTRACT_SECTION"
+        }
+      ],
+      warnings: [],
+      details: {}
+    };
+  }
+  return validateContract(contract);
+}
+function configDirOf(input) {
+  if (typeof input !== "string") return void 0;
+  const candidate = path3.resolve(input);
+  return fs9.existsSync(candidate) && fs9.statSync(candidate).isFile() ? path3.dirname(candidate) : void 0;
+}
+function withDocumentScope(result, check) {
+  return {
+    ...result,
+    details: {
+      ...result.details,
+      scope: result.details.scope ?? { flows: [], checks: [check] },
+      skipped: result.details.skipped ?? []
+    }
+  };
+}
+async function validate(type, input, options = {}) {
+  let resolved = input;
+  if (typeof input === "string") {
+    if (input.trim() === "") throw new Error(`${type} is required`);
+    resolved = await loadJsonConfig(input);
+  }
+  const misuse = inapplicableOptions(type, options);
+  if (misuse.length > 0) {
+    return {
+      valid: false,
+      type,
+      errors: misuse,
+      warnings: [],
+      details: { scope: { flows: [], checks: [] }, skipped: [] }
+    };
+  }
+  const result = await validateByType(type, input, resolved, options);
+  return options.strict === true ? escalateStrict(result) : result;
+}
+function escalateStrict(result) {
+  const skipped = result.details.skipped ?? [];
+  if (result.warnings.length === 0 && skipped.length === 0) return result;
+  return { ...result, valid: false };
+}
+async function validateByType(type, input, resolved, options) {
+  switch (type) {
+    case "contract":
+      return withDocumentScope(validateContractInput(resolved), "contract");
+    case "event":
+      return withDocumentScope(validateEvent2(resolved), "event");
+    case "flow":
+      if (options.path !== void 0) {
+        return validateEntry(options.path, resolved, {
+          flow: options.flow,
+          configDir: options.configDir ?? configDirOf(input)
+        });
+      }
+      return validateFlowWithPackages(resolved, {
+        flow: options.flow,
+        strict: options.strict,
+        offline: options.offline,
+        configDir: options.configDir ?? configDirOf(input)
+      });
+    case "mapping":
+      return withDocumentScope(validateMapping(resolved), "mapping");
+    default:
+      throw new Error(`Unknown validation type: ${type}`);
+  }
+}
+export {
+  VALIDATE_CODES,
+  validate
+};
+//# sourceMappingURL=validate.js.map