Claude/rescript http server 6 dj dd

.gitignore

@@ -38,8 +38,11 @@ erl_crash.dump
 /Manifest.toml
 
 # ReScript
+lib/
 /lib/bs/
 /.bsb.lock
+*.res.js
+.merlin
 
 # Python (SaltStack only)
 __pycache__/

.machine_readable/AGENTIC.scm

@@ -1,16 +1,49 @@
 ;; SPDX-License-Identifier: AGPL-3.0-or-later
-;; AGENTIC.scm - AI agent interaction patterns for rsr-template-repo
+;; AGENTIC.scm - AI agent interaction patterns for rescript-http-server
 
 (define agentic-config
   `((version . "1.0.0")
+    (project . "rescript-http-server")
+
     (claude-code
       ((model . "claude-opus-4-5-20251101")
-       (tools . ("read" "edit" "bash" "grep" "glob"))
-       (permissions . "read-all")))
+       (tools . ("read" "edit" "bash" "grep" "glob" "write"))
+       (permissions . "read-all")
+       (context-files . ("src/HttpServer.res"
+                         "src/HttpServer.resi"
+                         "README.adoc"
+                         "ROADMAP.adoc"))))
+
     (patterns
       ((code-review . "thorough")
        (refactoring . "conservative")
-       (testing . "comprehensive")))
+       (testing . "comprehensive")
+       (documentation . "asciidoc-preferred")))
+
     (constraints
-      ((languages . ())
-       (banned . ("typescript" "go" "python" "makefile"))))))
+      ((languages . ("rescript" "javascript"))
+       (banned . ("typescript" "go" "python" "node"))
+       (runtime . "deno-only")
+       (style . "functional-first")))
+
+    (task-guidance
+      ((adding-routes .
+        "Add route helpers in HttpServer.res, expose in .resi, document in README")
+       (adding-middleware .
+        "Follow cors/logging pattern. Async function wrapping handler.")
+       (bug-fixes .
+        "Check both .res and .resi for type consistency")
+       (new-features .
+        "Update ROADMAP.adoc, STATE.scm, and README.adoc")))
+
+    (code-patterns
+      ((handlers . "async request => response")
+       (middleware . "(request, handler) => promise<response>")
+       (ffi . "@val @scope(\"Deno\") external")
+       (error-handling . "Result or Option types, try/catch at boundaries")))
+
+    (testing-guidance
+      ((framework . "Deno.test")
+       (location . "tests/")
+       (naming . "*_test.res")
+       (run . "deno test --allow-net")))))

.machine_readable/ECOSYSTEM.scm

@@ -1,20 +1,59 @@
 ;; SPDX-License-Identifier: AGPL-3.0-or-later
-;; ECOSYSTEM.scm - Ecosystem position for rsr-template-repo
+;; ECOSYSTEM.scm - Ecosystem position for rescript-http-server
 ;; Media-Type: application/vnd.ecosystem+scm
 
 (ecosystem
   (version "1.0")
-  (name "rsr-template-repo")
-  (type "")
-  (purpose "")
+  (name "rescript-http-server")
+  (type "library")
+  (purpose "Type-safe HTTP server bindings for ReScript using Deno.serve")
 
   (position-in-ecosystem
-    (category "")
-    (subcategory "")
-    (unique-value ()))
+    (category "runtime")
+    (subcategory "http-server")
+    (layer "Runtime Layer (L4)")
+    (unique-value
+      ("First-class ReScript bindings to Deno.serve")
+      ("Type-safe routing with pattern matching")
+      ("Composable middleware architecture")
+      ("Zero runtime overhead FFI")))
 
-  (related-projects ())
+  (parent-ecosystem
+    (name "rescript-full-stack")
+    (url "https://github.com/hyperpolymath/rescript-full-stack")
+    (role "HTTP server component for backend services"))
 
-  (what-this-is ())
+  (related-projects
+    (siblings
+      (("rescript-tea" . "Elm Architecture for frontend")
+       ("rescript-postgres" . "Type-safe PostgreSQL client")
+       ("rescript-websocket" . "WebSocket client/server")
+       ("rescript-redis" . "Redis with Streams and Cluster")
+       ("rescript-env" . "Environment variable access")
+       ("rescript-wasm-runtime" . "WASM module support")))
+    (complements
+      (("@rescript/core" . "Core utilities and types")
+       ("rescript-schema" . "JSON validation")))
+    (alternatives
+      (("oak" . "Deno middleware framework (TypeScript)")
+       ("hono" . "Lightweight web framework (TypeScript)")
+       ("express" . "Node.js framework (not Deno-compatible)"))))
 
-  (what-this-is-not ()))
+  (integration-points
+    (("rescript-postgres" . "Database access from route handlers")
+     ("rescript-redis" . "Caching and session storage")
+     ("rescript-websocket" . "Upgrade HTTP connections to WebSocket")
+     ("rescript-env" . "Configuration from environment")))
+
+  (what-this-is
+    ("ReScript bindings to Deno.serve HTTP server API")
+    ("Type-safe request/response handling")
+    ("Pattern-based routing system")
+    ("Middleware infrastructure for cross-cutting concerns")
+    ("Part of the rescript-full-stack ecosystem"))
+
+  (what-this-is-not
+    ("Not a full web framework (no templates, ORM, sessions)")
+    ("Not Node.js compatible (Deno only)")
+    ("Not a static file server (use Deno's serveDir)")
+    ("Not a WebSocket server (use rescript-websocket)")))

.machine_readable/META.scm

@@ -1,17 +1,45 @@
 ;; SPDX-License-Identifier: AGPL-3.0-or-later
-;; META.scm - Meta-level information for rsr-template-repo
+;; META.scm - Meta-level information for rescript-http-server
 ;; Media-Type: application/meta+scheme
 
 (meta
-  (architecture-decisions ())
+  (architecture-decisions
+    (("deno-native" .
+      "Built exclusively for Deno runtime, not Node.js. Leverages Deno.serve for HTTP handling.")
+     ("ffi-bindings" .
+      "Direct FFI to Deno APIs via @val/@send externals. Zero runtime wrapper overhead.")
+     ("async-first" .
+      "All I/O operations return promises. Handlers are async functions.")
+     ("middleware-composition" .
+      "Middleware wraps handlers. Applied via withMiddleware for explicit composition.")
+     ("pattern-routing" .
+      "Simple pattern matching with exact and wildcard (*) support. Path params planned for v0.2.0.")))
 
   (development-practices
-    (code-style ())
+    (code-style
+      (("format" . "rescript format")
+       ("lint" . "rescript compiler warnings")
+       ("naming" . "camelCase for functions, PascalCase for types")))
     (security
-      (principle "Defense in depth"))
-    (testing ())
+      (principle "Defense in depth")
+      (practices
+        ("No eval or dynamic code execution")
+        ("CORS disabled by default")
+        ("Headers sanitized in responses")))
+    (testing
+      (framework "Deno.test")
+      (coverage-target "80%")
+      (strategy "Unit tests for helpers, integration for routing"))
     (versioning "SemVer")
     (documentation "AsciiDoc")
-    (branching "main for stable"))
+    (branching "main for stable, feature branches for development"))
 
-  (design-rationale ()))
+  (design-rationale
+    (("minimal-api" .
+      "Small surface area. Core request/response helpers only. Middleware for extensions.")
+     ("no-global-state" .
+      "Server configuration passed explicitly. No singleton patterns.")
+     ("interface-files" .
+      ".resi file defines public API. Implementation details hidden.")
+     ("ecosystem-alignment" .
+      "Follows rescript-full-stack conventions. Compatible with rescript-tea, rescript-postgres."))))

.machine_readable/NEUROSYM.scm

@@ -1,13 +1,56 @@
 ;; SPDX-License-Identifier: AGPL-3.0-or-later
-;; NEUROSYM.scm - Neurosymbolic integration config for rsr-template-repo
+;; NEUROSYM.scm - Neurosymbolic integration config for rescript-http-server
 
 (define neurosym-config
   `((version . "1.0.0")
+    (project . "rescript-http-server")
+
     (symbolic-layer
       ((type . "scheme")
        (reasoning . "deductive")
-       (verification . "formal")))
+       (verification . "type-checked")
+       (artifacts
+         ((".machine_readable/STATE.scm" . "Project state tracking")
+          (".machine_readable/META.scm" . "Architecture decisions")
+          (".machine_readable/ECOSYSTEM.scm" . "Ecosystem position")
+          (".machine_readable/PLAYBOOK.scm" . "Operational procedures")))))
+
     (neural-layer
-      ((embeddings . false)
-       (fine-tuning . false)))
-    (integration . ())))
+      ((embeddings . #f)
+       (fine-tuning . #f)
+       (llm-assistance . #t)
+       (assistance-patterns
+         (("code-generation" . "Route handlers, middleware")
+          ("documentation" . "API docs, examples")
+          ("testing" . "Test case generation")
+          ("debugging" . "Error analysis and fixes")))))
+
+    (integration
+      ((state-tracking .
+        "STATE.scm updated on significant changes")
+       (decision-logging .
+        "META.scm records architecture decisions")
+       (ecosystem-awareness .
+        "ECOSYSTEM.scm defines relationships")
+       (llm-context .
+        "AGENTIC.scm guides AI interactions")))
+
+    (type-system-integration
+      ((rescript-types . "Primary type safety layer")
+       (resi-interfaces . "API boundary definition")
+       (symbolic-validation . "Scheme S-expressions for metadata")))
+
+    (knowledge-representation
+      ((domain . "HTTP server development")
+       (concepts
+         (("request" . "Incoming HTTP request with method, path, headers, body")
+          ("response" . "Outgoing HTTP response with status, headers, body")
+          ("handler" . "Async function transforming request to response")
+          ("middleware" . "Function wrapping handler with cross-cutting logic")
+          ("route" . "Mapping from method+pattern to handler")))
+       (relationships
+         (("handler" "processes" "request")
+          ("handler" "produces" "response")
+          ("middleware" "wraps" "handler")
+          ("router" "dispatches-to" "handler")
+          ("server" "invokes" "handler")))))))

