feat(samples): CLI explainer/auditor + Blazor WASM Mermaid visualizer#12
Merged
Conversation
Adds two runnable samples that demonstrate consuming the ShellSyntaxTree v0.1.0-alpha API. Both samples are IsPackable=false so they don't ship in the nupkg. samples/ShellSyntaxTree.Cli.Sample (net8.0 console, System.CommandLine 2.0.7): - `explain "<cmd>"` — pretty-prints the AST with [flag]/[path]/ [cwd-attr]/[dyn-skip]/[glob] markers per arg, redirect targets, and the IsSubshell/IsBashCWrapped flags. Unparseable inputs show the reason. - `audit "<cmd>"` — runs a tiny built-in policy (deny writes under /etc/, /usr/, /bin/, /sbin/, /lib/; warn on `curl | bash`; warn on dynamic content in path-arg slots; warn on IsUnparseable). Exits 0/1/2 by severity. - AuditPolicy.cs is one file so the README can point at it as a reference implementation. samples/ShellSyntaxTree.Web.Sample (net8.0 Blazor WebAssembly): - Single page: textarea on the left, mermaid SVG render on the right. - Five preset buttons covering compound commands, subshell isolation, bash -c recursion, dynamic-cwd attribution, and unparseable inputs. - Source/AST/Unparseable tabs alongside the rendered diagram. - 300ms debounced auto-render on input; Render button available too. - mermaid.js v11 loaded from jsDelivr CDN; JS interop via shellSyntaxTreeInterop.renderMermaid(). - MermaidRenderer.cs handles label escaping, subshell/bash -c subgraphs, dotted edges for redirects, and CSS classes for unparseable (red) and dynamic-skip (yellow) nodes. - ScriptSplitter.cs folds line continuations, skips blank/comment lines, preserves heredoc bodies so the parser sees them whole. README rewritten: - Elevator pitch + install line up top - Inline mermaid example (GitHub renders directly) - Use-case bullets covering AI agent gates, CI/CD audits, sandbox policy generation, pre-commit linters, audit-log analytics, and documentation tools - Quick-start code snippet (~25 LOC of consumer code) - Pointer to both samples with copy-pasteable `dotnet run` commands - Repository layout table for contributors - Locked public API surface from SPEC §2 Eight screenshots captured via Playwright validating the Blazor sample's core scenarios (empty state, build script, subshell, bash -c, unparseable, dynamic cwd, custom input, source tab). Renderer fixes after first Playwright pass: - Empty input now returns string.Empty so the host page's "No script yet" placeholder shows instead of a phantom "(no commands)" node. - `2>&1` and `N>&M` fd-dup redirect targets are filtered out (they're not files; basename-startswith-& check handles the resolver's cwd-joined form like `/work/&1`). - Apostrophes in node labels left unescaped (mermaid 11 renders ' as `&'` inside `["..."]` labels). - Node labels fall back to first non-flag arg when no path args are present, so verbs like `echo done` and `set -e` show their args instead of rendering as bare verb-only nodes. - Razor textarea placeholder was Razor-encoding && to &&. API surface unchanged; tests still 353/353. CPM additions: - System.CommandLine 2.0.7 - $(AspNetCoreVersion) = 8.0.26 for Microsoft.AspNetCore.Components.WebAssembly[.DevServer] No new CI/CD workflow. Samples runnable via `dotnet run` only.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Two runnable samples demonstrating the ShellSyntaxTree v0.1.0-alpha API, plus a complete README rewrite for end-user consumption.
What landed
samples/ShellSyntaxTree.Cli.Sample(net8.0 console)System.CommandLine 2.0.7. Two subcommands:
```bash
dotnet run --project samples/ShellSyntaxTree.Cli.Sample -- explain "cd /repo && rm /etc/passwd"
dotnet run --project samples/ShellSyntaxTree.Cli.Sample -- audit "cd /repo && rm /etc/passwd"
```
[flag]/[path]/[cwd-attr]/[dyn-skip]/[glob]markers, redirect targets,IsSubshell/IsBashCWrappedflags. `IsUnparseable` shows reason./etc///usr///bin///sbin///lib/; warn oncurl | bash; warn on dynamic args in path slots; warn on unparseable. Exits 0/1/2 by severity.AuditPolicy.csis one file so the README can point at it.samples/ShellSyntaxTree.Web.Sample(net8.0 Blazor WASM)Paste a bash script → see the parsed AST as a Mermaid flowchart. Everything runs in the browser. mermaid.js v11 from jsDelivr CDN; JS interop via a 30-line wrapper. 300ms debounced auto-render. Five preset buttons cover compound commands, subshell isolation,
bash -crecursion, dynamic-cwd attribution, and unparseable inputs. Source / AST / Unparseable tabs alongside the diagram.```bash
dotnet run --project samples/ShellSyntaxTree.Web.Sample
→ http://localhost:5239
```
Validated end-to-end via Playwright; 8 screenshots saved to
assets/sample-web-*.pngand referenced from the README.README rewrite
Out: the Akka-template-flavored sections (status, why-not-tree-sitter, repository layout). In:
Renderer fixes after Playwright validation
2>&1and similar fd-dup redirect targets no longer render as fake file nodes (basename&check handles the resolver's cwd-joined form)'as literal&'inside["..."]labels)echo done,set -erender with their args)&&What's unchanged
PublicApiSnapshotTestsstill 18/18 greenIsPackable=falseCPM additions
System.CommandLine2.0.7$(AspNetCoreVersion)= 8.0.26 forMicrosoft.AspNetCore.Components.WebAssembly[.DevServer]Test plan