Extend defhandler with :path/:method/:csrf, migrate 12 ref endpoints to SX

defhandler now supports keyword options for public route registration:
  (defhandler name :path "/..." :method :post :csrf false (&key) body)

Infrastructure: forms.sx parses options, HandlerDef stores path/method/csrf,
register_route_handlers() mounts path-based handlers as app routes.

New IO primitives (boundary.sx "Web interop" section): now, sleep,
request-form, request-json, request-header, request-content-type.

First migration: 12 reference API endpoints from Python f-string SX
to declarative .sx handlers in sx/sx/handlers/ref-api.sx.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

shared/sx/ref/forms.sx

@@ -38,17 +38,65 @@
 
 
 ;; --------------------------------------------------------------------------
-;; defhandler — (defhandler name (&key param...) body)
+;; defhandler — (defhandler name [:path "..." :method :get :csrf false] (&key param...) body)
+;;
+;; Keyword options between name and params list:
+;;   :path   — public route path (string). Without :path, handler is internal-only.
+;;   :method — HTTP method (keyword: :get :post :put :patch :delete). Default :get.
+;;   :csrf   — CSRF protection (boolean). Default true; set false for POST/PUT etc.
 ;; --------------------------------------------------------------------------
 
+(define parse-handler-args
+  (fn ((args :as list))
+    "Parse defhandler args after the name symbol.
+     Scans for :keyword value option pairs, then a list (params), then body.
+     Returns dict with keys: opts, params, body."
+    (let ((opts   {})
+          (params (list))
+          (body   nil)
+          (i      0)
+          (n      (len args))
+          (done   false))
+      (for-each
+        (fn (idx)
+          (when (and (not done) (= idx i))
+            (let ((arg (nth args idx)))
+              (cond
+                ;; keyword-value pair → consume two items
+                (= (type-of arg) "keyword")
+                (do
+                  (when (< (+ idx 1) n)
+                    (let ((val (nth args (+ idx 1))))
+                      ;; For :method, extract keyword name; for :csrf, keep as-is
+                      (dict-set! opts (keyword-name arg)
+                        (if (= (type-of val) "keyword")
+                          (keyword-name val)
+                          val))))
+                  (set! i (+ idx 2)))
+                ;; list → params, next element is body
+                (= (type-of arg) "list")
+                (do
+                  (set! params (parse-key-params arg))
+                  (when (< (+ idx 1) n)
+                    (set! body (nth args (+ idx 1))))
+                  (set! done true))
+                ;; anything else → no explicit params, this is body
+                :else
+                (do
+                  (set! body arg)
+                  (set! done true))))))
+        (range 0 n))
+      (dict :opts opts :params params :body body))))
+
 (define sf-defhandler
   (fn ((args :as list) (env :as dict))
-    (let ((name-sym   (first args))
-          (params-raw (nth args 1))
-          (body       (nth args 2))
-          (name       (symbol-name name-sym))
-          (params     (parse-key-params params-raw)))
-      (let ((hdef (make-handler-def name params body env)))
+    (let ((name-sym (first args))
+          (name     (symbol-name name-sym))
+          (parsed   (parse-handler-args (rest args)))
+          (opts     (get parsed "opts"))
+          (params   (get parsed "params"))
+          (body     (get parsed "body")))
+      (let ((hdef (make-handler-def name params body env opts)))
         (env-set! env (str "handler:" name) hdef)
         hdef))))