blu/grapho
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add grapho CLI with improved UX

Browse Source 
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:
Brandon Lucas
2026-02-16 01:06:55 -05:00
parent 9c7f47e727
commit 63fedfb525
5 changed files with 915 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

238
docs/MARKDOWN-EDITORS.md Normal file
View File

@@ -0,0 +1,238 @@
# Markdown Editors for grapho
This document covers recommended markdown editors for use with grapho across desktop and mobile platforms.
## Recommended: md (PWA)
**URL:** https://md-ashy.vercel.app
A lightweight, browser-based markdown editor that works on both desktop and mobile.
### Features
- WYSIWYG editing with inline markdown transformation
- Source mode toggle for raw editing
- Offline support via PWA (installable as app)
- Dark theme
- File drag-and-drop support
- Share documents via compressed URL links
- GitHub Flavored Markdown (GFM) support including tables and task lists
- Syntax highlighting for code blocks
- Keyboard shortcuts (Ctrl+S to download, Ctrl+B/I for formatting)
### Why It's Good for grapho
- Works on any device with a browser
- Can be installed as a PWA on mobile home screen
- No account required
- Files stay local (privacy-first)
- Can edit files from Syncthing-synced folders
### Setup
1. Visit https://md-ashy.vercel.app
2. Click the install prompt (or use browser menu > "Add to Home Screen")
3. Open markdown files from your synced folders
---
## Desktop Editors
### MarkText (Recommended for Desktop)
**Open Source** | **Cross-platform** | [GitHub](https://github.com/marktext/marktext)
A simple, elegant markdown editor with real-time preview.
**Pros:**
- Clean, distraction-free interface
- WYSIWYG preview (like Typora, but free)
- Multiple editing modes: Source, Typewriter, Focus
- Six themes (light/dark variants)
- Supports CommonMark, GFM, and Pandoc markdown
- Diagrams (flowcharts, sequence, Gantt via Mermaid)
- Math expressions via KaTeX
- Auto-save and file recovery
**Cons:**
- Last release was March 2022 (minimally maintained)
- No mobile version
**Best for:** Writers who want a polished, free Typora alternative.
---
### Visual Studio Code
**Open Source** | **Cross-platform** | [Website](https://code.visualstudio.com)
The developer's Swiss Army knife with excellent markdown support.
**Pros:**
- Built-in markdown preview
- Extensive extension ecosystem (markdownlint, Markdown All in One, etc.)
- Git integration built-in
- Works with any programming workflow
- Highly customizable
**Cons:**
- Resource-heavy for just markdown editing
- Can feel like overkill for simple notes
**Best for:** Developers who want one editor for code and notes.
---
### Obsidian
**Freemium** | **Cross-platform** | [Website](https://obsidian.md)
A powerful knowledge base that works on local markdown files.
**Pros:**
- Bidirectional linking between notes
- Graph view of note connections
- Extensive plugin ecosystem (900+ plugins)
- Local-first, privacy-focused
- Mobile apps (iOS/Android)
- Sync available (paid) or use Syncthing
**Cons:**
- Not fully open source (free for personal use)
- Learning curve for advanced features
- Can become complex with too many plugins
**Best for:** Building a personal knowledge base / "second brain".
---
### Zettlr
**Open Source** | **Cross-platform** | [Website](https://www.zettlr.com)
Built for academics and researchers.
**Pros:**
- Built-in citation management (Zotero integration)
- Footnotes and LaTeX support
- Zettelkasten method support
- Export to PDF, Word, LaTeX via Pandoc
- Focus on long-form writing
**Cons:**
- No mobile app
- Steeper learning curve
- Requires Pandoc for some exports
**Best for:** Academic writing, research papers, thesis work.
---
### Joplin
**Open Source** | **Cross-platform** | [Website](https://joplinapp.org)
Note-taking with sync and mobile apps.
**Pros:**
- End-to-end encryption
- Mobile apps (iOS/Android)
- Sync with Nextcloud, Dropbox, OneDrive, WebDAV
- Import from Evernote
- Notebooks and tagging
- Web clipper extension
**Cons:**
- Notes stored in SQLite database, not plain files
- Can be resource-intensive
- Less suited for power users who want plain markdown
**Best for:** Evernote replacement with cross-platform sync.
---
## Mobile Editors
### Markor (Android)
**Open Source** | [GitHub](https://github.com/gsantner/markor)
The best open-source markdown editor for Android.
**Pros:**
- Works with any folder (including Syncthing)
- No account required
- Supports markdown, todo.txt, and more
- Offline-first
**Best for:** grapho users on Android.
### iA Writer (iOS/Android)
**Paid** | [Website](https://ia.net/writer)
Premium minimalist writing experience.
**Pros:**
- Beautiful, distraction-free interface
- Works with iCloud/Dropbox folders
- Focus mode highlights current sentence
**Cons:**
- Paid app
- File management less flexible than Markor
**Best for:** iOS users who value polish.
### Obsidian Mobile (iOS/Android)
**Free** | [Website](https://obsidian.md)
Mobile companion to Obsidian desktop.
**Pros:**
- Full Obsidian features on mobile
- Sync via iCloud, Obsidian Sync, or Syncthing
**Best for:** Existing Obsidian users.
---
## Recommendation for grapho Users
### Simple Setup (Recommended)
1. **Desktop:** MarkText or VS Code
2. **Mobile:** md PWA (https://md-ashy.vercel.app) or Markor (Android)
3. **Sync:** Syncthing (already part of grapho)
### Power User Setup
1. **Desktop:** Obsidian with Syncthing sync
2. **Mobile:** Obsidian Mobile
3. **Notes in:** `~/.nb/` or a dedicated Syncthing folder
### Academic Setup
1. **Desktop:** Zettlr with Zotero
2. **Mobile:** md PWA for quick edits
3. **Export:** Pandoc for final documents
---
## Integration with grapho
All recommended editors work with plain markdown files, which means:
1. Store notes in an `nb` notebook or Syncthing folder
2. Edit with any editor on any device
3. Changes sync automatically via Syncthing
4. Backup happens via restic
Example workflow:
```bash
# Create a note with nb
nb add "Meeting notes"
# Edit in your preferred editor
marktext ~/.nb/home/meeting-notes.md
# Or on mobile, open the same file via Syncthing folder
# Sync happens automatically
grapho sync
```
## Sources
- [MarkText GitHub](https://github.com/marktext/marktext)
- [Obsidian](https://obsidian.md)
- [Zettlr](https://www.zettlr.com)
- [Joplin](https://joplinapp.org)
- [awesome-markdown-editors](https://github.com/mundimark/awesome-markdown-editors)
- [Markdown Guide Tools](https://www.markdownguide.org/tools/)