@constela/cli 0.3.30 → 0.4.1

package/README.md

@@ -30,6 +30,10 @@ constela compile <input> [options]
 **Options:**
 - `-o, --out <path>` - Output file path
 - `--pretty` - Pretty-print JSON output
+- `--json` - Output results as JSON (for tooling/AI integration)
+- `-w, --watch` - Watch input file and recompile on changes
+- `-v, --verbose` - Show detailed compilation progress
+- `--debug` - Show internal debug information
 
 **Examples:**
 
@@ -42,6 +46,114 @@ constela compile app.json --out dist/app.compiled.json
 
 # Pretty-print output
 constela compile app.json --pretty
+
+# JSON output for AI tools
+constela compile app.json --json
+
+# Watch mode for development
+constela compile app.json --watch
+
+# Verbose output with timing
+constela compile app.json --verbose
+# Output:
+# [1/3] Validating schema... OK (2ms)
+# [2/3] Analyzing semantics... OK (1ms)
+# [3/3] Transforming AST... OK (0ms)
+# Compilation successful (5ms total)
+
+# Debug information
+constela compile app.json --debug
+# Output:
+# [DEBUG] Input file: app.json (1234 bytes)
+# [DEBUG] Parse time: 1ms
+# [DEBUG] Validate pass: 15 nodes validated (2ms)
+# ...
+```
+
+### constela validate
+
+Validates Constela JSON files without full compilation (faster feedback).
+
+```bash
+constela validate [input] [options]
+```
+
+**Arguments:**
+- `[input]` - Input DSL file (JSON) or directory with `--all`
+
+**Options:**
+- `-a, --all` - Validate all JSON files in directory recursively
+- `--json` - Output results as JSON
+
+**Examples:**
+
+```bash
+# Validate single file
+constela validate app.json
+
+# Validate all JSON files in directory
+constela validate --all src/routes/
+
+# JSON output for tooling
+constela validate app.json --json
+```
+
+**Error Output with Suggestions:**
+
+```
+Error [UNDEFINED_STATE] at /view/children/0/value/name
+
+  Undefined state reference: 'count'
+
+  Did you mean 'counter'?
+```
+
+### constela inspect
+
+Inspects Constela program structure without compilation.
+
+```bash
+constela inspect <input> [options]
+```
+
+**Arguments:**
+- `<input>` - Input DSL file (JSON)
+
+**Options:**
+- `--state` - Show only state information
+- `--actions` - Show only actions information
+- `--components` - Show only components information
+- `--view` - Show only view tree
+- `--json` - Output as JSON
+
+**Examples:**
+
+```bash
+# Show all program structure
+constela inspect app.json
+
+# Show only state
+constela inspect app.json --state
+
+# JSON output
+constela inspect app.json --json
+```
+
+**Output:**
+
+```
+State (2 fields):
+  count: number = 0
+  items: list = []
+
+Actions (2):
+  increment: update count +1
+  addItem: push to items
+
+View Tree:
+  element<div>
+    text: state.count
+    element<button> onClick=increment
 ```
 
 ### constela dev
@@ -156,6 +268,77 @@ export default {
 } satisfies ConstelaConfig;
 ```
 
+## Debugging Guide
+
+### Using Debug Mode
+
+Add `--debug` to any compile command to see internal processing:
+
+```bash
+constela compile app.json --debug
+```
+
+**Debug output includes:**
+- File size and parse time
+- Number of nodes validated
+- Analysis pass details
+- Transform timings
+
+### Common Issues
+
+#### UNDEFINED_STATE Error
+
+```
+Error [UNDEFINED_STATE] at /view/children/0/value/name
+Undefined state reference: 'count'
+Did you mean 'counter'?
+```
+
+**Solution:** Check your state name spelling. The error shows suggested corrections.
+
+#### SCHEMA_INVALID Error
+
+```
+Error [SCHEMA_INVALID] at /view/kind
+Invalid value: 'button'. Expected one of: element, text, if, each, component, slot, markdown, code
+```
+
+**Solution:** Use correct node kind. `kind: "element"` with `tag: "button"` for buttons.
+
+#### Component Not Found
+
+```
+Error [COMPONENT_NOT_FOUND] at /view/children/0/name
+Component 'Header' is not defined
+```
+
+**Solution:** Define the component in the `components` section or check import paths.
+
+### Inspecting Program Structure
+
+Use `inspect` to understand your program without compilation:
+
+```bash
+# See state structure
+constela inspect app.json --state
+
+# See view tree
+constela inspect app.json --view
+
+# Get JSON for tooling
+constela inspect app.json --json | jq '.state'
+```
+
+### Browser DevTools
+
+For runtime debugging:
+
+1. Open DevTools → Sources tab
+2. Find `@constela/runtime` in the source tree
+3. Set breakpoints in action handlers
+
+State changes are logged to console in development mode.
+
 ## Exit Codes
 
 | Code | Description |

package/dist/index.js

@@ -4,9 +4,213 @@
 import { Command } from "commander";
 
 // src/commands/compile.ts
-import { compile } from "@constela/compiler";
-import { readFileSync, writeFileSync, mkdirSync, statSync } from "fs";
+import { validatePass, analyzePass, transformPass } from "@constela/compiler";
+import { ConstelaError } from "@constela/core";
+import { readFileSync, writeFileSync, mkdirSync, statSync, watch as fsWatch } from "fs";
 import { dirname, basename, join } from "path";
