release 0.3.0

.gitignore

@@ -1 +1,3 @@
 fes
+*.tar.gz
+/stuff/

COPYING

@@ -1,6 +1,6 @@
 ISC License
 
-Copyright (c) 2025 fSD
+Copyright (c) 2025-2026 fSD
 
 Permission to use, copy, modify, and/or distribute this software for any
 purpose with or without fee is hereby granted, provided that the above

Dockerfile

@@ -4,24 +4,17 @@ WORKDIR /src
 
 RUN apk add --no-cache git build-base
 
-COPY go.mod go.sum ./
-RUN go mod download
-
 COPY . .
 
-ENV CGO_ENABLED=0
-ENV GOOS=linux
-ENV GOARCH=amd64
+RUN make
 
-RUN go build -ldflags="-X fes/modules/version.gitCommit=$(git rev-parse --short HEAD) -s -w" -o fes
+FROM alpine:3.19
 
-FROM scratch
-
-COPY --from=builder /src/fes /fes
+COPY --from=builder /src/fes /usr/local/bin/fes
 
 WORKDIR /app
 
-EXPOSE 8080
+EXPOSE 3000
 
-ENTRYPOINT ["/fes"]
+ENTRYPOINT ["/usr/local/bin/fes"]
 CMD ["run", "/app"]

README.md