.machine_readable/PLAYBOOK.scm

@@ -1,13 +1,61 @@
 ;; SPDX-License-Identifier: AGPL-3.0-or-later
-;; PLAYBOOK.scm - Operational runbook for rsr-template-repo
+;; PLAYBOOK.scm - Operational runbook for rescript-http-server
 
 (define playbook
   `((version . "1.0.0")
+    (project . "rescript-http-server")
+
     (procedures
-      ((deploy . (("build" . "just build")
-                  ("test" . "just test")
-                  ("release" . "just release")))
-       (rollback . ())
-       (debug . ())))
-    (alerts . ())
-    (contacts . ())))
+      ((build
+         (steps
+           (("compile" . "deno task build")
+            ("verify" . "Check src/HttpServer.res.js exists")))
+         (success-criteria . "No compiler errors, .res.js file generated"))
+
+       (test
+         (steps
+           (("unit" . "deno test tests/")
+            ("integration" . "deno test --allow-net tests/integration/")))
+         (success-criteria . "All tests pass"))
+
+       (release
+         (steps
+           (("version" . "Update version in deno.json and STATE.scm")
+            ("changelog" . "Update ROADMAP.adoc with completed features")
+            ("tag" . "git tag v$VERSION")
+            ("push" . "git push origin main --tags")))
+         (success-criteria . "Tag pushed, version updated"))
+
+       (dev-server
+         (steps
+           (("watch" . "deno task dev")
+            ("example" . "deno run --allow-net examples/basic.res.js")))
+         (notes . "Watch mode rebuilds on file changes"))
+
+       (clean
+         (steps
+           (("artifacts" . "deno task clean")
+            ("cache" . "rm -rf lib/")))
+         (notes . "Removes compiled JavaScript and build cache"))))
+
+    (common-issues
+      ((issue . "Compiler error: Unbound module Fetch")
+       (cause . "Missing @rescript/core dependency")
+       (fix . "Add @rescript/core to bs-dependencies in rescript.json"))
+
+      ((issue . "Runtime error: Deno is not defined")
+       (cause . "Running with Node.js instead of Deno")
+       (fix . "Use deno run instead of node"))
+
+      ((issue . "Type error in handler")
+       (cause . "Handler not returning promise<response>")
+       (fix . "Ensure handler is async or returns promise explicitly")))
+
+    (alerts
+      ((security . "Monitor Deno security advisories")
+       (dependencies . "Check @rescript/core updates monthly")))
+
+    (contacts
+      ((maintainer . "hyperpolymath")
+       (issues . "github.com/hyperpolymath/rescript-http-server/issues")
+       (ecosystem . "github.com/hyperpolymath/rescript-full-stack")))))