feat(fmt): add 'rad fmt' canonical formatter

Add a gofmt-style formatter exposed as `rad fmt`: it reparses a script
and re-emits it in one canonical style, so layout stops being a thing
anyone argues about and can be enforced in CI.

Modes follow gofmt/prettier convention: rewrite in place by default,
--stdout to preview, --check to exit non-zero when a file isn't already
formatted, and read from stdin when piped (for editor integration).

The formatter works on the tree-sitter CST, not the typed AST, because
the AST drops comments and the shebang and so can't round-trip. Layout
is built with a Prettier-style Doc IR that wraps long calls and
collections to fit a width target; construct formatters turn CST nodes
into Docs.

Safety is the central constraint - a formatter must never corrupt code.
Three layers enforce it: a no-op on parse errors, a panic recover, and
a structural-equivalence guard that reparses the output and refuses it
unless the named-node tree and comment count are unchanged. Anything
the guard rejects degrades to returning the input untouched.

This ships the common constructs (assignments, expressions, calls,
paths, collections, if/for/while, comments, blank lines). Constructs
not yet handled - string quote-normalization, args/rad/cmd blocks,
functions, switch - fall back to emitting their original source
verbatim, which the guard proves safe, so the rest can land
incrementally without risking valid scripts.

Wired in like the existing `check` command: an embedded Rad script
drives IO and flags over a pure `_rad_fmt` builtin backed by the new
rts/radfmt package. DESIGN.md vendors the design-time research.

Author: amterp

core/cmds.go

@@ -18,6 +18,7 @@ const (
 	EmbCmdGenId   = "gen-id"
 	EmbCmdStash   = "stash"
 	EmbCmdCheck   = "check"
+	EmbCmdFmt     = "fmt"
 	EmbCmdExplain = "explain"
 )
 
@@ -43,6 +44,7 @@ func init() {
 		createEmbeddedCmd(EmbCmdNew),
 		createEmbeddedCmd(EmbCmdDocs),
 		createEmbeddedCmd(EmbCmdCheck),
+		createEmbeddedCmd(EmbCmdFmt),
 		createEmbeddedCmd(EmbCmdHome),
 		createEmbeddedCmd(EmbCmdGenId),
 		createEmbeddedCmd(EmbCmdStash),

core/embedded/fmt

@@ -0,0 +1,66 @@
+#!/usr/bin/env rad
+---
+Formats Rad scripts.
+
+Rewrites each script in place into Rad's canonical style. Use --stdout to
+preview without writing, or --check to verify formatting (e.g. in CI).
+---
+args:
+    *paths str       # Paths of Rad scripts to format.
+    stdout bool      # Print formatted output to stdout instead of writing files.
+    check bool       # Don't write; exit non-zero if any file isn't formatted.
+
+    stdout excludes check
+
+// No paths + piped stdin: format stdin to stdout (editor / pipe friendly).
+if not paths and has_stdin():
+    result = _rad_fmt(read_stdin())
+    if not result.ok:
+        print_err("stdin: could not parse.")
+        exit(1)
+    if check:
+        // In check mode, don't emit the formatted text; just signal via exit code.
+        exit(result.changed)
+    print(result.formatted, end="")
+    exit()
+
+if not paths:
+    print_err("Error: provide at least one path to format (or pipe a script via stdin).")
+    exit(1)
+
+any_unformatted = false
+any_error = false
+
+for path in paths:
+    file = read_file(path) catch:
+        pass
+    if type_of(file) == "error":
+        print_err("{path}: {file}")
+        any_error = true
+        continue
+
+    result = _rad_fmt(file.content)
+    if not result.ok:
+        print_err("{path}: could not parse, skipping.")
+        any_error = true
+        continue
+
+    if stdout:
+        print(result.formatted, end="")
+    else if check:
+        if result.changed:
+            print(path)
+            any_unformatted = true
+    else if result.changed:
+        write = write_file(path, result.formatted) catch:
+            pass
+        if type_of(write) == "error":
+            print_err("{path}: {write}")
+            any_error = true
+            continue
+        print("Formatted {path}")
+
+if any_error:
+    exit(1)
+if check and any_unformatted:
+    exit(1)

core/funcs.go

@@ -137,6 +137,7 @@ const (
 	INTERNAL_FUNC_GET_STASH_ID    = "_rad_get_stash_id"
 	INTERNAL_FUNC_DELETE_STASH    = "_rad_delete_stash"
 	INTERNAL_FUNC_RUN_CHECK       = "_rad_run_check"
+	INTERNAL_FUNC_FMT             = "_rad_fmt"
 	INTERNAL_FUNC_CHECK_FROM_LOGS = "_rad_check_from_logs"
 	INTERNAL_FUNC_EXPLAIN         = "_rad_explain"
 	INTERNAL_FUNC_EXPLAIN_LIST    = "_rad_explain_list"

core/funcs_internal.go

@@ -7,6 +7,7 @@ import (
 
 	com "github.com/amterp/rad/core/common"
 	"github.com/amterp/rad/rts/check"
+	radfmt "github.com/amterp/rad/rts/radfmt"
 	"github.com/amterp/rad/rts/rl"
 
 	"github.com/amterp/rad/rts"
@@ -124,6 +125,19 @@ func AddInternalFuncs() {
 				return newRadValues(f.i, f.callNode, radMap)
 			},
 		},
+		{
+			Name: INTERNAL_FUNC_FMT,
+			Execute: func(f FuncInvocation) RadValue {
+				// Format normalizes line endings itself, so pass the raw source.
+				formatted, changed, ok := radfmt.Format(f.GetStr("_src").Plain())
+
+				radMap := NewRadMap()
+				radMap.SetPrimitiveStr("formatted", formatted)
+				radMap.SetPrimitiveBool("changed", changed)
+				radMap.SetPrimitiveBool("ok", ok)
+				return newRadValues(f.i, f.callNode, radMap)
+			},
+		},
 		FuncInternalCheckFromLogs,
 		{
 			Name: INTERNAL_FUNC_EXPLAIN,

core/testing/snapshots/args/cmds.snap

@@ -421,6 +421,7 @@ Commands:
   completion    Generate shell tab-completion scripts.
   docs          Opens rad's documentation website.
   explain       Explains Rad error codes with detailed documentation.
+  fmt           Formats Rad scripts.
   gen-id        Generates a unique string ID. Useful for e.g. rad stash IDs.
   home          Prints out rad's home directory.
   new           Sets up a new Rad script.

core/testing/snapshots/misc/misc.snap

@@ -134,6 +134,7 @@ Commands:
   completion    Generate shell tab-completion scripts.
   docs          Opens rad's documentation website.
   explain       Explains Rad error codes with detailed documentation.
+  fmt           Formats Rad scripts.
   gen-id        Generates a unique string ID. Useful for e.g. rad stash IDs.
   home          Prints out rad's home directory.
   new           Sets up a new Rad script.
@@ -223,6 +224,7 @@ Commands:
   completion    Generate shell tab-completion scripts.
   docs          Opens rad's documentation website.
   explain       Explains Rad error codes with detailed documentation.
+  fmt           Formats Rad scripts.
   gen-id        Generates a unique string ID. Useful for e.g. rad stash IDs.
   home          Prints out rad's home directory.
   new           Sets up a new Rad script.