Add graph-wizard CLI workflow

.cursor/skills/graph-wizard/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: graph-wizard
+description: Use when you need to turn a natural-language architecture or topology prompt into maxGraph XML, an mxGraph-compatible XML export, a rendered PNG, a diagram report, and a markdown summary using the `javascript/max-graph-editor` project.
+---
+
+# graph-wizard
+
+## Overview
+
+This skill captures the `graph-wizard` workflow implemented in `javascript/max-graph-editor`.
+
+Use it when the task is to:
+
+- draft a diagram from a plain-English prompt
+- render the diagram to an image
+- inspect the rendered output
+- hand back machine-readable artifacts like XML, JSON, and markdown summary
+
+The workflow is Bun-first and Bash-friendly. Do not depend on Nushell.
+
+
+## When To Use
+
+Use this skill when the user wants something like:
+
+- "make me a graph of ..."
+- "generate a max graph / mxGraph diagram from this description"
+- "render an architecture diagram from a prompt"
+- "iterate on a topology diagram"
+- "produce XML and an image for a system diagram"
+
+Do not use this skill if the task is only about manual editing of an existing diagram in the browser UI with no prompt-driven generation.
+
+
+## Files And Commands
+
+Project root:
+
+- `javascript/max-graph-editor`
+
+Important files:
+
+- `javascript/max-graph-editor/graph-wizard.ts`
+- `javascript/max-graph-editor/src/wizard/`
+- `javascript/max-graph-editor/src/client/main.tsx`
+- `javascript/max-graph-editor/README.md`
+
+Core commands:
+
+1. Install dependencies
+   - ```shell
+     export PATH="$HOME/.bun/bin:$PATH"
+     bun install
+     ```
+2. Build the browser client
+   - ```shell
+     export PATH="$HOME/.bun/bin:$PATH"
+     bun run build-client
+     ```
+3. Type-check the project
+   - ```shell
+     export PATH="$HOME/.bun/bin:$PATH"
+     bun run check
+     ```
+4. Run the wizard
+   - ```shell
+     export PATH="$HOME/.bun/bin:$PATH"
+     bun graph-wizard.ts "please give me a graph of a network topology for how AWS Lambda functions work and please show the logging infrastructure"
+     ```
+
+
+## Expected Outputs
+
+The wizard writes an artifact bundle under:
+
+- `javascript/max-graph-editor/out/<timestamp>-<slug>/`
+
+Expect these files:
+
+- `prompt.txt`
+- `diagram-spec.json`
+- `diagram.maxgraph.xml`
+- `diagram.mxgraph.xml`
+- `diagram.png`
+- `diagram-report.json`
+- `diagram-summary.md`
+
+The CLI also prints a JSON result to stdout describing the output directory, provider used, final spec, render report, summary, and artifact paths.
+
+
+## Provider Behavior
+
+- If `OPENAI_API_KEY` is set, `graph-wizard` will attempt to use OpenAI for the first draft.
+- If no API key is configured, or if the OpenAI call fails, the workflow falls back to a deterministic heuristic drafter.
+- The fallback behavior is acceptable and expected in cloud environments where credentials are unavailable.
+
+
+## Validation Workflow
+
+When using this skill, validate in this order:
+
+1. Run:
+   - ```shell
+     export PATH="$HOME/.bun/bin:$PATH"
+     bun run build-client
+     bun run check
+     ```
+2. Run `graph-wizard.ts` with the user's prompt.
+3. Inspect:
+   - stdout JSON
+   - `diagram-report.json`
+   - `diagram-summary.md`
+   - `diagram.png`
+4. If the change affects UI/rendering, manually validate in the browser:
+   - start the server against the generated `diagram.maxgraph.xml`
+   - open normal editor mode
+   - open render-only mode with `?mode=render`
+   - confirm the diagram is legible and the topology is coherent
+
+Recommended manual validation command:
+
+- ```shell
+  export PATH="$HOME/.bun/bin:$PATH"
+  bun src/server.ts "/absolute/path/to/generated/diagram.maxgraph.xml" 3200
+  ```
+
+Then visit:
+
+- `http://127.0.0.1:3200`
+- `http://127.0.0.1:3200/?mode=render`
+
+
+## Output Quality Checklist
+
+Before calling the work done, check:
+
+- nodes referenced by the prompt are present
+- edges form a coherent flow rather than isolated boxes
+- observability/logging nodes are included when the prompt asks for them
+- network/topology prompts do not leave boundary nodes disconnected
+- `diagram.png` is diagram-only and free of editor chrome
+- `diagram-summary.md` explains the result and suggests useful next refinements
+
+
+## Notes For Agents
+
+- Prefer Bun commands directly over `do.nu`.
+- Preserve the generated bundle in `out/`; it is useful evidence.
+- If you improve the workflow itself, update this skill and the project README together.

