darto: Instructions file for Codex

AGENTS.md

Guidance for AI coding agents working in this repository. For end-user API docs see darto/REFERENCE.md and https://darto-docs.vercel.app/.

For task-scoped procedures (add a route, validate a request, write middleware, scaffold a project), load the matching Claude Skill in skills/. Machine-readable docs for the site live at /llms.txt.

Overview

Darto is a minimal, type-safe web framework for pure Dart (no Flutter, no Node/JS). It is inspired by Express but its actual programming model is Hono-style: everything flows through a single Context object. This repo is a monorepo — the core darto package plus an ecosystem of plugins (darto_*) and runnable examples/.

The #1 thing to get right: Context, not (req, res, next)

Darto's lineage is Express, but as of v1.x the API is not Express. Do not write (Request req, Response res, Next next) handlers, res.send(), or Express-style error middleware — that is the old API and will not compile.

A handler takes a single Context c and returns a Response:

import 'package:darto/darto.dart';

void main() {
  final app = Darto();

  app.get('/users/:id', [], (Context c) {
    final id = c.req.param('id');   // read request via c.req
    return c.ok({'id': id});        // RETURN a response helper
  });

  app.listen(3000);
}

The three typedefs that define the whole framework:

typedef Handler    = FutureOr<Response>? Function(Context c);
typedef Middleware = FutureOr<void>      Function(Context c, Next next);
typedef Next       = Future<void>        Function();

Conventions an agent won't infer

• Middleware list is a required positional arg on every verb method. Pass [] when there is no route-level middleware: app.get(path, [middlewares], handler). Never omit it.
• Return responses, don't "send" them. Use the helpers and return them: c.ok, c.created, c.noContent, c.badRequest, c.unauthorized, c.forbidden, c.notFound, c.conflict, c.internalError, or typed c.json(data, [status]), c.text, c.html, c.redirect, c.binary, await c.file(...), await c.download(...). Chain status with c.status(206).json(...).
• c.body(...) is a response helper (raw body), not a request reader.
• Read the request through c.req: c.req.param('id') / paramInt, c.req.query('page') / queryInt / queryBool, c.req.header('...'), and the body via await c.req.json() (or c.req.json<T>(T.fromJson)), c.req.text(), c.req.blob().
• Per-request state: c.set('k', v) / c.get<T>('k'); auth shortcut c.user.
• Writing middleware: factory returning a closure; await next() to continue, return (without next) to short-circuit:

  Middleware requireAdmin() => (Context c, Next next) async {
    if (c.user?['role'] != 'admin') { c.forbidden(); return; }
    await next();
  };
  

• Error & 404 handling use Context too — not Express error middleware:

  app.onError((DartoError err, Context c) => c.internalError({'error': err.message}));
  app.notFound((Context c) => c.notFound({'error': 'not found'}));
  

• Validation is zValidator from darto_validator (Zod-style via zard), used as route middleware; read the result with c.req.valid<Map<String, dynamic>>('json' | 'query' | 'param').
• There is no built-in ORM/database layer. Don't introduce or assume one (e.g. "Dartonic") — persistence is left to the application.