AkurAI-Framework / CHANGELOG.md

Latest change 0ebc2057fd9a65182855334c219522ae944ad484 - docs: /docs guides for routing, forms, storage, middleware, SEO, styling + dev server by Ólafur Búi Ólafsson

# Changelog

All notable changes to AkurAI-Framework are documented here.
The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

Entries below the `## [Unreleased]` heading are maintained by hand during
development; `deploy.sh` cuts them into a versioned, dated section on release.

## [Unreleased]

### Added
- Workspace scaffold, `deploy.sh` release engine, `AGENTS.md` index.
- `akurai-http` crate (pure std, zero deps): HTTP/1.1 request-head parser,
  response builder, thread pool, and a blocking thread-pooled `Server`.
- `akurai` CLI binary: `new` bootstraps a project from embedded templates;
  `serve`/`dev` runs a lean static server with `/api/health`, `/api/_meta`,
  SPA fallback, MIME detection, and path-traversal protection.
- Default starter page (client-first, native ESM, no build step) that renders
  and live-pings the server's health endpoint.
- `akurai-json` crate (pure std, zero deps): order-preserving `Value`, a
  recursive-descent parser (string escapes, `\uXXXX` + surrogate pairs,
  int/float kept distinct so IDs round-trip exactly), and a serializer.
- `serve` now builds `/api/health` and `/api/_meta` from real JSON `Value`s
  instead of hand-spun strings.
- `akurai-storage` crate (pure std, zero deps): single-file `Pager` — fixed
  4 KiB pages, read/write/allocate, and `sync` for durability. The storage
  bedrock the B+tree and SQL layers will build on. B+tree node encode/decode added.
- `akurai-storage` crash-safe copy-on-write `BTree`: get/insert/delete/range
  over byte keys, path-copying mutations, leaf+interior node splits, and a
  double-buffered checksummed (FNV-1a) meta page for atomic, WAL-free commits —
  a torn commit recovers the previous tree from the other meta slot. An inline,
  page-capped free list recycles orphaned pages so rewrites don't grow the file.
- `akurai-markdown` crate (pure std, zero deps): Markdown → HTML (headings,
  lists, code blocks, blockquotes, inline code/bold/italic/links).
- **Documentation** — new `/docs` guides under a "Building" section for every
  recently shipped capability: Routing, Forms & actions, Storage, Middleware,
  SEO, and Styling (the CSS engine); the CLI page now covers `akurai dev` +
  live-reload. Closes the principle-#10 gap where features shipped without docs.
- **HTTP middleware chain** (`akurai-http`) — a `Middleware` trait + ordered
  `MiddlewareStack` run via `Server::run_with` (additive; `run` is unchanged),
  with built-ins: `SecurityHeaders` (nosniff / `X-Frame-Options: DENY` /
  `Referrer-Policy`), `RequestLogger`, and `Timing` (`X-Response-Time-Us`). Now
  active on `serve` — every response is hardened.
- **Atomic CSS engine core** (new `crates/css`) — pure-std, scans `class="…"`
  tokens and emits only the used utility CSS (parametric spacing on a 4px scale,
  flex/display, text, CSS-variable colours). `akurai_css::build(&sources)`. The
  from-scratch, no-Tailwind-dependency engine the no-build frontend will use.
- **SEO essentials** (`akurai-cli`) — `GET /sitemap.xml` (generated from the
  static routes in `routes.json`, param/wildcard routes excluded) and
  `GET /robots.txt`, plus optional per-route `title`/`description` injected into
  `<head>` (OpenGraph too), driven by a `site_url` in `page.json`.
- **Durable storage wired into `serve`** — the embedded B+tree now backs live
  requests. A small `store.rs` appends/lists JSON records on `data/store.db`
  (monotonic u64 keys → insertion order; every append commits, so it's durable
  immediately). The guestbook now **persists to disk** instead of memory — entries
  survive a server restart (and a redeploy). The store opens once and is shared
  behind a mutex (the B+tree is single-writer). This is the seed of the
  per-collection storage the auto-API will grow into.
- **Request bodies + form actions** — the HTTP server now reads request bodies
  (`Content-Length`, 8 MiB cap, bytes already buffered past the head reused),
  exposed as `Request.body` / `body_str()`. A new `akurai_http::form` parses
  `application/x-www-form-urlencoded` (percent-decode, `+`→space). On top: a
  **guestbook** form-actions demo (`/guestbook`) — a plain `<form method="post">`
  the server validates, stores, and redirects back from (Post/Redirect/Get),
  working with JavaScript disabled; user input is HTML-escaped by the template
  engine (verified against an injected `<script>`). Entries are in-memory for
  now (durable B+tree storage is the next slice).
