@constela/cli 0.4.0 → 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@constela/cli",
-  "version": "0.4.0",
+  "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/start": "1.2.24",
-    "@constela/compiler": "0.8.0",
-    "@constela/core": "0.8.0"
+    "@constela/core": "0.8.0",
+    "@constela/start": "1.2.25",
+    "@constela/compiler": "0.8.0"
   },
   "devDependencies": {
     "@types/node": "^20.10.0",