+function shouldUseColors() {
+  if (process.env["NO_COLOR"] !== void 0) {
+    return false;
+  }
+  if (process.env["FORCE_COLOR"] === "1") {
+    return true;
+  }
+  return process.stdout.isTTY === true;
+}
+var colors = {
+  red: (s) => `\x1B[31m${s}\x1B[0m`,
+  green: (s) => `\x1B[32m${s}\x1B[0m`,
+  yellow: (s) => `\x1B[33m${s}\x1B[0m`,
+  reset: "\x1B[0m"
+};
+function getColors() {
+  if (shouldUseColors()) {
+    return colors;
+  }
+  return {
+    red: (s) => s,
+    green: (s) => s,
+    yellow: (s) => s,
+    reset: ""
+  };
+}
+function countViewNodes(node) {
+  let count = 1;
+  switch (node.kind) {
+    case "element":
+      if (node.children) {
+        for (const child of node.children) {
+          count += countViewNodes(child);
+        }
+      }
+      break;
+    case "if":
+      count += countViewNodes(node.then);
+      if (node.else) {
+        count += countViewNodes(node.else);
+      }
+      break;
+    case "each":
+      count += countViewNodes(node.template);
+      break;
+    // text, markdown, code, slot nodes have no children
+    default:
+      break;
+  }
+  return count;
+}
+function createVerboseLogger(enabled, c) {
+  if (!enabled) {
+    return {
+      phaseStart: () => {
+      },
+      phaseOk: () => {
+      },
+      phaseFail: () => {
+      },
+      detail: () => {
+      },
+      summary: () => {
+      }
+    };
+  }
+  return {
+    phaseStart(phase, total, message) {
+      process.stdout.write(`[${phase}/${total}] ${message}...`);
+    },
+    phaseOk(phase, total, message, durationMs) {
+      console.log(`[${phase}/${total}] ${message}... ${c.green("OK")} (${durationMs}ms)`);
+    },
+    phaseFail(phase, total, message) {
+      console.log(`[${phase}/${total}] ${message}... ${c.red("FAILED")}`);
+    },
+    detail(message) {
+      console.log(`  ${message}`);
+    },
+    summary(states, actions, viewNodes, totalMs) {
+      console.log("");
+      console.log("Summary:");
+      console.log(`  States: ${states}`);
+      console.log(`  Actions: ${actions}`);
+      console.log(`  View nodes: ${viewNodes}`);
+      console.log("");
+      console.log(`${c.green("Compilation successful")} (${totalMs}ms total)`);
+    }
+  };
+}
+function createDebugLogger(enabled) {
+  if (!enabled) {
+    return {
+      inputFile: () => {
+      },
+      parseTime: () => {
+      },
+      validatePass: () => {
+      },
+      analyzePass: () => {
+      },
+      transformPass: () => {
+      },
+      getInfo: () => void 0
+    };
+  }
+  const info = {
+    inputFile: "",
+    inputSize: 0,
+    parseTime: 0,
+    validateTime: 0,
+    analyzeTime: 0,
+    transformTime: 0,
+    nodesValidated: 0,
+    stateCount: 0,
+    actionCount: 0,
+    viewNodeCount: 0,
+    outputSize: 0
+  };
+  return {
+    inputFile(filename, size) {
+      info.inputFile = filename;
+      info.inputSize = size;
+      console.log(`[DEBUG] Input file: ${filename} (${size} bytes)`);
+    },
+    parseTime(ms) {
+      info.parseTime = ms;
+      console.log(`[DEBUG] Parse time: ${ms}ms`);
+    },
+    validatePass(nodes, ms) {
+      info.nodesValidated = nodes;
+      info.validateTime = ms;
+      console.log(`[DEBUG] Validate pass: ${nodes} nodes validated (${ms}ms)`);
+    },
+    analyzePass(states, actions, views, ms) {
+      info.stateCount = states;
+      info.actionCount = actions;
+      info.viewNodeCount = views;
+      info.analyzeTime = ms;
+      console.log(`[DEBUG] Analyze pass: ${states} states, ${actions} actions, ${views} views (${ms}ms)`);
+    },
+    transformPass(outputSize, ms) {
+      info.outputSize = outputSize;
+      info.transformTime = ms;
+      console.log(`[DEBUG] Transform pass: output size ${outputSize} bytes (${ms}ms)`);
+    },
+    getInfo() {
+      return info;
+    }
+  };
+}
+function buildDebugInfo(inputFile, inputSize, parseTime, validateTime, analyzeTime, transformTime, nodesValidated, stateCount, actionCount, viewNodeCount, outputSize) {
+  return {
+    inputFile,
+    inputSize,
+    parseTime,
+    validateTime,
+    analyzeTime,
+    transformTime,
+    nodesValidated,
+    stateCount,
+    actionCount,
+    viewNodeCount,
+    outputSize
+  };
+}
+function countAstNodes(ast) {
+  let count = 1;
+  count += Object.keys(ast.state).length;
+  for (const action of ast.actions) {
+    count += 1;
+    count += action.steps.length;
+  }
+  count += countViewNodesFromAst(ast.view);
+  if (ast.components) {
+    for (const key of Object.keys(ast.components)) {
+      const comp = ast.components[key];
+      if (comp) {
+        count += 1;
+        count += countViewNodesFromAst(comp.view);
+      }
+    }
+  }
+  return count;
+}
+function countViewNodesFromAst(node) {
+  let count = 1;
+  if ("children" in node && Array.isArray(node.children)) {
+    for (const child of node.children) {
+      count += countViewNodesFromAst(child);
+    }
+  }
+  if ("then" in node && node.then) {
+    count += countViewNodesFromAst(node.then);
+  }
+  if ("else" in node && node.else) {
+    count += countViewNodesFromAst(node.else);
+  }
+  if ("template" in node && node.template) {
+    count += countViewNodesFromAst(node.template);
+  }
+  return count;
+}
 function getOutputPath(inputPath, options) {
   if (options.out) {
     return options.out;
@@ -19,64 +223,849 @@ function getOutputPath(inputPath, options) {
   }
   return join(dir, `${base}.compiled.json`);
 }
-async function compileCommand(inputPath, options) {
+function formatColoredError(error, c) {
+  const lines = [];
+  const pathInfo = error.path ? ` at ${error.path}` : "";
+  lines.push(`Error [${c.red(error.code)}]: ${error.message}${pathInfo}`);
+  if (error.suggestion) {
+    lines.push(`  ${c.yellow(`Did you mean: ${error.suggestion}`)}`);
+  }
+  return lines.join("\n");
+}
+function errorToJson(error) {
+  const result = {
+    code: error.code,
+    message: error.message
+  };
+  if (error.path !== void 0) {
+    result.path = error.path;
+  }
+  if (error.suggestion !== void 0) {
+    result.suggestion = error.suggestion;
+  }
+  if (error.context !== void 0) {
+    result.context = error.context;
+  }
+  return result;
+}
+function outputJson(output) {
+  console.log(JSON.stringify(output));
+}
+function performCompilation(inputPath, options, c) {
+  const startTime = performance.now();
+  const verbose = createVerboseLogger(options.verbose === true, c);
+  const isJsonMode = options.json === true;
+  const debug = createDebugLogger(options.debug === true && !isJsonMode);
+  let inputSize;
   try {
     const stat = statSync(inputPath);
     if (!stat.isFile()) {
-      console.error(`Error: Input path is not a regular file: ${inputPath}`);
-      process.exit(1);
+      return {
+        ok: false,
+        errors: [new ConstelaError("SCHEMA_INVALID", `Input path is not a regular file: ${inputPath}`)],
+        duration: Math.round(performance.now() - startTime)
+      };
     }
+    inputSize = stat.size;
   } catch (err) {
     const error = err;
-    if (error.code === "ENOENT") {
-      console.error(`Error: File not found: ${inputPath}`);
-    } else {
-      console.error(`Error: Could not access file: ${inputPath} - ${error.message}`);
-    }
-    process.exit(1);
+    const message = error.code === "ENOENT" ? `File not found: ${inputPath}` : `Could not access file: ${inputPath} - ${error.message}`;
+    return {
+      ok: false,
+      errors: [new ConstelaError("SCHEMA_INVALID", message)],
+      duration: Math.round(performance.now() - startTime)
+    };
   }
+  debug.inputFile(basename(inputPath), inputSize);
   let fileContent;
   try {
     fileContent = readFileSync(inputPath, "utf-8");
   } catch (err) {
     const error = err;
-    console.error(`Error: Could not read file: ${inputPath} - ${error.message}`);
-    process.exit(1);
+    return {
+      ok: false,
+      errors: [new ConstelaError("SCHEMA_INVALID", `Could not read file: ${inputPath} - ${error.message}`)],
+      duration: Math.round(performance.now() - startTime)
+    };
   }
+  const parseStart = performance.now();
   let inputJson;
   try {
     inputJson = JSON.parse(fileContent);
   } catch (err) {
     const error = err;
-    console.error(`Error: Invalid JSON: ${error.message}`);
-    process.exit(1);
+    return {
+      ok: false,
+      errors: [new ConstelaError("SCHEMA_INVALID", `Invalid JSON: ${error.message}`)],
+      duration: Math.round(performance.now() - startTime)
+    };
   }
-  const result = compile(inputJson);
-  if (!result.ok) {
-    for (const error of result.errors) {
-      const pathInfo = error.path ? ` at ${error.path}` : "";
-      console.error(`Error [${error.code}]: ${error.message}${pathInfo}`);
-    }
-    process.exit(1);
+  const parseDuration = Math.round(performance.now() - parseStart);
+  debug.parseTime(parseDuration);
+  const phase1Start = performance.now();
+  const validateResult = validatePass(inputJson);
+  const phase1Duration = Math.round(performance.now() - phase1Start);
+  if (!validateResult.ok) {
+    verbose.phaseFail(1, 3, "Validating schema");
+    return {
+      ok: false,
+      errors: [validateResult.error],
+      duration: Math.round(performance.now() - startTime)
+    };
   }
+  verbose.phaseOk(1, 3, "Validating schema", phase1Duration);
+  const ast = validateResult.ast;
+  const nodesValidated = countAstNodes(ast);
+  debug.validatePass(nodesValidated, phase1Duration);
+  const phase2Start = performance.now();
+  const stateNames = Object.keys(ast.state);
+  const actionNames = ast.actions.map((a) => a.name);
+  verbose.detail(`Collecting state names: ${stateNames.join(", ")}`);
+  verbose.detail(`Collecting action names: ${actionNames.join(", ")}`);
+  verbose.detail("Validating view tree");
+  const analyzeResult = analyzePass(ast);
+  const phase2Duration = Math.round(performance.now() - phase2Start);
+  if (!analyzeResult.ok) {
+    verbose.phaseFail(2, 3, "Analyzing semantics");
+    return {
+      ok: false,
+      errors: analyzeResult.errors,
+      duration: Math.round(performance.now() - startTime)
+    };
+  }
+  verbose.phaseOk(2, 3, "Analyzing semantics", phase2Duration);
+  const phase3Start = performance.now();
+  const program2 = transformPass(analyzeResult.ast, analyzeResult.context);
+  const phase3Duration = Math.round(performance.now() - phase3Start);
+  verbose.phaseOk(3, 3, "Transforming AST", phase3Duration);
+  const viewNodeCount = countViewNodes(program2.view);
+  debug.analyzePass(stateNames.length, actionNames.length, viewNodeCount, phase2Duration);
   const outputPath = getOutputPath(inputPath, options);
   const outputDir = dirname(outputPath);
   try {
     mkdirSync(outputDir, { recursive: true });
   } catch (err) {
     const error = err;
-    console.error(`Error: Could not create output directory: ${outputDir} - ${error.message}`);
-    process.exit(1);
+    return {
+      ok: false,
+      errors: [new ConstelaError("SCHEMA_INVALID", `Could not create output directory: ${outputDir} - ${error.message}`)],
+      duration: Math.round(performance.now() - startTime)
+    };
   }
-  const outputContent = options.pretty ? JSON.stringify(result.program, null, 2) : JSON.stringify(result.program);
+  const outputContent = options.pretty ? JSON.stringify(program2, null, 2) : JSON.stringify(program2);
   try {
     writeFileSync(outputPath, outputContent, "utf-8");
   } catch (err) {
     const error = err;
-    console.error(`Error: Could not write output file: ${outputPath} - ${error.message}`);
+    return {
+      ok: false,
+      errors: [new ConstelaError("SCHEMA_INVALID", `Could not write output file: ${outputPath} - ${error.message}`)],
+      duration: Math.round(performance.now() - startTime)
+    };
+  }
+  const outputSize = outputContent.length;
+  debug.transformPass(outputSize, phase3Duration);
+  const totalDuration = Math.round(performance.now() - startTime);
+  verbose.summary(stateNames.length, actionNames.length, viewNodeCount, totalDuration);
+  const result = {
+    ok: true,
+    outputPath,
+    duration: totalDuration
+  };
+  if (options.debug) {
+    result.debugInfo = buildDebugInfo(
+      basename(inputPath),
+      inputSize,
+      parseDuration,
+      phase1Duration,
+      phase2Duration,
+      phase3Duration,
+      nodesValidated,
+      stateNames.length,
+      actionNames.length,
+      viewNodeCount,
+      outputSize
+    );
+  }
+  return result;
+}
+function outputResult(inputPath, result, options, c) {
+  const isJsonMode = options.json === true;
+  if (result.ok) {
+    if (isJsonMode) {
+      const output = {
+        success: true,
+        inputFile: basename(inputPath),
+        outputFile: basename(result.outputPath),
+        diagnostics: { duration: result.duration }
+      };
+      if (result.debugInfo) {
+        output.debug = result.debugInfo;
+      }
+      outputJson(output);
+    } else if (!options.verbose) {
+      console.log(`${c.green("\u2713")} Compiled ${inputPath} \u2192 ${result.outputPath}`);
+    }
+  } else {
+    if (isJsonMode) {
+      const output = {
+        success: false,
+        errors: result.errors.map(errorToJson),
+        diagnostics: { duration: result.duration }
+      };
+      outputJson(output);
+    } else {
+      for (const error of result.errors) {
+        console.error(formatColoredError(error, c));
+      }
+    }
+  }
+}
+async function compileCommand(inputPath, options) {
+  const isJsonMode = options.json === true;
+  const c = isJsonMode ? { red: (s) => s, green: (s) => s, yellow: (s) => s, reset: "" } : getColors();
+  const result = performCompilation(inputPath, options, c);
+  outputResult(inputPath, result, options, c);
+  if (!options.watch) {
+    if (!result.ok) {
+      process.exit(1);
+    }
+    return;
+  }
+  console.log("[Watching for changes...]");
+  const watcher = fsWatch(inputPath, (eventType) => {
+    if (eventType === "change") {
+      console.log(`[File changed: ${inputPath}]`);
+      const watchResult = performCompilation(inputPath, options, c);
+      outputResult(inputPath, watchResult, options, c);
+      console.log("[Watching for changes...]");
+    }
+  });
+  process.on("SIGINT", () => {
+    watcher.close();
+    console.log("\n[Watch mode stopped]");
+    process.exit(0);
+  });
+  await new Promise(() => {
+  });
+}
+
+// src/commands/validate.ts
+import { validatePass as validatePass2, analyzePass as analyzePass2 } from "@constela/compiler";
+import { ConstelaError as ConstelaError2 } from "@constela/core";
+import { readFileSync as readFileSync2, readdirSync, statSync as statSync2 } from "fs";
+import { join as join2, basename as basename2 } from "path";
+function shouldUseColors2() {
+  if (process.env["NO_COLOR"] !== void 0) {
+    return false;
+  }
+  if (process.env["FORCE_COLOR"] === "1") {
+    return true;
+  }
+  return process.stdout.isTTY === true;
+}
+var colors2 = {
+  red: (s) => `\x1B[31m${s}\x1B[0m`,
+  green: (s) => `\x1B[32m${s}\x1B[0m`,
+  yellow: (s) => `\x1B[33m${s}\x1B[0m`,
+  reset: "\x1B[0m"
+};
+function getColors2() {
+  if (shouldUseColors2()) {
+    return colors2;
+  }
+  return {
+    red: (s) => s,
+    green: (s) => s,
+    yellow: (s) => s,
+    reset: ""
+  };
+}
+function formatColoredError2(error, c) {
+  const lines = [];
+  const pathInfo = error.path ? ` at ${error.path}` : "";
+  lines.push(`Error [${c.red(error.code)}]: ${error.message}${pathInfo}`);
+  if (error.suggestion) {
+    lines.push(`  ${c.yellow(`Suggestion: ${error.suggestion}`)}`);
+  }
+  return lines.join("\n");
+}
+function errorToJson2(error) {
+  const result = {
+    code: error.code,
+    message: error.message
+  };
+  if (error.path !== void 0) {
+    result.path = error.path;
+  }
+  if (error.suggestion !== void 0) {
+    result.suggestion = error.suggestion;
+  }
+  if (error.context !== void 0) {
+    result.context = error.context;
+  }
+  return result;
+}
+function outputJson2(output) {
+  console.log(JSON.stringify(output));
+}
+function findJsonFiles(dir) {
+  const files = [];
+  const entries = readdirSync(dir);
+  for (const entry of entries) {
+    const fullPath = join2(dir, entry);
+    const stat = statSync2(fullPath);
+    if (stat.isDirectory()) {
+      files.push(...findJsonFiles(fullPath));
+    } else if (stat.isFile() && entry.endsWith(".json")) {
+      files.push(fullPath);
+    }
+  }
+  return files;
+}
+function validateSingleFile(filePath) {
+  let fileContent;
+  try {
+    fileContent = readFileSync2(filePath, "utf-8");
+  } catch (err) {
+    const error = err;
+    if (error.code === "ENOENT") {
+      return {
+        valid: false,
+        errors: [new ConstelaError2("SCHEMA_INVALID", `File not found: ${filePath}`)]
+      };
+    }
+    return {
+      valid: false,
+      errors: [new ConstelaError2("SCHEMA_INVALID", `Could not read file: ${filePath} - ${error.message}`)]
+    };
+  }
+  let inputJson;
+  try {
+    inputJson = JSON.parse(fileContent);
+  } catch (err) {
+    const error = err;
+    return {
+      valid: false,
+      errors: [new ConstelaError2("SCHEMA_INVALID", `Invalid JSON: ${error.message}`)]
+    };
+  }
+  const validateResult = validatePass2(inputJson);
+  if (!validateResult.ok) {
+    return {
+      valid: false,
+      errors: [validateResult.error]
+    };
+  }
+  const analyzeResult = analyzePass2(validateResult.ast);
+  if (!analyzeResult.ok) {
+    return {
+      valid: false,
+      errors: analyzeResult.errors
+    };
+  }
+  return {
+    valid: true,
+    errors: []
+  };
+}
+async function validateCommand(input, options) {
+  const startTime = performance.now();
+  const isJsonMode = options.json === true;
+  const isAllMode = options.all === true;
+  const c = isJsonMode ? { red: (s) => s, green: (s) => s, yellow: (s) => s, reset: "" } : getColors2();
+  function exitWithResult(success, output) {
+    if (isJsonMode && output) {
+      outputJson2(output);
+    }
+    process.exit(success ? 0 : 1);
+  }
+  if (isAllMode) {
+    const dirPath = input ?? ".";
+    try {
+      const stat = statSync2(dirPath);
+      if (!stat.isDirectory()) {
+        const duration3 = Math.round(performance.now() - startTime);
+        if (isJsonMode) {
+          exitWithResult(false, {
+            success: false,
+            errors: [{ code: "SCHEMA_INVALID", message: `Not a directory: ${dirPath}` }],
+            diagnostics: { duration: duration3 }
+          });
+        } else {
+          console.error(`Error: Not a directory: ${dirPath}`);
+          process.exit(1);
+        }
+      }
+    } catch (err) {
+      const duration3 = Math.round(performance.now() - startTime);
+      if (isJsonMode) {
+        exitWithResult(false, {
+          success: false,
+          errors: [{ code: "SCHEMA_INVALID", message: `Directory not found: ${dirPath}` }],
+          diagnostics: { duration: duration3 }
+        });
+      } else {
+        console.error(`Error: Directory not found: ${dirPath}`);
+        process.exit(1);
+      }
+    }
+    const jsonFiles = findJsonFiles(dirPath);
+    const validatedCount = jsonFiles.length;
+    const fileErrors = [];
+    const validFiles = [];
+    for (const filePath of jsonFiles) {
+      const result2 = validateSingleFile(filePath);
+      const fileName2 = basename2(filePath);
+      if (result2.valid) {
+        validFiles.push(fileName2);
+      } else {
+        fileErrors.push({
+          file: fileName2,
+          errors: result2.errors.map(errorToJson2)
+        });
+        if (!isJsonMode) {
+          console.error(`
+${c.red("Error")} in ${fileName2}:`);
+          for (const error of result2.errors) {
+            console.error(formatColoredError2(error, c));
+          }
+        }
+      }
+    }
+    const duration2 = Math.round(performance.now() - startTime);
+    const hasErrors = fileErrors.length > 0;
+    if (isJsonMode) {
+      if (hasErrors) {
+        const output = {
+          success: false,
+          files: fileErrors,
+          validatedCount,
+          diagnostics: { duration: duration2 }
+        };
+        exitWithResult(false, output);
+      } else {
+        const output = {
+          success: true,
+          files: validFiles,
+          validatedCount,
+          diagnostics: { duration: duration2 }
+        };
+        exitWithResult(true, output);
+      }
+    } else {
+      if (hasErrors) {
+        console.log(`
+Validated ${validatedCount} files with errors`);
+        process.exit(1);
+      } else {
+        console.log(`${c.green("OK")} Validated ${validatedCount} files successfully`);
+        process.exit(0);
+      }
+    }
+  }
+  if (!input) {
+    const duration2 = Math.round(performance.now() - startTime);
+    if (isJsonMode) {
+      exitWithResult(false, {
+        success: false,
+        errors: [{ code: "SCHEMA_INVALID", message: "No input file specified" }],
+        diagnostics: { duration: duration2 }
+      });
+    } else {
+      console.error("Error: No input file specified");
+      process.exit(1);
+    }
+  }
+  const result = validateSingleFile(input);
+  const duration = Math.round(performance.now() - startTime);
+  const fileName = basename2(input);
+  if (result.valid) {
+    if (isJsonMode) {
+      const output = {
+        success: true,
+        file: fileName,
+        validatedCount: 1,
+        diagnostics: { duration }
+      };
+      exitWithResult(true, output);
+    } else {
+      console.log(`${c.green("OK")} ${input} is valid`);
+      process.exit(0);
+    }
+  } else {
+    if (isJsonMode) {
+      const output = {
+        success: false,
+        file: fileName,
+        errors: result.errors.map(errorToJson2),
+        diagnostics: { duration }
+      };
+      exitWithResult(false, output);
+    } else {
+      for (const error of result.errors) {
+        console.error(formatColoredError2(error, c));
+      }
+      process.exit(1);
+    }
+  }
+}
+
+// src/commands/inspect.ts
+import { readFileSync as readFileSync3 } from "fs";
+function shouldUseColors3() {
+  if (process.env["NO_COLOR"] !== void 0) {
+    return false;
+  }
+  if (process.env["FORCE_COLOR"] === "1") {
+    return true;
+  }
+  return process.stdout.isTTY === true;
+}
+var colors3 = {
+  red: (s) => `\x1B[31m${s}\x1B[0m`,
+  green: (s) => `\x1B[32m${s}\x1B[0m`,
+  yellow: (s) => `\x1B[33m${s}\x1B[0m`,
+  cyan: (s) => `\x1B[36m${s}\x1B[0m`,
+  dim: (s) => `\x1B[2m${s}\x1B[0m`,
+  reset: "\x1B[0m"
+};
+function getColors3() {
+  if (shouldUseColors3()) {
+    return colors3;
+  }
+  return {
+    red: (s) => s,
+    green: (s) => s,
+    yellow: (s) => s,
+    cyan: (s) => s,
+    dim: (s) => s,
+    reset: ""
+  };
+}
+function summarizeStep(step) {
+  switch (step.do) {
+    case "set":
+      return `set ${step.target}`;
+    case "update":
+      return `${step.operation} ${step.target}`;
+    case "fetch":
+      return "fetch";
+    case "storage":
+      return `storage ${step.operation}`;
+    case "clipboard":
+      return `clipboard ${step.operation}`;
+    case "navigate":
+      return "navigate";
+    case "import":
+      return `import ${step.module}`;
+    case "call":
+      return "call";
+    case "subscribe":
+      return `subscribe ${step.event}`;
+    case "dispose":
+      return "dispose";
+    case "dom":
+      return `dom ${step.operation}`;
+    default:
+      return "unknown";
+  }
+}
+function summarizeAction(action) {
+  if (action.steps.length === 0) {
+    return "(empty)";
+  }
+  if (action.steps.length === 1) {
+    return summarizeStep(action.steps[0]);
+  }
+  return `${summarizeStep(action.steps[0])} + ${action.steps.length - 1} more`;
+}
+function viewNodeToInfo(node) {
+  const info = { kind: node.kind };
+  switch (node.kind) {
+    case "element": {
+      info.tag = node.tag;
+      if (node.props) {
+        for (const [key, value] of Object.entries(node.props)) {
+          if (key === "onClick" && typeof value === "object" && value !== null && "action" in value) {
+            info.event = `onClick=${value.action}`;
+            break;
+          }
+        }
+      }
+      if (node.children && node.children.length > 0) {
+        info.children = node.children.map(viewNodeToInfo);
+      }
+      break;
+    }
+    case "text": {
+      const val = node.value;
+      if (val.expr === "state") {
+        info.text = `state.${val.name}`;
+      } else if (val.expr === "lit") {
+        info.text = String(val.value);
+      } else if (val.expr === "param") {
+        info.text = `param.${val.name}`;
+      } else {
+        info.text = `(${val.expr})`;
+      }
+      break;
+    }
+    case "if": {
+      info.children = [viewNodeToInfo(node.then)];
+      if (node.else) {
+        info.children.push(viewNodeToInfo(node.else));
+      }
+      break;
+    }
+    case "each": {
+      info.children = [viewNodeToInfo(node.body)];
+      break;
+    }
+    case "component": {
+      info.tag = node.name;
+      if (node.children && node.children.length > 0) {
+        info.children = node.children.map(viewNodeToInfo);
+      }
+      break;
+    }
+    default:
+      break;
+  }
+  return info;
+}
+function formatStateSection(state, c) {
+  const lines = [];
+  const fieldCount = Object.keys(state).length;
+  lines.push(`${c.cyan("State")} (${fieldCount} fields):`);
+  for (const [name, field] of Object.entries(state)) {
+    const initialStr = JSON.stringify(field.initial);
+    lines.push(`  ${name}: ${c.yellow(field.type)} = ${c.dim(initialStr)}`);
+  }
+  return lines;
+}
+function formatActionsSection(actions, c) {
+  const lines = [];
+  lines.push(`${c.cyan("Actions")} (${actions.length}):`);
+  for (const action of actions) {
+    const summary = summarizeAction(action);
+    lines.push(`  ${action.name}: ${c.dim(summary)}`);
+  }
+  return lines;
+}
+function normalizeComponents(components) {
+  if (Array.isArray(components)) {
+    return components.map((comp) => ({
+      name: comp.name,
+      params: Array.isArray(comp.params) ? comp.params : Object.entries(comp.params ?? {}).map(([pName, pDef]) => ({
+        name: pName,
+        type: pDef.type
+      }))
+    }));
+  }
+  return Object.entries(components).map(
+    ([name, def]) => ({
+      name,
+      params: Array.isArray(def.params) ? def.params : Object.entries(def.params ?? {}).map(([pName, pDef]) => ({
+        name: pName,
+        type: pDef.type
+      }))
+    })
+  );
+}
+function formatComponentsSection(components, c) {
+  const lines = [];
+  const normalized = normalizeComponents(components);
+  const componentCount = normalized.length;
+  lines.push(`${c.cyan("Components")} (${componentCount}):`);
+  for (const comp of normalized) {
+    const paramList = comp.params.map((p) => `${p.name}: ${p.type}`).join(", ");
+    lines.push(`  ${comp.name}: params(${c.dim(paramList)})`);
+  }
+  return lines;
+}
+function formatStylesSection(styles, c) {
+  const lines = [];
+  const styleCount = Object.keys(styles).length;
+  lines.push(`${c.cyan("Styles")} (${styleCount}):`);
+  for (const [name, preset] of Object.entries(styles)) {
+    const variantCount = preset.variants ? Object.keys(preset.variants).length : 0;
+    const desc = variantCount > 0 ? `base + ${variantCount} variants` : "base only";
+    lines.push(`  ${name}: ${c.dim(desc)}`);
+  }
+  return lines;
+}
+function formatViewTree(node, c, indent = 0) {
+  const lines = [];
+  const prefix = "  ".repeat(indent);
+  switch (node.kind) {
+    case "element": {
+      let line = `${prefix}element<${c.green(node.tag)}>`;
+      if (node.props) {
+        for (const [key, value] of Object.entries(node.props)) {
+          if (key === "onClick" && typeof value === "object" && value !== null && "action" in value) {
+            line += ` ${c.dim(`onClick=${value.action}`)}`;
+          }
+        }
+      }
+      lines.push(line);
+      if (node.children) {
+        for (const child of node.children) {
+          lines.push(...formatViewTree(child, c, indent + 1));
+        }
+      }
+      break;
+    }
+    case "text": {
+      const val = node.value;
+      let textDesc;
+      if (val.expr === "state") {
+        textDesc = `state.${val.name}`;
+      } else if (val.expr === "lit") {
+        textDesc = JSON.stringify(val.value);
+      } else if (val.expr === "param") {
+        textDesc = `param.${val.name}`;
+      } else {
+        textDesc = `(${val.expr})`;
+      }
+      lines.push(`${prefix}text: ${c.dim(textDesc)}`);
+      break;
+    }
+    case "if": {
+      lines.push(`${prefix}if:`);
+      lines.push(`${prefix}  then:`);
+      lines.push(...formatViewTree(node.then, c, indent + 2));
+      if (node.else) {
+        lines.push(`${prefix}  else:`);
+        lines.push(...formatViewTree(node.else, c, indent + 2));
+      }
+      break;
+    }
+    case "each": {
+      lines.push(`${prefix}each (as ${node.as}):`);
+      lines.push(...formatViewTree(node.body, c, indent + 1));
+      break;
+    }
+    case "component": {
+      lines.push(`${prefix}component<${c.green(node.name)}>`);
+      if (node.children) {
+        for (const child of node.children) {
+          lines.push(...formatViewTree(child, c, indent + 1));
+        }
+      }
+      break;
+    }
+    case "slot": {
+      const slotName = node.name ? `(${node.name})` : "";
+      lines.push(`${prefix}slot${slotName}`);
+      break;
+    }
+    case "markdown": {
+      lines.push(`${prefix}markdown`);
+      break;
+    }
+    case "code": {
+      lines.push(`${prefix}code`);
+      break;
+    }
+  }
+  return lines;
+}
+function formatViewSection(view, c) {
+  const lines = [];
+  lines.push(`${c.cyan("View Tree")}:`);
+  lines.push(...formatViewTree(view, c, 1));
+  return lines;
+}
+async function inspectCommand(input, options) {
+  const isJsonMode = options.json === true;
+  const c = isJsonMode ? {
+    red: (s) => s,
+    green: (s) => s,
+    yellow: (s) => s,
+    cyan: (s) => s,
+    dim: (s) => s,
+    reset: ""
+  } : getColors3();
+  const showAll = !options.state && !options.actions && !options.components && !options.view;
+  const showState = showAll || options.state === true;
+  const showActions = showAll || options.actions === true;
+  const showComponents = showAll || options.components === true;
+  const showView = showAll || options.view === true;
+  const showStyles = showAll;
+  let fileContent;
+  try {
+    fileContent = readFileSync3(input, "utf-8");
+  } catch (err) {
+    const error = err;
+    if (error.code === "ENOENT") {
+      console.error(`Error: File not found: ${input}`);
+    } else {
+      console.error(`Error: Could not read file: ${input} - ${error.message}`);
+    }
     process.exit(1);
   }
-  console.log(`Compiled ${inputPath} \u2192 ${outputPath}`);
+  let program2;
+  try {
+    program2 = JSON.parse(fileContent);
+  } catch (err) {
+    const error = err;
+    console.error(`Error: Invalid JSON syntax: ${error.message}`);
+    process.exit(1);
+  }
+  if (isJsonMode) {
+    const output = {};
+    if (showState && program2.state) {
+      output.state = {};
+      for (const [name, field] of Object.entries(program2.state)) {
+        output.state[name] = {
+          type: field.type,
+          initial: field.initial
+        };
+      }
+    }
+    if (showActions && program2.actions) {
+      output.actions = program2.actions.map((action) => ({
+        name: action.name,
+        stepSummary: summarizeAction(action)
+      }));
+    }
+    if (showComponents && program2.components) {
+      output.components = normalizeComponents(program2.components);
+    }
+    if (showStyles && program2.styles) {
+      output.styles = program2.styles;
+    }
+    if (showView && program2.view) {
+      output.viewTree = viewNodeToInfo(program2.view);
+    }
+    console.log(JSON.stringify(output));
+  } else {
+    const sections = [];
+    if (showState && program2.state) {
+      sections.push(formatStateSection(program2.state, c));
+    }
+    if (showActions && program2.actions) {
+      sections.push(formatActionsSection(program2.actions, c));
+    }
+    if (showComponents && program2.components) {
+      sections.push(formatComponentsSection(program2.components, c));
+    }
+    if (showStyles && program2.styles) {
+      sections.push(formatStylesSection(program2.styles, c));
+    }
+    if (showView && program2.view) {
+      sections.push(formatViewSection(program2.view, c));
+    }
+    for (let i = 0; i < sections.length; i++) {
+      for (const line of sections[i]) {
+        console.log(line);
+      }
+      if (i < sections.length - 1) {
+        console.log("");
+      }
+    }
+  }
 }
 
 // src/commands/dev.ts
@@ -185,7 +1174,9 @@ async function startCommand(options) {
 // src/index.ts
 var program = new Command();
 program.name("constela").description("Constela UI framework CLI").version("0.1.0");
-program.command("compile <input>").description("Compile a Constela DSL file").option("-o, --out <path>", "Output file path").option("--pretty", "Pretty-print JSON output").action(compileCommand);
+program.command("compile <input>").description("Compile a Constela DSL file").option("-o, --out <path>", "Output file path").option("--pretty", "Pretty-print JSON output").option("--json", "Output results as JSON").option("-w, --watch", "Watch input file for changes and recompile").option("-v, --verbose", "Show detailed progress during compilation").option("--debug", "Show internal debug information").action(compileCommand);
+program.command("validate [input]").description("Validate Constela JSON files without compilation").option("-a, --all", "Validate all JSON files in directory recursively").option("--json", "Output results as JSON").action(validateCommand);
+program.command("inspect <input>").description("Inspect Constela program structure").option("--state", "Show only state").option("--actions", "Show only actions").option("--components", "Show only components").option("--view", "Show only view tree").option("--json", "Output as JSON").action(inspectCommand);
 program.command("dev").description("Start development server").option("-p, --port <number>", "Port number (default: 3000)").option("--host <string>", "Host address").option("--routesDir <path>", "Routes directory").option("--publicDir <path>", "Public directory").option("--layoutsDir <path>", "Layouts directory").action(devCommand);
 program.command("build").description("Build for production").option("-o, --outDir <path>", "Output directory (default: dist)").option("--routesDir <path>", "Routes directory").option("--publicDir <path>", "Public directory").option("--layoutsDir <path>", "Layouts directory").action(buildCommand);
 program.command("start").description("Start production server").option("-p, --port <number>", "Port number (default: 3000)").action(startCommand);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@constela/cli",
-  "version": "0.3.30",
+  "version": "0.4.1",
   "description": "CLI tools for Constela UI framework",
   "type": "module",
   "main": "./dist/index.js",
@@ -19,9 +19,9 @@
   ],
   "dependencies": {
     "commander": "^12.0.0",
-    "@constela/core": "0.7.0",
-    "@constela/compiler": "0.7.1",
-    "@constela/start": "1.2.23"
+    "@constela/core": "0.8.0",
+    "@constela/start": "1.2.25",
+    "@constela/compiler": "0.8.0"
   },
   "devDependencies": {
     "@types/node": "^20.10.0",