@@ -40,6 +40,6 @@ Run `fes doc` for the documentation website or goto [docs.vxserver.dev](https://
 
 ISC License
 
-Copyright (C) 2025 fSD
+Copyright (C) 2025-2026 fSD
 
 See `COPYING`

examples/advanced/include/foo.lua

@@ -1,7 +0,0 @@
-local foo = {}
-
-foo.render = function()
-	return "This was called from a foo function"
-end
-
-return foo

examples/advanced/www/index.lua

@@ -1,15 +0,0 @@
-local fes = require("fes")
-local std = fes.std
-
-
-local site = fes.fes()
-
-site.copyright = fes.util.copyright("https://fsd.vxserver.dev", "fSD")
-
-site:h1("Hello, World!")
-
-site:note(
-	fes.app.foo.render()
-)
-
-return site

examples/archive/README.md

@@ -0,0 +1,4 @@
+# archive
+
+This example demonstrates the archive feature of Fes it is useful for file
+sharing purposes.

examples/archive/archive/facts/seals/seals.txt

@@ -0,0 +1,22 @@
+Pinnipeds [2] are the seals and their relatives, a group of semi-aquatic marine
+mammals. The Pinnipedia is in the Order Carnivora. There are three seal
+families: Odobenidae (walruses), Otariidae (eared seals, including sea lions
+and fur seals), and Phocidae (true seals).[3]
+
+Seals are sleek-bodied and barrel-shaped. Their bodies are well adapted to the
+aquatic habitat where they spend most of their lives. Pinnipeds have flippers
+for hands, big bulky bodies, doggish faces, and big eyes. Unlike cetaceans,
+pinnipeds have their noses on their faces, and each nostril of the nose closes
+when the pinniped goes underwater. Like cetaceans, pinnipeds have a thick layer
+of blubber (fat) just under their skin: this blubber keeps them warm in cold
+waters and keeps them fed during times when food is not easily found. When they
+cannot find food, they live off the fat in the blubber.
+
+Pinnipeds are carnivorous. This means they eat only meat (such as fish or
+squid) and not plants. However, almost all pinnipeds can be eaten by polar
+bears, sharks and killer whales.
+
+Seals are often trained in zoos or aquariums to put on shows. However, in
+Sweden, it is illegal to train a seal to balance a ball on its nose.[4]
+
+From [Pinniped Wikipedia](https://simple.wikipedia.org/wiki/Pinniped)

examples/archive/www/index.lua

@@ -1,17 +1,10 @@
 local fes = require("fes")
-local std = fes.std
-
 local site = fes.fes()
 
 site.copyright = fes.util.copyright("https://fsd.vxserver.dev", "fSD")
 
 site:h1("Hello, World!")
 
-site:note(fes.util.cc {
-	std.h2("Files"),
-	std.ul {
-		std.a("/archive", "to the file room!"),
-	}
-})
+site:a("/archive", fes.std.h2("To the file room!"))
 
 return site

examples/best/Fes.toml

@@ -1,5 +1,5 @@
 [app]
 
-name = "hello"
+name = "best"
 version = "0.0.1"
 authors = ["vx-clutch"]

examples/best/README.md

@@ -0,0 +1,23 @@
+# best
+
+This is an example of best practices for the Fes framework.
+
+## Parts
+
+With best practice we can break our sites into a few parts.
+
+## Index
+
+The main page of the site loads in the header and the footer, as well as shows
+some core information
+
+## Include
+
+Within include the header and footer are defined.
+
+* **Header:** Site navigation and name display
+* **Footer:** Extra and external information.
+
+## Static
+
+This is where we store our favicon.

examples/best/include/footer.lua

@@ -0,0 +1,13 @@
+local footer = {}
+
+footer.render = function(std)
+    return table.concat({
+	std.h2("Other resources"),
+	std.tl({
+		std.external("https://git.vxserver.dev/fSD/fes", "Fes source"),
+		std.external("https://docs.vxserver.dev/static/fes.html", "Documentation"),
+	}),
+})
+end
+
+return footer

examples/best/include/header.lua

@@ -0,0 +1,7 @@
+local header = {}
+
+header.render = function(std)
+    return std.center(std.ha("/", std.h1("Best Practices")))
+end
+
+return header

examples/best/www/index.lua

@@ -0,0 +1,20 @@
+local fes = require("fes")
+local std = fes.std
+local u = fes.util
+
+local site = fes.fes()
+
+site.copyright = fes.util.copyright("https://fsd.vxserver.dev", "fSD")
+site.title = "Best practices"
+site.favicon = "/static/favicon.ico"
+
+site:banner(fes.app.header.render(std))
+
+site:note(u.cc {
+	std.h2("Hello, World!"),
+	std.p("This is an example of the best practices/canonical Fes site.")
+})
+
+site:note(fes.app.footer.render(std))
+
+return site

examples/default/Fes.toml

@@ -1,5 +1,5 @@
 [app]
 
-name = "advanced"
+name = "default"
 version = "0.0.1"
 authors = ["vx-clutch"]

examples/default/README.md

@@ -0,0 +1,33 @@
+# default
+
+```
+fes new default
+```
+
+> **Know what you are doing?** Delete this file. Have fun!
+
+## Project Structure
+
+Inside your Fes project, you'll see the following directories and files:
+
+```
+.
+├── Fes.toml
+├── README.md
+└── www
+    └── index.lua
+```
+
+Fes looks for `.lua` files in the `www/` directory. Each file is exposed as a route based on its file name.
+
+## Commands
+
+All commands are run from the root of the project, from a terminal:
+
+| Command                   | Action                                           |
+| :------------------------ | :----------------------------------------------- |
+| `fes run .`               | Runs the project at `.`                          |
+
+## What to learn more?
+
+Check out [Fes's docs](https://docs.vxserver.dev/static/fes.html).

examples/error/README.md

@@ -0,0 +1,6 @@
+# error
+
+This shows what a Lua error looks like to the user. Lua errors are the most
+common and the most critical so that is why they are shown to the user. Other,
+lesser errors, are only shown to the developer because of their different
+nature.

examples/error/www/index.lua

@@ -1,6 +1,10 @@
 local fes = require("fes")
 local site = fes.fes()
 
+site.copyright = fes.util.copyright("https://fsd.vxserver.dev", "fSD")
+
 This is what an error looks like
 
+site:h1("Hello, World!")
+
 return site

examples/extentions/Fes.toml

@@ -0,0 +1,5 @@
+[app]
+
+name = "extentions"
+version = "0.0.1"
+authors = ["vx-clutch"]

examples/extentions/README.md

@@ -0,0 +1,33 @@
+# extentions
+
+```
+fes new extentions
+```
+
+> **Know what you are doing?** Delete this file. Have fun!
+
+## Project Structure
+
+Inside your Fes project, you'll see the following directories and files:
+
+```
+.
+├── Fes.toml
+├── README.md
+└── www
+    └── index.lua
+```
+
+Fes looks for `.lua` files in the `www/` directory. Each file is exposed as a route based on its file name.
+
+## Commands
+
+All commands are run from the root of the project, from a terminal:
+
+| Command                   | Action                                           |
+| :------------------------ | :----------------------------------------------- |
+| `fes run .`               | Runs the project at `.`                          |
+
+## What to learn more?
+
+Check out [Fes's docs](https://docs.vxserver.dev/static/fes.html).

examples/extentions/www/index.lua

@@ -0,0 +1,12 @@
+local fes = require("fes")
+local site = fes.fes()
+
+site.copyright = fes.util.copyright("https://fsd.vxserver.dev/", "fSD")
+
+site:extend("myext", {
+  shout = function(self, str) return self:g(str:upper()) end
+})
+
+site.myext:shout("hello world")
+
+return site

examples/hello-with-docker/docker-compose.yml

@@ -1,7 +0,0 @@
-services:
-  hello:
-    image: git.vxserver.dev/fsd/fes:latest
-    ports:
-      - "3000:3000"
-    volumes:
-      - ./app:/app

examples/hello/README.md

@@ -0,0 +1,4 @@
+# hello
+
+This is a very simple hello world program, the only difference between this and
+default is this README.

examples/markdown/README.md

@@ -0,0 +1,3 @@
+# markdown
+
+This example demonstrate Fes's ability to handle markdown routes.

examples/markdown/www/index.md

@@ -1 +1,3 @@
-# Hello, World!
+# Markdown!
+
+**Fes** also supports markdown routes!

examples/simple/README.md

@@ -0,0 +1,5 @@
+# simple
+
+This simple example shows the extensibility of the Fes framework. It shows the
+you do not necessarily need to use the site object (although it is recommended)
+you can define your own site, similar to how Lisps do things.

lib/fes.lua

@@ -1,4 +1,5 @@
 local std = require("lib.std")
+local symbol = require("lib.symbol")
 
 local M = {}
 M.__index = M
@@ -318,11 +319,30 @@ em, i { font-style: italic; }
 	return setmetatable(self, M)
 end
 
-function M:custom(str)
+function M:g(str)
 	table.insert(self.parts, str)
 	return self
 end
 
+function M:extend(name, tbl)
+	if type(name) ~= "string" then
+		error("First argument to extend must be a string (namespace name)")
+	end
+	if type(tbl) ~= "table" then
+		error("Second argument to extend must be a table of functions")
+	end
+	self[name] = {}
+	for k, v in pairs(tbl) do
+		if type(v) ~= "function" then
+			error("Extension values must be functions, got " .. type(v) .. " for key " .. k)
+		end
+		self[name][k] = function(...)
+			return v(self, ...)
+		end
+	end
+	return self
+end
+
 for name, func in pairs(std) do
 	if type(func) == "function" then
 		M[name] = function(self, ...)
@@ -340,9 +360,11 @@ function M:build()
 	header = header:gsub(
 		"{{FAVICON}}",
 		favicon_html
-			or [[<link rel="icon" href="data:image/svg+xml,<svg xmlns=%%22http://www.w3.org/2000/svg%%22 viewBox=%%220 0 100 100%%22><text y=%%22.9em%%22 font-size=%%2290%%22>🔥</text></svg>">]]
+		or
+		[[<link rel="icon" href="data:image/svg+xml,<svg xmlns=%%22http://www.w3.org/2000/svg%%22 viewBox=%%220 0 100 100%%22><text y=%%22.9em%%22 font-size=%%2290%%22>🔥</text></svg>">]]
 	)
-	local footer = self.footer:gsub("{{COPYRIGHT}}", self.copyright or "&#169; The Copyright Holder")
+	local footer = self.footer:gsub("{{COPYRIGHT}}",
+		self.copyright or symbol.legal.copyright .. "The Copyright Holder")
 	return header .. table.concat(self.parts, "\n") .. footer
 end
 

lib/site.lua

@@ -0,0 +1,27 @@
+local M = {}
+
+function M.name()
+	local fes_mod = package.loaded.fes
+	if fes_mod and fes_mod.config and fes_mod.config.site and fes_mod.config.site.name then
+		return fes_mod.config.site.name
+	end
+	return ""
+end
+
+function M.version()
+	local fes_mod = package.loaded.fes
+	if fes_mod and fes_mod.config and fes_mod.config.site and fes_mod.config.site.version then
+		return fes_mod.config.site.version
+	end
+	return ""
+end
+
+function M.authors()
+	local fes_mod = package.loaded.fes
+	if fes_mod and fes_mod.config and fes_mod.config.site and fes_mod.config.site.authors then
+		return fes_mod.config.site.authors
+	end
+	return {}
+end
+
+return M

lib/std.lua

@@ -1,155 +1,157 @@
 local M = {}
 
-function M.fes_version()
-	local fes_mod = package.loaded.fes
-	if fes_mod and fes_mod.config and fes_mod.config.fes and fes_mod.config.fes.version then
-		return fes_mod.config.fes.version
-	end
-	return ""
-end
+function M.element(tag, attrs, content)
+	local out = { "<", tag }
 
-function M.site_version()
-	local fes_mod = package.loaded.fes
-	if fes_mod and fes_mod.config and fes_mod.config.site and fes_mod.config.site.version then
-		return fes_mod.config.site.version
+	if attrs then
+		for k, v in pairs(attrs) do
+			if v ~= false and v ~= nil then
+				if v == true then
+					out[#out + 1] = " " .. k
+				else
+					out[#out + 1] = " " .. k .. "=\"" .. tostring(v) .. "\""
 				end
-	return ""
+			end
+		end
+	end
+
+	if content == nil then
+		out[#out + 1] = " />"
+		return table.concat(out)
+	end
+
+	out[#out + 1] = ">"
+	out[#out + 1] = tostring(content)
+	out[#out + 1] = "</"
+	out[#out + 1] = tag
+	out[#out + 1] = ">"
+
+	return table.concat(out)
 end
 
 function M.a(link, str)
 	link = link or "https://example.com"
 	str = str or link
-	return '<a href="' .. link .. '">' .. str .. "</a>"
+	return M.element("a", { href = link }, str)
 end
 
 function M.ha(link, str)
 	link = link or "https://example.com"
 	str = str or link
-	return '<a class="hidden" href="' .. link .. '">' .. str .. "</a>"
+	return M.element("a", { href = link, class = "hidden" }, str)
 end
 
 function M.external(link, str)
-	return '<a target="_blank" href="' .. link .. '">' .. str .. "</a>"
+	return M.element("a", { href = link, target = "_blank" }, str)
 end
 
 function M.note(str)
-	return '<div class="note">' .. str .. "</div>"
+	return M.element("div", { class = "note" }, str)
 end
 
 function M.muted(str)
-	return '<div class="muted">' .. str .. "</div>"
+	return M.element("div", { class = "muted" }, str)
 end
 
 function M.callout(str)
-	return '<div class="callout">' .. str .. "</div>"
+	return M.element("div", { class = "callout" }, str)
 end
 
 function M.h1(str)
-	return "<h1>" .. (str or "") .. "</h1>"
+	return M.element("h1", nil, str or "")
 end
 
 function M.h2(str)
-	return "<h2>" .. (str or "") .. "</h2>"
+	return M.element("h2", nil, str or "")
 end
 
 function M.h3(str)
-	return "<h3>" .. (str or "") .. "</h3>"
+	return M.element("h3", nil, str or "")
 end
+
 function M.h4(str)
-	return "<h4>" .. (str or "") .. "</h4>"
+	return M.element("h4", nil, str or "")
 end
 
 function M.h5(str)
-	return "<h5>" .. (str or "") .. "</h5>"
+	return M.element("h5", nil, str or "")
 end
 
 function M.h6(str)
-	return "<h6>" .. (str or "") .. "</h6>"
+	return M.element("h6", nil, str or "")
 end
 
 function M.p(str)
-	return "<p>" .. (str or "") .. "</p>"
+	return M.element("p", nil, str or "")
 end
 
 function M.pre(str)
-	return "<pre>" .. (str or "") .. "</pre>"
+	return M.element("pre", nil, str or "")
 end
 
 function M.code(str)
-	return "<pre><code>" .. (str or "") .. "</code></pre>"
+	return M.element("pre", nil, M.element("code", nil, str or ""))
 end
 
 function M.ul(items)
 	items = items or {}
-	local html = "<ul>"
+	local out = {}
 	for _, item in ipairs(items) do
-		html = html .. "<li>" .. tostring(item) .. "</li>"
+		out[#out + 1] = M.element("li", nil, item)
 	end
-	html = html .. "</ul>"
-	return html
+	return M.element("ul", nil, table.concat(out))
 end
 
 function M.ol(items)
 	items = items or {}
-	local html = "<ol>"
+	local out = {}
 	for _, item in ipairs(items) do
-		html = html .. "<li>" .. tostring(item) .. "</li>"
+		out[#out + 1] = M.element("li", nil, item)
 	end
-	html = html .. "</ol>"
-	return html
+	return M.element("ol", nil, table.concat(out))
 end
 
 function M.tl(items)
 	items = items or {}
-	local html = '<ul class="tl">'
+	local out = {}
 	for _, item in ipairs(items) do
-		html = html .. "<li>" .. tostring(item) .. "</li>"
+		out[#out + 1] = M.element("li", nil, item)
 	end
-	html = html .. "</ul>"
-	return html
+	return M.element("ul", { class = "tl" }, table.concat(out))
 end
 
 function M.blockquote(str)
-	return "<blockquote>" .. (str or "") .. "</blockquote>"
+	return M.element("blockquote", nil, str or "")
 end
 
 function M.hr()
-	return "<hr>"
+	return M.element("hr")
 end
 
 function M.img(src, alt)
-	src = src or ""
-	alt = alt or ""
-	return '<img src="' .. src .. '" alt="' .. alt .. '">'
+	return M.element("img", { src = src or "", alt = alt or "" })
 end
 
 function M.strong(str)
-	return "<strong>" .. (str or "") .. "</strong>"
+	return M.element("strong", nil, str or "")
 end
 
 function M.em(str)
-	return "<em>" .. (str or "") .. "</em>"
+	return M.element("em", nil, str or "")
 end
 
 function M.br()
-	return "<br>"
+	return M.element("br")
 end
 
 function M.div(content, class)
-	content = content or ""
-	class = class or ""
-	local class_attr = class ~= "" and (' class="' .. class .. '"') or ""
-	return "<div" .. class_attr .. ">" .. content .. "</div>"
+	return M.element("div", class and { class = class } or nil, content or "")
 end
 
 function M.span(content, class)
-	content = content or ""
-	class = class or ""
-	local class_attr = class ~= "" and (' class="' .. class .. '"') or ""
-	return "<span" .. class_attr .. ">" .. content .. "</span>"
+	return M.element("span", class and { class = class } or nil, content or "")
 end
 
--- HTML escaping utility
 function M.escape(str)
 	str = tostring(str or "")
 	str = str:gsub("&", "&amp;")
@@ -160,55 +162,28 @@ function M.escape(str)
 	return str
 end
 
--- Get site name from config
-function M.site_name()
-	local fes_mod = package.loaded.fes
-	if fes_mod and fes_mod.config and fes_mod.config.site and fes_mod.config.site.name then
-		return fes_mod.config.site.name
-	end
-	return ""
-end
-
--- Get site title from config
-function M.site_title()
-	local fes_mod = package.loaded.fes
-	if fes_mod and fes_mod.config and fes_mod.config.site and fes_mod.config.site.title then
-		return fes_mod.config.site.title
-	end
-	return ""
-end
-
--- Get site authors from config
-function M.site_authors()
-	local fes_mod = package.loaded.fes
-	if fes_mod and fes_mod.config and fes_mod.config.site and fes_mod.config.site.authors then
-		return fes_mod.config.site.authors
-	end
-	return {}
-end
-
 function M.highlight(str)
-	return '<span class="highlight">' .. (str or "") .. "</span>"
+	return M.element("span", { class = "highlight" }, str or "")
 end
 
 function M.banner(str)
-	return '<div class="banner">' .. (str or "") .. "</div>"
+	return M.element("div", { class = "banner" }, str or "")
 end
 
 function M.center(str)
-	return '<div class="center">' .. (str or "") .. "</div>"
+	return M.element("div", { class = "center" }, str or "")
 end
 
 function M.nav(link, str)
 	link = link or "example.com"
 	str = str or link
-	return '<a class="nav" href="' .. link .. '">' .. str .. "</a>"
+	return M.element("a", { href = link, class = "nav" }, str)
 end
 
 function M.rl(r, l)
-	r = r or ""
-	l = l or ""
-	return string.format('<span class="left">%s</span><span class="right">%s</span>', r, l)
+	return
+		M.element("span", { class = "left" }, r or "") ..
+		M.element("span", { class = "right" }, l or "")
 end
 
 return M

lib/symbol.lua

@@ -1,7 +1,75 @@
 local M = {}
 
-M.copyright = "©"
-M.registered_trademark = "®"
-M.trademark = "™"
+local function get(s)
+	return "&" .. (s or "") .. ";"
+end
+
+M.legal = {
+	copyright = get("copy"),
+	registered_trademark = get("reg"),
+	trademark = get("trade"),
+}
+
+M.currency = {
+	euro = get("euro"),
+	pound = get("pound"),
+	yen = get("yen"),
+	cent = get("cent"),
+	dollar = "$",
+}
+
+M.math = {
+	plus_minus = get("plusmn"),
+	multiply = get("times"),
+	divide = get("divide"),
+	not_equal = get("ne"),
+	less_equal = get("le"),
+	greater_equal = get("ge"),
+	infinity = get("infin"),
+	approx = get("asymp"),
+}
+
+M.arrows = {
+	left = get("larr"),
+	right = get("rarr"),
+	up = get("uarr"),
+	down = get("darr"),
+	left_right = get("harr"),
+}
+
+M.punctuation = {
+	left_double_quote = get("ldquo"),
+	right_double_quote = get("rdquo"),
+	left_single_quote = get("lsquo"),
+	right_single_quote = get("rsquo"),
+	ellipsis = get("hellip"),
+	em_dash = get("mdash"),
+	en_dash = get("ndash"),
+}
+
+M.whitespace = {
+	non_breaking = get("nbsp"),
+	thin = get("thinsp"),
+}
+
+M.symbols = {
+	degree = get("deg"),
+	micro = get("micro"),
+	section = get("sect"),
+	paragraph = get("para"),
+	check = get("check"),
+	cross = get("cross"),
+	bullet = get("bull"),
+	middle_dot = get("middot"),
+	broken_bar = get("brvbar"),
+}
+
+M.html = {
+	less_than = get("lt"),
+	greater_than = get("gt"),
+	ampersand = get("amp"),
+	double_quote = get("quot"),
+	single_quote = get("apos"),
+}
 
 return M

lib/util.lua

@@ -3,12 +3,33 @@ local symbol = require("lib.symbol")
 
 local M = {}
 
-function M.cc(tbl)
-	return table.concat(tbl)
+function M.cc(tbl, sep)
+	return table.concat(tbl, sep or "")
 end
 
-function M.copyright(link, holder)
-	return symbol.copyright .. " " .. std.external(link, holder)
+function M.year(y)
+	return y or os.date("%Y")
+end
+
+function M.copyright(link, holder, year)
+	return symbol.legal.copyright .. " " .. M.year(year) .. " " .. std.external(link, holder)
+end
+
+function M.license(name)
+	return symbol.legal.registered .. " " .. name
+end
+
+function M.ls(dir)
+	local p = io.popen('ls -A -1 -- ' .. string.format('%q', dir))
+	if not p then
+		return nil
+	end
+	local t = {}
+	for line in p:lines() do
+		t[#t + 1] = line
+	end
+	p:close()
+	return t
 end
 
 return M

main.go

@@ -6,6 +6,7 @@ import (
 	"flag"
 	"fmt"
 	"os"
+	"runtime"
 
 	"github.com/fatih/color"
 
@@ -13,6 +14,7 @@ import (
 	"fes/modules/doc"
 	"fes/modules/new"
 	"fes/modules/server"
+	"fes/modules/ui"
 	"fes/modules/version"
 )
 
@@ -29,18 +31,21 @@ func init() {
 	config.Docker = flag.Bool("docker", false, "Create a docker project")
 	config.Lib = lib
 	config.Doc = documentation
+	config.Verbose = flag.Bool("verbose", false, "Enable verbose logging")
 }
 
 func main() {
+	var m runtime.MemStats
+
 	flag.Usage = func() {
 		fmt.Fprintf(flag.CommandLine.Output(), "Usage: %s [options] <command> <project_dir>\n", os.Args[0])
-		fmt.Println("Commands:")
-		fmt.Println("  new <project_dir>   Create a new project")
-		fmt.Println("  doc                 Open documentation")
-		fmt.Println("  run <project_dir>   Start the server")
-		fmt.Println("Options:")
+		fmt.Fprintln(flag.CommandLine.Output(), "Commands:")
+		fmt.Fprintln(flag.CommandLine.Output(), "  new <project_dir>   Create a new project")
+		fmt.Fprintln(flag.CommandLine.Output(), "  doc                 Open documentation")
+		fmt.Fprintln(flag.CommandLine.Output(), "  run <project_dir>   Start the server")
+		fmt.Fprintln(flag.CommandLine.Output(), "Options:")
 		flag.PrintDefaults()
-		fmt.Println("For bug reports, contact a developer and describe the issue. Provide the output of the `-V1` flag.")
+		fmt.Fprintln(flag.CommandLine.Output(), "For bug reports, contact a developer and describe the issue. Provide the output of the `-V1` flag.")
 	}
 
 	showVersion := flag.Bool("version", false, "Show version and exit")
@@ -89,6 +94,15 @@ func main() {
 			os.Exit(1)
 		}
 	case "run":
+		if *config.Port == 3000 {
+			ui.WARNING("Using default port, this may lead to conflicts with other services")
+		}
+		ui.Log("Fes is starting")
+		ui.Log("Fes version=%s, commit=%s, just started", version.VERSION, version.GetCommit())
+
+		runtime.ReadMemStats(&m)
+		ui.Log("FRE memory usage when created %v Mb", m.TotalAlloc/1024/1024)
+
 		if err := server.Start(dir); err != nil {
 			if errors.Is(err, os.ErrNotExist) {
 				fmt.Fprintf(os.Stderr, "%s does not exist\n", dir)

modules/config/config.go

@@ -11,6 +11,7 @@ var Port *int
 var Color *bool
 var Static *bool
 var Docker *bool
+var Verbose *bool
 
 type AppConfig struct {
 	App struct {

modules/doc/doc.go

@@ -9,6 +9,7 @@ import (
 	"github.com/pkg/browser"
 )
 
+/* open documentation in browser */
 func Open() error {
 	fmt.Println("Opening documentation in browser")
 

modules/new/new.go

@@ -2,6 +2,7 @@ package new
 
 import (
 	"fes/modules/config"
+	"fes/modules/ui"
 	"fmt"
 	"os"
 	"os/exec"
@@ -114,5 +115,16 @@ All commands are run from the root of the project, from a terminal:
 ## What to learn more?
 
 Check out [Fes's docs](https://docs.vxserver.dev/static/fes.html).`, "$$", "`"), dir, dir)
+
+	ui.Hint("you can run this with `fes run %s`", dir)
+
+	fmt.Println("Created new Fes project at", func () string {
+		if cwd, err := os.Getwd(); err != nil {
+			return dir
+		} else {
+			return cwd
+		}
+	}())
+
 	return nil
 }

modules/server/server.go

@@ -1,11 +1,10 @@
 package server
 
 import (
+	"errors"
 	"fes/modules/config"
 	"fes/modules/ui"
 	"fmt"
-	"github.com/pelletier/go-toml/v2"
-	lua "github.com/yuin/gopher-lua"
 	"html/template"
 	"io/fs"
 	"net/http"
@@ -15,13 +14,26 @@ import (
 	"sort"
 	"strings"
 	"time"
+
+	"github.com/pelletier/go-toml/v2"
+	lua "github.com/yuin/gopher-lua"
 )
 
+/* this is the request data we pass over the bus to the application, via the fes.bus interface */
 type reqData struct {
 	path   string
 	params map[string]string
 }
 
+/* performs relavent handling based on the directory passaed
+ *
+ * Special directories
+ *  - www/     <= contains lua routes.
+ *  - static/  <= static content accessable at /static/path or /static/dir/path.
+ *  - include/ <= globally accessable lua functions, cannot directly access "fes" right now.
+ *  - archive/ <= contains user facing files such as archives or dists.
+ *
+ */
 func handleDir(entries []os.DirEntry, dir string, routes map[string]string, base string, isStatic bool) error {
 	for _, entry := range entries {
 		path := filepath.Join(dir, entry.Name())
@@ -59,6 +71,7 @@ func handleDir(entries []os.DirEntry, dir string, routes map[string]string, base
 	return nil
 }
 
+// TODO(vx-clutch): this should not be a function
 func loadIncludeModules(L *lua.LState, includeDir string) *lua.LTable {
 	app := L.NewTable()
 	ents, err := os.ReadDir(includeDir)
@@ -94,7 +107,8 @@ func loadIncludeModules(L *lua.LState, includeDir string) *lua.LTable {
 	return app
 }
 
-func loadLua(entry string, cfg *config.AppConfig, requestData reqData) ([]byte, error) {
+/* renders the given lua route */
+func renderRoute(entry string, cfg *config.AppConfig, requestData reqData) ([]byte, error) {
 	L := lua.NewState()
 	defer L.Close()
 
@@ -219,6 +233,7 @@ func loadLua(entry string, cfg *config.AppConfig, requestData reqData) ([]byte,
 	return []byte(""), nil
 }
 
+/* this indexes and generate the page for viewing the archive directory */
 func generateArchiveIndex(fsPath string, urlPath string) (string, error) {
 	info, err := os.Stat(fsPath)
 	if err != nil {
@@ -271,23 +286,25 @@ func generateArchiveIndex(fsPath string, urlPath string) (string, error) {
 	urlPath = basePath(strings.TrimPrefix(urlPath, "/archive"))
 
 	var b strings.Builder
+
 	b.WriteString("<html>\n<head><title>Index of ")
 	b.WriteString(template.HTMLEscapeString(urlPath))
 	b.WriteString("</title></head>\n<body>\n<h1>Index of ")
 	b.WriteString(template.HTMLEscapeString(urlPath))
 	b.WriteString("</h1><hr><pre>")
-	if urlPath != "/archive" && urlPath != "/archive/" {
-		up := path.Dir(urlPath)
-		if up == "." {
-			up = "/archive"
-		}
-		if !strings.HasSuffix(up, "/") {
-			up = "/archive" + filepath.Dir(up) + "/"
-		}
-		b.WriteString(`<a href="` + template.HTMLEscapeString(up) + `">../</a>` + "\n")
+
+	if urlPath != "/" {
+		b.WriteString(
+			`<a href="/archive` +
+				template.HTMLEscapeString(path.Dir(strings.TrimSuffix(urlPath, "/"))) +
+				`">../</a>` + "\n",
+		)
 	} else {
-		b.WriteString(`<a href="../">../</a>` + "\n")
+		b.WriteString(
+			`<a href="/">../</a>` + "\n",
+		)
 	}
+
 	nameCol := 50
 	for _, ei := range list {
 		escapedName := template.HTMLEscapeString(ei.name)
@@ -309,6 +326,9 @@ func generateArchiveIndex(fsPath string, urlPath string) (string, error) {
 	return b.String(), nil
 }
 
+/* generates the data for the not found page. Checks for user-defined source in this order
+ * 404.lua => 404.md => 404.html => default.
+ */
 func generateNotFoundData(cfg *config.AppConfig) []byte {
 	notFoundData := []byte(`
 <html>
@@ -320,9 +340,13 @@ func generateNotFoundData(cfg *config.AppConfig) []byte {
 </html>
 `)
 	if _, err := os.Stat(filepath.Join("www", "404.lua")); err == nil {
-		if nf, err := loadLua("www/404.lua", cfg, reqData{}); err == nil {
+		if nf, err := renderRoute("www/404.lua", cfg, reqData{}); err == nil {
 			notFoundData = nf
 		}
+	} else if _, err := os.Stat("www/404.md"); err == nil {
+		if buf, err := os.ReadFile("www/404.html"); err == nil {
+			notFoundData = []byte(markdownToHTML(string(buf)))
+		}
 	} else if _, err := os.Stat("www/404.html"); err == nil {
 		if buf, err := os.ReadFile("www/404.html"); err == nil {
 			notFoundData = buf
@@ -331,6 +355,7 @@ func generateNotFoundData(cfg *config.AppConfig) []byte {
 	return notFoundData
 }
 
+/* helper to load all special directories */
 func loadDirs() map[string]string {
 	routes := make(map[string]string)
 
@@ -355,37 +380,54 @@ func loadDirs() map[string]string {
 	return routes
 }
 
+/* helper to parse the Fes.toml and generate config */
 func parseConfig() config.AppConfig {
+	defaultCfg := config.AppConfig{}
+	defaultCfg.App.Authors = []string{"unknown"}
+	defaultCfg.App.Name = "unknown"
+	defaultCfg.App.Version = "unknown"
+
 	tomlDocument, err := os.ReadFile("Fes.toml")
 	if err != nil {
+		if errors.Is(err, os.ErrNotExist) {
+			ui.WARN("no config file found, using the default config. In order to specify a config file write to Fes.toml")
+			return defaultCfg
+		} else {
 			ui.Error("failed to read Fes.toml", err)
 			os.Exit(1)
 		}
+	}
 	docStr := fixMalformedToml(string(tomlDocument))
 	var cfg config.AppConfig
 	if err := toml.Unmarshal([]byte(docStr), &cfg); err != nil {
 		ui.Warning("failed to parse Fes.toml", err)
-		cfg.App.Authors = []string{"unknown"}
-		cfg.App.Name = "unknown"
-		cfg.App.Version = "unknown"
+		cfg = defaultCfg
 	}
 	return cfg
 }
 
-func readArchive(w http.ResponseWriter, route string) {
+/* helper to read the archive files */
+func readArchive(w http.ResponseWriter, route string) error {
 	fsPath := "." + route
 	if info, err := os.Stat(fsPath); err == nil && info.IsDir() {
 		if page, err := generateArchiveIndex(fsPath, route); err == nil {
 			w.Write([]byte(page))
+			return nil
+		} else {
+			return err
 		}
 	}
+	return nil
 }
 
+/* start the Fes server */
 func Start(dir string) error {
 	if err := os.Chdir(dir); err != nil {
 		return ui.Error(fmt.Sprintf("failed to change directory to %s", dir), err)
 	}
 
+	ui.Log("Running root=%s, port=%d.", filepath.Clean(dir), *config.Port)
+
 	cfg := parseConfig()
 	notFoundData := generateNotFoundData(&cfg)
 	routes := loadDirs()
@@ -405,7 +447,7 @@ func Start(dir string) error {
 			route = r.URL.Path
 
 			if strings.HasPrefix(route, "/archive") {
-				readArchive(w, route)
+				err = readArchive(w, route)
 			} else {
 				w.WriteHeader(http.StatusNotFound)
 				w.Write([]byte(notFoundData))
@@ -422,7 +464,7 @@ func Start(dir string) error {
 
 		var data []byte
 		if strings.HasSuffix(route, ".lua") {
-			data, err = loadLua(route, &cfg, reqData{path: r.URL.Path, params: params})
+			data, err = renderRoute(route, &cfg, reqData{path: r.URL.Path, params: params})
 		} else if strings.HasSuffix(route, ".md") {
 			data, err = os.ReadFile(route)
 			data = []byte(markdownToHTML(string(data)))
@@ -437,7 +479,8 @@ func Start(dir string) error {
 
 		w.Write(data)
 	})
+	ui.Log("Server initialized")
 
-	fmt.Printf("Server is running on http://localhost:%d\n", *config.Port)
+	ui.Log("Ready to accept connections tcp")
 	return http.ListenAndServe(fmt.Sprintf("0.0.0.0:%d", *config.Port), nil)
 }

modules/ui/ui.go

@@ -4,54 +4,114 @@ import (
 	"errors"
 	"fmt"
 	"strings"
+	"time"
 
 	"fes/modules/config"
-	"fes/modules/version"
 
 	"github.com/fatih/color"
 )
 
+const (
+	hintColor = 0xbda02a
+)
+
+func formatTimestamp() string {
+	return time.Now().Format("02 Jan 2006 15:04")
+}
+
+func logMessage(prefix string, msg string, args ...any) {
+	formatted := fmt.Sprintf(msg, args...)
+	if prefix == "" {
+		fmt.Printf("%s * %s\n", formatTimestamp(), formatted)
+	} else {
+		fmt.Printf("%s * %s: %s\n", formatTimestamp(), prefix, formatted)
+	}
+}
+
+// Generic log
+func Log(msg string, args ...any) {
+	logMessage("", msg, args...)
+}
+
+// OK message (green)
+func OK(msg string, args ...any) {
+	formatted := fmt.Sprintf(msg, args...)
+	color.Green("%s * %s\n", formatTimestamp(), formatted)
+}
+
+// Warning message (magenta)
+func WARN(msg string, args ...any) {
+	formatted := fmt.Sprintf(msg, args...)
+	color.Magenta("%s # %s\n", formatTimestamp(), formatted)
+}
+
+// Warning message (magenta)
+func WARNING(msg string, args ...any) {
+	formatted := fmt.Sprintf(msg, args...)
+	color.Magenta("%s # WARNING %s\n", formatTimestamp(), formatted)
+}
+
+// Error message (red)
+func ERROR(msg string, args ...any) {
+	formatted := fmt.Sprintf(msg, args...)
+	color.Red("%s ! %s\n", formatTimestamp(), formatted)
+}
+
+// Fatal message and panic
+func FATAL(msg string, args ...any) {
+	formatted := fmt.Sprintf(msg, args...)
+	color.Red("%s % %s\n", formatTimestamp(), formatted)
+	panic(formatted)
+}
+
+// Hint message (custom color)
+func Hint(msg string, args ...any) {
+	formatted := fmt.Sprintf(msg, args...)
+	color.RGB(func(hex int) (r, g, b int) {
+		r = (hex >> 16) & 0xFF
+		g = (hex >> 8) & 0xFF
+		b = hex & 0xFF
+		return
+	}(hintColor)).Printf("hint: %s\n", formatted)
+}
+
+// Path logging: prints route and status
 func Path(path string, err error) {
 	path = strings.TrimPrefix(path, "/")
-
 	if path == "" {
 		path = "(null)"
 	}
 
-	fmt.Printf(" > %s ", path)
 	if err == nil {
-		OK("ok")
-		return
+		OK("Route: %s - ok", path)
 	} else if errors.Is(err, config.ErrRouteMiss) {
-		WARN(config.ErrRouteMiss.Error())
+		WARN("Route: %s - %s", path, config.ErrRouteMiss.Error())
 	} else {
-		ERROR("bad")
+		ERROR("Route: %s - bad", path)
 	}
 }
 
+// System warning with prefix
 func Warning(msg string, err error) error {
-	fmt.Printf("%s: %s: %v\n", version.PROGRAM_NAME, color.MagentaString("warning"), err)
+	WARN("%s: %v", msg, err)
 	return err
 }
 
+// System error with prefix
 func Error(msg string, err error) error {
-	fmt.Printf("%s: %s: %v\n", version.PROGRAM_NAME, color.RedString("error"), err)
+	ERROR("%s: %v", msg, err)
 	return err
 }
 
+// Fatal system error
 func Fatal(msg string, err error) error {
-	fmt.Printf("%s: %s: %v\n", version.PROGRAM_NAME, color.RedString("fatal"), err)
-	panic(err)
+	FATAL("%s: %v", msg, err)
+	return err
 }
 
-func OK(msg string) {
-	color.Green(msg)
-}
-
-func WARN(msg string) {
-	color.Magenta(msg)
-}
-
-func ERROR(msg string) {
-	color.Red(msg)
+// Log on Verbose
+func LogVerbose(msg string, args ...any) {
+	if *config.Verbose {
+		Log(msg, args...)
+	}
 }

modules/version/version.go

@@ -9,7 +9,7 @@ var gitCommit string = "devel"
 
 const PROGRAM_NAME string = "fes"
 const PROGRAM_NAME_LONG string = "fes/fSD"
-const VERSION string = "beta"
+const VERSION string = "0.3.0"
 
 func Version() {
 	fmt.Printf("%s version %s\n", PROGRAM_NAME_LONG, VERSION)
@@ -20,3 +20,7 @@ func FullVersion() {
 	fmt.Printf("%s+%s\n", VERSION, gitCommit)
 	os.Exit(0)
 }
+
+func GetCommit() string {
+	return gitCommit
+}