Add grapho CLI with improved UX

New CLI features:
- One-liner health check as default (grapho)
- Component status dashboard (grapho status)
- Verbose mode with details (grapho status -v)
- System diagnostics with fix commands (grapho doctor)
- Machine-readable output (grapho --json)
- Actionable fix suggestions for all warnings/errors

Also adds documentation:
- docs/MARKDOWN-EDITORS.md - Editor recommendations for mobile/desktop
- docs/LUX-LIMITATIONS.md - Tracking Lux language issues

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
2026-02-16 01:06:55 -05:00
parent 9c7f47e727
commit 63fedfb525
5 changed files with 915 additions and 1 deletions

137
docs/LUX-LIMITATIONS.md Normal file
View File

@@ -0,0 +1,137 @@
# Lux Language Limitations (grapho CLI)
This document tracks limitations encountered while developing the grapho CLI in Lux, to help improve the language.
## Fixed Issues
### 1. Double Execution Bug (FIXED)
**Severity:** Critical
**Status:** Fixed in Lux c_backend.rs
When using `let result = run main() with {}` to invoke the main function, the entire program was executing twice.
**Root Cause:** In `c_backend.rs:3878-3907`, the generated C code was:
1. Executing all `run` expressions (including `run main() with {}`)
2. Then ALSO calling `main_lux()` separately because `has_main` was true
**Fix:** Added tracking of whether main was already called via a `run` expression, and skip the separate `main_lux()` call if so.
---
## String Handling Issues
### 2. No Escape Sequences in String Literals
**Severity:** High
**Status:** Confirmed
Lux does not support backslash escape sequences like `\"`, `\n`, `\t` in string literals.
```lux
// This FAILS - backslash causes parse error
Console.print("Hello \"World\"") // ERROR: Unexpected character: '\'
// This FAILS
Console.print("Line1\nLine2") // ERROR: Unexpected character: '\'
```
**Impact:** Cannot include quotes in strings, cannot create multi-line strings, cannot output JSON with proper formatting.
**Workaround:**
- Use shell commands via `Process.exec` to generate quoted output
- Use `String.fromChar('"')` for quotes (but this had issues too)
- For JSON output, use key=value format instead
### 3. Dollar Sign in Strings Causes Parse Error
**Severity:** Medium
**Status:** Confirmed
The `$` character in strings triggers the string interpolation lexer, even inside shell command strings.
```lux
// This FAILS
execQuiet("jq -n --arg x '$foo' ...") // ERROR: Unexpected character: '$'
```
**Impact:** Cannot use shell variable syntax or jq arguments in command strings.
**Workaround:** Avoid `$` in strings, or construct commands differently.
### 4. String.fromChar Returns Int, Not String
**Severity:** Medium
**Status:** Bug
`String.fromChar('"')` appears to return an Int instead of a String, causing C compilation errors.
```lux
let q = String.fromChar('"') // Compiles but C code is wrong
Console.print(q + "hello") // C error: int + string
```
**Impact:** Cannot use character literals to build strings.
**Workaround:** Use `execQuiet("printf '%s' '\"'")` to get a quote character.
---
## Type System Issues
### 5. Record Type Definitions Don't Work as Expected
**Severity:** Medium
**Status:** Needs Investigation
Defining a record type and then creating values of that type doesn't work:
```lux
type ComponentStatus = {
name: String,
status: HealthStatus,
message: String,
fix: String
}
fn checkNb(): ComponentStatus with {Process} = {
// ...
{ name: "nb", status: Healthy, message: "ok", fix: "" }
// ERROR: Cannot unify { name: String, ... } with ComponentStatus
}
```
**Impact:** Cannot use structured types for cleaner code organization.
**Workaround:** Avoid record types, use multiple return values via tuples or restructure code.
### 6. Int.parse Doesn't Exist or Has Wrong Signature
**Severity:** Low
**Status:** Confirmed
There's no obvious way to parse a string to an integer.
```lux
let count = Int.parse(someString) // ERROR: Unknown effect operation
```
**Impact:** Cannot convert string output from shell commands to numbers.
**Workaround:** Keep numbers as strings, use shell for numeric comparisons.
---
## Suggestions for Lux
1. **Add escape sequence support** - At minimum `\"`, `\\`, `\n`, `\t`
2. **Fix String.fromChar** to return String, not Int
3. **Add raw string literals** - Something like `r"..."` or `'''...'''` for shell commands
4. **Fix the double execution bug** in the runtime
5. **Support record type literals** matching their declared type
6. **Add Int.parse and Float.parse** for string-to-number conversion
7. **Consider a heredoc syntax** for multi-line strings with special characters
---
## Current Workarounds in grapho CLI
1. **Double output:** FIXED in Lux c_backend.rs
2. **JSON output:** Using key=value format instead of proper JSON
3. **Quotes in output:** Avoided entirely or generated via shell
4. **Structured types:** Using individual variables instead of records
5. **Numeric parsing:** Keeping counts as strings throughout