javascript/max-graph-editor/.gitignore

@@ -1 +1,3 @@
 /public/app.js
+/.my/
+/out/

javascript/max-graph-editor/README.md

@@ -2,7 +2,7 @@
 
 **AI First Draft**: Much of the `max-graph-editor` project was AI-generated. Treat this as a first draft until I prune dead ends and fill in missing pieces.
 
-A minimal [maxGraph][max-graph] editor with live disk sync.
+A minimal [maxGraph][max-graph] editor with live disk sync, plus a `graph-wizard` CLI that drafts and renders diagrams from natural-language prompts.
 
 
 ## Overview
@@ -12,82 +12,66 @@ I like Mermaid diagrams but I need some architecture diagrams which tend to incl
 
 ## Instructions
 
-Follow these instructions to build and run the editor.
-
-1. Activate the Nushell `do` module
-   - ```nushell
-     do activate
-     ```
-2. Generate the `package.json` file (if needed)
-   - ```nushell
-     do package-json
-     ```
-3. Install dependencies
-   - ```nushell
-     do install
-     ```
-4. Build the browser client bundle
-   - ```nushell
-     do build-client
-     ```
-5. Type-check the TypeScript client code
-   - ```nushell
-     do check
-     ```
-6. Start the editor server with the example diagram file
-   - ```nushell
-     do server-start data/example-diagram.xml
-     ```
-7. Confirm server status
-   - ```nushell
-     do server-status
-     ```
-8. Start a Puppeteer-managed browser instance (headful)
-    - ```nushell
-      do browser-start --mode headful --url http://127.0.0.1:3000
-      ```
-9. Confirm browser status
-    - ```nushell
-      do browser-status
-      ```
-10. Capture a screenshot via Puppeteer
-    - ```nushell
-      do screenshot
-      ```
-11. Dynamically inject JavaScript in the page (example: add a box)
-    - ```nushell
-      do browser-eval --js '({label,x,y,width,height}) => { const api = window.__maxGraphEditor; if (!api) return "missing api"; return api.insertVertex(label, x, y, width, height); }' --args-json '{"label":"New Box","x":220,"y":360,"width":140,"height":60}'
-      ```
-12. Optional: inject JavaScript as a screenshot pre-step (single command)
-    - ```nushell
-      do screenshot --pre-js '({label,x,y}) => { const api = window.__maxGraphEditor; if (!api) return null; return api.insertVertex(label, x, y, 140, 60); }' --pre-args-json '{"label":"PreShot Box","x":420,"y":460}'
-      ```
-13. Capture another screenshot after dynamic actions
-    - ```nushell
-      do screenshot
-      ```
-14. Print the newest screenshot path
-    - ```nushell
-      do screenshot-latest
-      ```
-15. Optional: explicit URL/output path
-    - ```nushell
-      do screenshot --url http://127.0.0.1:3000 --out .my/screenshots/manual.png
-      ```
-16. Export a maxGraph XML file to mxGraph-compatible XML
-    - ```nushell
-      do export-mxgraph data/example-diagram.xml
-      ```
-17. Stop both server and browser when done
-    - ```nushell
-      do stop
-      ```
+Follow these instructions to build and run the editor or the `graph-wizard` CLI.
+
+### Bun / Bash workflow
+
+1. Install dependencies
+   - `bun install`
+2. Build the browser client bundle
+   - `bun run build-client`
+3. Type-check the project
+   - `bun run check`
+4. Start the editor server with the example diagram file
+   - `bun do.ts server-start --diagram data/example-diagram.xml`
+5. Start a Puppeteer-managed browser instance (headful)
+   - `bun do.ts browser-start --mode headful --url http://127.0.0.1:3000`
+6. Capture a screenshot
+   - `bun do.ts screenshot`
+7. Stop the browser and server
+   - `bun do.ts stop`
+
+### `graph-wizard` workflow
+
+Run the wizard with a natural-language prompt.
+
+- `bun graph-wizard.ts "please give me a graph of a network topology for how AWS Lambda functions work and please show the logging infrastructure"`
+
+By default, the wizard:
+
+- drafts a structured diagram spec from the prompt
+- generates maxGraph XML
+- exports mxGraph-compatible XML
+- renders a diagram-only PNG in a headless browser
+- inspects the rendered diagram and applies a small revision pass
+- writes a final summary plus suggested changes
+
+The artifact bundle is written under `out/<timestamp>-<slug>/`:
+
+- `prompt.txt`
+- `diagram-spec.json`
+- `diagram.maxgraph.xml`
+- `diagram.mxgraph.xml`
+- `diagram.png`
+- `diagram-report.json`
+- `diagram-summary.md`
+
+The wizard uses OpenAI automatically when `OPENAI_API_KEY` is set. Otherwise it falls back to a deterministic heuristic drafter so the command still works offline.
+
+### Nushell compatibility
+
+If you still want the old helper module, the `do.nu` wrappers remain available:
+
+- `do install`
+- `do build-client`
+- `do check`
+- `do graph-wizard "describe the graph"`
 
 The key point is that interaction logic is dynamic:
 