- **Dynamic routing wired into `serve`** — an optional declarative
  `backend/routes.json` maps URL patterns to templates through `akurai-router`;
  `:param`/`*wildcard` captures are injected into the render context as
  `params`, so a template at `/hello/:name` reads `{{ params.name }}`
  (server-rendered, HTML-escaped, no client framework). Without the file the
  server keeps its previous behaviour, so existing projects are unaffected. The
  framework's own site now routes through it, with a `/hello/:name` live demo.
- **`akurai dev` live-reload** — the dev server now watches `frontend/`,
  `content/`, and `backend/` on a background thread and pushes a `reload` over
  SSE to the browser on any change (one injected native-`EventSource` script, no
  build step, no client dep). Strictly dev-only: `akurai serve` starts no
  watcher, injects nothing, and 404s the reserved `/_dev/*` namespace.
- **`akurai-router` crate (core)** — pure-std URL pattern matcher: static,
  `:param`, and `*wildcard` segments → captured params, ranked by specificity
  (static > param > wildcard) so exact routes never get shadowed. Transport-
  agnostic; the first step toward file/convention routing with dynamic segments.
- **Expanded `/components` library** — ~22 new pure-HTML/CSS, native-first,
  accessible components, reorganised into category groups (Actions, Forms, Data
  display, Feedback, Navigation, Overlays, Utilities) with a category index:
  button group, icon button, dropdown menu, split button; switch, input group,
  search, validation fields, file dropzone; description list, metrics, tags,
  avatars, code block; toast, banner, progress, spinner, skeleton, empty state;
  tabs, breadcrumbs, pagination, stepper, menu list; modal, drawer, popover,
  tooltip. Built by parallel agents into isolated fragments, assembled in order,
  and verified in real Chrome via CDP (all interactions work, no console errors).
- **Realtime: WebSocket + Server-Sent Events**, both pure `std`, zero deps,
  standards-compliant. `akurai-http` gains a connection-upgrade primitive
  (`Reply::Upgrade`) that hands the raw socket to a dedicated thread, plus an
  SSE `text/event-stream` writer (`sse()` / `SseSink`, spec framing). New
  `akurai-ws` crate implements RFC 6455: the handshake (from-scratch SHA-1 +
  base64, verified against the RFC accept vector), §5 framing with required
  client masking, fragmentation reassembly, automatic ping/pong, the close
  handshake, and UTF-8 / size / protocol validation with correct close codes.
  Demo endpoints `GET /api/ws` (echo) and `GET /api/events` (tick stream); see
  the new Realtime docs page. End-to-end tests drive a real handshake + masked
  echo and a live SSE read over TCP.
- **Design system documentation** under `site/content/docs/design-system/`: an
  overview, a foundations page (colour/type/spacing/radius/elevation/motion/
  z-index/breakpoint/theming tokens), and an extensive component catalog (~60
  components across actions, forms, data display, feedback, navigation,
  overlays, layout primitives, and the PocketBase-style admin shell — each with
  variants, states, markup, accessibility contract, and tokens). Wired into the
  docs sidebar; the build spec for `crates/css` and the frontend layer.
- `deploy.sh` now cuts the repo and website changelogs in lockstep and publishes
  to EC2 at the tail of a release, so the live `/changelog` always matches the
  shipped version; `version` in `site/backend/page.json` is bumped too.
- **Framework website** under `site/`, served by the framework itself: an
  authentic landing page, sidebar `/docs` (rendered from markdown), `/changelog`,
  an API reference, and a categorized `/components` library. Live at
  akurai-framework.olibuijr.com. The `akurai new` starter is now a clean minimal
  page (the SaaS-style showcase moved to `/components`).
- `serve` renders markdown content pages (`/docs/*`, `/changelog`) into a layout.

- `akurai-template` crate (pure std + internal json): server-side HTML template
  engine — `{{ var }}` (escaped) / `{{{ raw }}}`, `{% if/else %}`, `{% for %}`,
  `{% include %}`, `{# comments #}`, dotted paths, against a JSON `Value` context.
- `serve` is now SSR: registers every `frontend/*.html` as a template and renders
  pages against `backend/page.json`; static assets and `/api` unchanged.
- Bootstrap scaffolds a real component showcase (nav, hero, full form, cards,
  data table, alerts, badges) built entirely from templates + a JSON context.

### Note
- Local git history was reset once after an unclean reboot zeroed half the
  object store. Working tree was intact and verified; re-initialized from it.

### Verified
- 25 unit/integration tests green; clippy `-D warnings` clean.
- End-to-end locally: `akurai new` → `akurai serve` → page renders, health
  endpoint responds, ESM client fetch works (visual confirmation captured).
- Release binary: ~438 KB, zero runtime dependencies.