@walkeros/cli 1.1.3 → 1.2.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @walkeros/cli
 
+## 1.2.0
+
+### Minor Changes
+
+- cc68f50: Add validate command for events, flows, and mappings
+  - `walkeros validate event` - validates event structure using
+    PartialEventSchema
+  - `walkeros validate flow` - validates flow configurations using SetupSchema
+  - `walkeros validate mapping` - validates mapping event patterns
+
+  Includes programmatic API via `import { validate } from '@walkeros/cli'`
+
 ## 1.1.3
 
 ### Patch Changes

package/dist/examples/flow-complete.json

@@ -250,7 +250,10 @@
                           "this",
                           {
                             "map": {
-                              "item_id": "data.id",
+                              "item_id": [
+                                { "key": "data.sku" },
+                                { "key": "data.id" }
+                              ],
                               "item_name": "data.name",
                               "item_category": "data.category",
                               "price": "data.price"
@@ -322,6 +325,12 @@
               "url": "$var.apiUrl",
               "batch": 5
             },
+            "data": {
+              "map": {
+                "sent_at": { "fn": "$code:() => Date.now()" },
+                "flow_version": "$var.flowVersion"
+              }
+            },
             "mapping": {
               "order": {
                 "complete": {

package/dist/examples/flow-complete.md

@@ -71,7 +71,7 @@ npx walkeros serve packages/cli/examples/flow-complete.json --flow web
 
 ## Feature Inventory
 
-### Features Used (51)
+### Features Used (53)
 
 #### Mapping - Value Extraction
 
@@ -81,6 +81,7 @@ npx walkeros serve packages/cli/examples/flow-complete.json --flow web
 | Static value      | Meta ViewContent  | `"content_type": { "value": "product" }`                     |
 | Key with fallback | GA4 add_to_cart   | `{ "key": "data.currency", "value": "$variables.currency" }` |
 | Nested key (deep) | dataLayer mapping | `"items.0.item_id"`                                          |
+| Fallback array    | GA4 view_item     | `[{ "key": "data.sku" }, { "key": "data.id" }]`              |
 
 #### Mapping - Structure
 
@@ -92,6 +93,7 @@ npx walkeros serve packages/cli/examples/flow-complete.json --flow web
 | Set (single value)    | Meta ViewContent   | `"content_ids": { "set": ["data.id"] }`                     |
 | Set (multiple values) | Meta settings      | `"external_id": { "set": ["user.device", "user.session"] }` |
 | Direct passthrough    | Meta PageView      | `"data": "data"`                                            |
+| Config-level data     | API destination    | `"data": { "map": { "sent_at": {...} } }`                   |
 
 #### Mapping - Control
 
@@ -175,36 +177,33 @@ npx walkeros serve packages/cli/examples/flow-complete.json --flow web
 
 ---
 
-### Features NOT Used (15)
+### Features NOT Used (6)
 
-#### Requires JavaScript (7)
+#### Now Available via $code: Prefix ✅
 
-These features cannot be used in pure JSON configurations:
+These features are now fully supported in JSON via `$code:` prefix (and ARE used
+in this example):
 
-| Feature                     | Reason                        |
-| --------------------------- | ----------------------------- |
-| `fn:` function              | Requires JavaScript callback  |
-| `condition:`                | Requires JavaScript predicate |
-| Conditional mapping (array) | Requires condition functions  |
-| Custom transformer code     | Requires JavaScript           |
-| Custom source code          | Requires JavaScript           |
-| Custom destination code     | Requires JavaScript           |
-| Event handler callbacks     | Requires JavaScript           |
+| Feature                     | Status                              |
+| --------------------------- | ----------------------------------- |
+| `fn:` function              | ✅ Used via `$code:` in GA4 value   |
+| `condition:`                | ✅ Used via `$code:` in definitions |
+| Conditional mapping (array) | ✅ Used in serverValidator          |
+| Custom transformer code     | ✅ Used in enricher, filter         |
+| Custom destination code     | ✅ Used in debug logger             |
 
-#### Omitted for Clarity (8)
+#### Omitted for Clarity (6)
 
 These features could be added but were omitted to keep the example focused:
 
-| Feature                   | Why Omitted                   |
-| ------------------------- | ----------------------------- |
-| Multiple named flows (3+) | Two flows sufficient for demo |
-| Queue config              | Advanced batching scenario    |
-| Retry config              | Advanced error handling       |
-| Custom fetch options      | API destination advanced      |
-| Dynamic routing           | Requires condition logic      |
-| Transform before send     | Covered by policy             |
-| Custom headers in API     | Would add complexity          |
-| Multiple validators       | One per flow sufficient       |
+| Feature                   | Why Omitted                    |
+| ------------------------- | ------------------------------ |
+| Multiple named flows (3+) | Two flows sufficient for demo  |
+| Queue config              | Advanced batching scenario     |
+| Retry config              | Advanced error handling        |
+| Custom fetch options      | API destination advanced       |
+| Custom headers in API     | Would add complexity           |
+| `validate:` function      | Could add via $code: if needed |
 
 ---
 

package/dist/index.d.ts

@@ -419,4 +419,32 @@ declare function runCommand(mode: string, options: RunCommandOptions): Promise<v
  */
 declare function run(mode: RunMode, options: RunOptions): Promise<RunResult>;
 
-export { type BuildOptions, type BundleStats, type CLIBuildOptions, type GlobalOptions, type MinifyOptions, type RunCommandOptions, type RunMode, type RunOptions, type RunResult, type SimulationResult, bundle, bundleCommand, pushCommand, run, runCommand, simulate, simulateCommand };
+type ValidationType = 'event' | 'flow' | 'mapping';
+interface ValidationError {
+    path: string;
+    message: string;
+    value?: unknown;
+    code?: string;
+}
+interface ValidationWarning {
+    path: string;
+    message: string;
+    suggestion?: string;
+}
+interface ValidateResult {
+    valid: boolean;
+    type: ValidationType;
+    errors: ValidationError[];
+    warnings: ValidationWarning[];
+    details: Record<string, unknown>;
+}
+
+/**
+ * Programmatic API for validation.
+ * Can be called directly from code or MCP server.
+ */
+declare function validate(type: ValidationType, input: unknown, options?: {
+    flow?: string;
+}): Promise<ValidateResult>;
+
+export { type BuildOptions, type BundleStats, type CLIBuildOptions, type GlobalOptions, type MinifyOptions, type RunCommandOptions, type RunMode, type RunOptions, type RunResult, type SimulationResult, type ValidateResult, type ValidationError, type ValidationType, type ValidationWarning, bundle, bundleCommand, pushCommand, run, runCommand, simulate, simulateCommand, validate };

package/dist/index.js

@@ -2,7 +2,7 @@
 
 // src/index.ts
 import { Command } from "commander";
-import chalk2 from "chalk";
+import chalk3 from "chalk";
 
 // src/version.ts
 import { readFileSync } from "fs";
@@ -2905,6 +2905,288 @@ async function run(mode, options) {
   }
 }
 
+// src/commands/validate/index.ts
+import chalk2 from "chalk";
+
+// src/commands/validate/validators/event.ts
+import { schemas as schemas3 } from "@walkeros/core/dev";
+var { PartialEventSchema } = schemas3;
+function validateEvent(input) {
+  const errors = [];
+  const warnings = [];
+  const details = {};
+  const event = typeof input === "object" && input !== null ? 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(" ")) {
+      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 {
+      const parts = name.trim().split(/\s+/);
+      const action = parts.pop();
+      const entity = parts.join(" ");
+      details.entity = entity;
+      details.action = action;
+    }
+  }
+  const zodResult = PartialEventSchema.safeParse(input);
+  if (!zodResult.success) {
+    for (const issue of zodResult.error.issues) {
+      const path14 = issue.path.join(".");
+      if (path14 === "name") continue;
+      errors.push({
+        path: path14 || "root",
+        message: issue.message,
+        code: "SCHEMA_VALIDATION"
+      });
+    }
+  }
+  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,
+    type: "event",
+    errors,
+    warnings,
+    details
+  };
+}
+
+// src/commands/validate/validators/flow.ts
+import { schemas as schemas4 } from "@walkeros/core/dev";
+var { SetupSchema } = schemas4;
+function validateFlow(input, options = {}) {
+  const errors = [];
+  const warnings = [];
+  const details = {};
+  const config = typeof input === "object" && input !== null ? input : {};
+  const zodResult = SetupSchema.safeParse(input);
+  if (!zodResult.success) {
+    for (const issue of zodResult.error.issues) {
+      const path14 = issue.path.join(".");
+      errors.push({
+        path: path14 || "root",
+        message: issue.message,
+        code: "SCHEMA_VALIDATION"
+      });
+    }
+  }
+  const flows = config.flows;
+  if (flows && typeof flows === "object" && Object.keys(flows).length === 0) {
+    errors.push({
+      path: "flows",
+      message: "At least one flow is required",
+      code: "EMPTY_FLOWS"
+    });
+  }
+  if (flows && typeof flows === "object") {
+    const flowNames = Object.keys(flows);
+    details.flowNames = flowNames;
+    details.flowCount = flowNames.length;
+    if (options.flow) {
+      if (!flowNames.includes(options.flow)) {
+        errors.push({
+          path: "flows",
+          message: `Flow "${options.flow}" not found. Available: ${flowNames.join(", ")}`,
+          code: "FLOW_NOT_FOUND"
+        });
+      } else {
+        details.validatedFlow = options.flow;
+      }
+    }
+  }
+  const packages = config.packages;
+  if (packages && typeof packages === "object") {
+    for (const [pkgName, pkgConfig] of Object.entries(packages)) {
+      if (!pkgConfig.version && !pkgConfig.path) {
+        warnings.push({
+          path: `packages.${pkgName}`,
+          message: `Package "${pkgName}" has no version specified`,
+          suggestion: "Consider specifying a version for reproducible builds"
+        });
+      }
+    }
+    details.packageCount = Object.keys(packages).length;
+  }
+  return {
+    valid: errors.length === 0,
+    type: "flow",
+    errors,
+    warnings,
+    details
+  };
+}
+
+// src/commands/validate/validators/mapping.ts
+function validateMapping(input) {
+  const errors = [];
+  const warnings = [];
+  const details = {};
+  if (typeof input !== "object" || input === null || Array.isArray(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 patterns = Object.keys(mapping);
+  details.eventPatterns = patterns;
+  details.patternCount = patterns.length;
+  patterns.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 !== patterns.length - 1) {
+      warnings.push({
+        path: "*",
+        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/index.ts
+async function validate(type, input, options = {}) {
+  switch (type) {
+    case "event":
+      return validateEvent(input);
+    case "flow":
+      return validateFlow(input, { flow: options.flow });
+    case "mapping":
+      return validateMapping(input);
+    default:
+      throw new Error(`Unknown validation type: ${type}`);
+  }
+}
+function formatResult(result, options) {
+  if (options.json) {
+    return JSON.stringify(result, null, 2);
+  }
+  const lines = [];
+  lines.push("");
+  lines.push(`Validating ${result.type}...`);
+  lines.push("");
+  if (options.verbose && Object.keys(result.details).length > 0) {
+    lines.push("Details:");
+    for (const [key, value] of Object.entries(result.details)) {
+      lines.push(`  ${key}: ${JSON.stringify(value)}`);
+    }
+    lines.push("");
+  }
+  lines.push("Validation Results:");
+  for (const error of result.errors) {
+    lines.push(chalk2.red(`  \u2717 ${error.path}: ${error.message}`));
+  }
+  for (const warning of result.warnings) {
+    lines.push(chalk2.yellow(`  \u26A0 ${warning.path}: ${warning.message}`));
+    if (warning.suggestion) {
+      lines.push(chalk2.gray(`    \u2192 ${warning.suggestion}`));
+    }
+  }
+  if (result.valid) {
+    lines.push(chalk2.green(`  \u2713 All checks passed`));
+  }
+  lines.push("");
+  lines.push(
+    `Summary: ${result.errors.length} error(s), ${result.warnings.length} warning(s)`
+  );
+  return lines.join("\n");
+}
+async function validateCommand(options) {
+  const logger2 = createCommandLogger(options);
+  try {
+    const input = await loadJsonFromSource(options.input, {
+      name: options.type,
+      required: true
+    });
+    const result = await validate(options.type, input, {
+      flow: options.flow
+    });
+    const output = formatResult(result, {
+      json: options.json,
+      verbose: options.verbose
+    });
+    if (options.json) {
+      console.log(output);
+    } else {
+      logger2.log(output);
+    }
+    if (!result.valid) {
+      process.exit(1);
+    }
+    if (options.strict && result.warnings.length > 0) {
+      process.exit(2);
+    }
+    process.exit(0);
+  } catch (error) {
+    const errorMessage = getErrorMessage(error);
+    if (options.json) {
+      logger2.json({
+        valid: false,
+        type: options.type,
+        errors: [{ path: "input", message: errorMessage, code: "INPUT_ERROR" }],
+        warnings: [],
+        details: {}
+      });
+    } else {
+      logger2.error(`Error: ${errorMessage}`);
+    }
+    process.exit(3);
+  }
+}
+
 // src/commands/cache.ts
 import fs13 from "fs-extra";
 function registerCacheCommand(program2) {
@@ -2955,7 +3237,7 @@ program.name("walkeros").description("walkerOS CLI - Bundle and deploy walkerOS
 program.hook("preAction", (thisCommand, actionCommand) => {
   const options = actionCommand.opts();
   if (!options.silent && !options.json) {
-    console.log(`${chalk2.hex("#01b5e2")("walkerOS")} v${VERSION}`);
+    console.log(`${chalk3.hex("#01b5e2")("walkerOS")} v${VERSION}`);
   }
 });
 program.command("bundle [file]").description("Bundle NPM packages with custom code").option("--flow <name>", "flow name for multi-flow configs").option("--all", "build all flows for multi-flow configs").option("--stats", "show bundle statistics").option("--json", "output as JSON (implies --stats)").option("--no-cache", "disable package caching").option("-v, --verbose", "verbose output").option("-s, --silent", "suppress output").option(
@@ -3002,6 +3284,17 @@ program.command("push [file]").description("Push an event through the flow with
     silent: options.silent
   });
 });
+program.command("validate <type> [input]").description("Validate event, flow, or mapping configuration").option("--flow <name>", "flow name for multi-flow configs").option("--json", "output as JSON").option("-v, --verbose", "verbose output").option("-s, --silent", "suppress output").option("--strict", "fail on warnings").action(async (type, input, options) => {
+  await validateCommand({
+    type,
+    input,
+    flow: options.flow,
+    json: options.json,
+    verbose: options.verbose,
+    silent: options.silent,
+    strict: options.strict
+  });
+});
 var runCmd = program.command("run").description("Run walkerOS flows in collect or serve mode");
 runCmd.command("collect [file]").description(
   "Run collector mode (event collection endpoint). Defaults to server-collect.mjs if no file specified."
@@ -3039,6 +3332,7 @@ export {
   run,
   runCommand,
   simulate,
-  simulateCommand
+  simulateCommand,
+  validate
 };
 //# sourceMappingURL=index.js.map