-- Use `do browser-eval --js '...'` or `--js-file ...` for browser-side logic.
-- Use `--args-json ...` to parameterize injected JavaScript (no hardcoded operation flags needed).
-- Use `do screenshot --pre-js ...` when you want “mutate page then capture” in one command.
+- Use `bun do.ts browser-eval --js '...'` or `--js-file ...` for browser-side logic.
+- Use `--args-json ...` to parameterize injected JavaScript.
+- Use `bun do.ts screenshot --pre-js ...` when you want “mutate page then capture” in one command.
 
 
 ## Wish List
@@ -98,7 +82,8 @@ General clean-ups, TODOs and things I wish to implement for this project:
 - [x] DONE Ability to add components
 - [x] DONE Ability to delete components
 - [x] DONE Add a minimal maxGraph-to-mxGraph compatibility pass for draw.io workflows (for example, compatibility renames in XML where feasible).
-- [ ] Add a headless diagram-to-image rendering path (for LLM agentic coding loops where image context is useful).
+- [x] DONE Add a headless diagram-to-image rendering path (for LLM agentic coding loops where image context is useful).
+- [ ] Iterate on the `graph-wizard` prompting loop so rendered-image critique can feed richer revisions.
 - [ ] Consider wiring the server to be launched with `my-node-launcher`.
 - [ ] Use Bun instead of npm across my JavaScript projects.
 

javascript/max-graph-editor/do.nu

@@ -40,12 +40,12 @@ export def install [] {
 
 export def build-client [] {
     cd $DIR
-    bun build src/client/main.tsx --outfile public/app.js --format esm --target browser
+    run-external bun run build-client
 }
 
 export def check [] {
     cd $DIR
-    bunx tsc --project tsconfig.json --noEmit
+    run-external bun run check
 }
 
 export def run [diagram: string, --port: int = 3000] {
@@ -144,3 +144,8 @@ export def stop [] {
     let args = ["stop"]
     run-external bun do.ts ...$args
 }
+
+export def graph-wizard [...args: string] {
+    cd $DIR
+    run-external bun graph-wizard.ts ...$args
+}