diff --git a/.gitignore b/.gitignore index 8efce08a7..f6c428691 100644 --- a/.gitignore +++ b/.gitignore @@ -52,6 +52,7 @@ website/static/api/ # Generated from docs/ by website/scripts/generate-llms-full.sh, which runs as the # prebuild step of every site build. Committing it only lets it drift. website/static/llms-full.txt +website/static/docs/ ### Maven ### # Machine-local heap tuning for the reactor. Maven reads it automatically, so a diff --git a/README.md b/README.md index 9df5cd0ef..20402755a 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ [![Kotlin 2.0+](https://img.shields.io/badge/Kotlin-2.0%2B-purple)](https://kotlinlang.org/) [![Java 21](https://img.shields.io/badge/Java-21-blue)](https://openjdk.org/projects/jdk/21/) -**Storm is the type-safe, SQL-first ORM for Kotlin 2.0+ and Java 21.** Immutable data-class entities, one-line queries checked at compile time, and none of the machinery you fight in traditional ORMs: no proxies, no N+1, no persistence context. +**Storm is the type-safe, SQL-first ORM for Kotlin 2.0+ and Java 21, built for agentic coding and performance.** Immutable data-class entities, one-line queries checked at compile time, and none of the machinery you fight in traditional ORMs: no proxies, no N+1, no persistence context. ```kotlin // An entity is a data class. This is the whole mapping. @@ -27,7 +27,7 @@ interface UserRepository : EntityRepository { } ``` -The `city` graph loads in a single query, and `User_` is generated at compile time so a typo is a compile error. What you write is what runs. +The `city` graph loads in a single query, and `User_` is generated at compile time so a typo is a compile error. What you write is what runs, which is also what makes Storm work so well with coding agents: the data class is the whole model, so the agent has the exact details it needs. Set your agent up with `npx @storm-orm/cli init` ([Agentic Coding](#agentic-coding)). ## Why Storm @@ -179,16 +179,20 @@ Both paths add the metamodel processor, which generates the `User_` and `City_` With the BOM imported, add Storm modules without specifying versions. -## AI-Assisted Development +## Agentic Coding -Storm's stateless, immutable model is a natural fit for AI coding tools: what you see in the source is exactly what runs, with no proxies, lazy loading, or hidden persistence-context rules to trip up generated code. An optional workflow gives AI tools full schema awareness through a local MCP server, guides them with Storm-specific skills, and closes the loop by verifying generated entities and queries with real tests rather than trusting model reasoning. +A coding agent is only as right as what it can read. In Storm the data class is the table, its keys and its relations, every database call is a visible line of code, and the domain model already gives one-line, type-safe queries across relations. There are no proxies, no lazy loading and no persistence context, so the code the agent reads is exactly what runs. + +One command sets your agent up: ```bash -npm install -g @storm-orm/cli -storm init +npx @storm-orm/cli init # in your project: rules, skills and schema access +npx @storm-orm/cli demo # in an empty directory: your agent builds a demo app on Storm ``` -See [AI-Assisted Development](docs/ai.md) for the full workflow. +It installs Storm's rules and skills for Claude Code, Cursor, GitHub Copilot, Windsurf and Codex. An existing `CLAUDE.md` or rules file keeps its content; Storm adds its own marked block. Optionally it sets up an MCP server that runs on your machine and is read-only: the agent sees your schema, never your credentials, and sees data only if you allow it. The agent then checks its own work with `validateSchema()` and `SqlCapture`. + +See [Agentic Coding](docs/ai.md) for the full workflow. ## Examples diff --git a/docs/ai-reference.md b/docs/ai-reference.md index fbd85ade3..1948a8ac5 100644 --- a/docs/ai-reference.md +++ b/docs/ai-reference.md @@ -1,6 +1,6 @@ # AI Tools Reference -This page lists the configuration locations, skills, and database skills that Storm installs for each AI coding tool. For the main guide, see [AI-Assisted Development](ai.md). +This page lists the configuration locations, skills, and database skills that Storm installs for each AI coding tool. For the main guide, see [Agentic Coding](ai.md). --- diff --git a/docs/ai.md b/docs/ai.md index 7e3e5b483..213f64705 100644 --- a/docs/ai.md +++ b/docs/ai.md @@ -1,29 +1,41 @@ -# AI-Assisted Development +# Agentic Coding import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -Storm is an AI-first ORM. Entities are plain Kotlin data classes or Java records. Queries are explicit SQL. Built-in verification lets AI validate its own work before anything touches production. +Storm is built for agentic coding. A coding agent is only as right as what it can read, and in Storm every detail lives in the model: your data classes define the tables, keys and relations, and the queries follow from them. Underneath is a thin layer over JDBC, so nothing sits between the model and the database. -:::info AI-first, not AI-only -Storm keeps you in control. `ORMTemplate.validateSchema()` validates that entities match the database. `SqlCapture` validates that queries match the intent. `@StormTest` runs both checks in an isolated in-memory database before anything reaches production. The AI generates code, then Storm verifies it. That is what AI-first means here. +- **What you see is what runs.** No proxies, no lazy loading, no persistence context, no flush. An entity is a value, and every database call is a visible line of code. +- **All in one place.** One data class is the table, its keys and its relations. There is no second table definition beside it and no session state deciding at runtime what a field holds. The agent reads one file and has the full picture. +- **Queries come from the domain.** The entities already give one-line, type-safe queries across relations, with the whole entity graph loaded in one statement. There is less for the agent to write, and fewer joins and mappings to get wrong. + +Good for your agent, good for you: the same properties that make Storm code easy to generate correctly make it easy to review. On top of that, Storm gives the agent its conventions (rules and skills), your schema (a local, read-only MCP server), and a way to check its own work (`validateSchema()` and `SqlCapture`). + +:::info You stay in control +`ORMTemplate.validateSchema()` validates that entities match the database. `SqlCapture` validates that queries match the intent. `@StormTest` runs both checks in an isolated in-memory database before anything reaches production. The agent generates code, then Storm verifies it. ::: --- ## Quick Setup -Install the Storm CLI and run it in your project: +Run the Storm CLI from the root of your project. Nothing to install first: ```bash -npm install -g @storm-orm/cli -storm init +npx @storm-orm/cli init ``` -Or without installing globally: +Starting from an empty directory instead? `demo` creates a Kotlin project and installs a skill that guides your agent to build a small web application on Storm, using the public IMDB dataset: ```bash -npx @storm-orm/cli init +npx @storm-orm/cli demo +``` + +If you will use the CLI again, for `storm update` (refresh rules and skills), `storm db` (manage database connections) or `storm mcp` (manage a project's MCP servers), install it globally: + +```bash +npm install -g @storm-orm/cli +storm init ``` The interactive setup walks you through three steps: @@ -36,13 +48,13 @@ Choose which AI coding tools you use. Storm configures each one with rules, skil For each selected tool, Storm installs two types of AI context: -**Rules** are a project-level configuration file that is always loaded by the AI tool. They contain Storm's key patterns, naming conventions, and critical constraints (immutable QueryBuilder, no collection fields on entities, `Ref` for circular references, etc.). The rules ensure the AI follows Storm's conventions in every interaction, without you having to repeat them. +**Rules** are a project-level configuration file that is always loaded by the AI tool. When the file already exists (an existing `CLAUDE.md`, for example), its content is kept: Storm adds its rules as a marked block, and later runs replace only that block. They contain Storm's key patterns, naming conventions, and critical constraints (immutable QueryBuilder, no collection fields on entities, `Ref` for circular references, etc.). The rules ensure the AI follows Storm's conventions in every interaction, without you having to repeat them. **Skills** are per-topic guides that the AI loads on demand when working on a specific task. Each skill contains focused instructions, code examples, and common pitfalls for one area of Storm (entities, queries, repositories, migrations, JSON, serialization, and more). Skills are fetched from orm.st during setup and can be updated automatically on each run without requiring a CLI update. See [AI Tools Reference](ai-reference.md#skills) for the full list. ### 3. Database connection (optional) -If you have a local development database running, Storm can set up a schema-aware MCP server. This gives your AI tool access to your actual database structure (table definitions, column types, foreign keys) without exposing credentials or data. +If you have a local development database running, Storm can set up a schema-aware MCP server. This gives your AI tool access to your actual database structure (table definitions, column types, foreign keys) without exposing credentials or data. The server runs on your machine and is read-only: it cannot write, modify or delete anything. The MCP server runs locally on your machine, exposes only schema metadata by default, and stores credentials in `~/.storm/` (outside your project, outside the LLM's reach). It supports PostgreSQL, MySQL, MariaDB, Oracle, SQL Server, SQLite, and H2. You can connect multiple databases to a single project, even across different database types. @@ -95,11 +107,11 @@ Most AI coding tools support adding context through URLs or pasted text. Point y --- -## Why Storm Works Well With AI +## Why Storm Works Well With Agents -AI works better when framework behavior is explicit and visible in source code. +Agents work better when framework behavior is explicit and visible in source code. -Traditional ORMs rely on mechanisms that are powerful but implicit: proxy objects that intercept field access, lazy loading that triggers queries at unpredictable moments, persistence contexts that track entity state across transaction boundaries, and cascading rules that propagate changes through the object graph. These features serve real purposes, but they make AI-assisted development harder. The AI has to account for behavior that does not appear in the code. Code that compiles and looks correct can still break at runtime because of invisible framework state. +Traditional ORMs rely on mechanisms that are powerful but implicit: proxy objects that intercept field access, lazy loading that triggers queries at unpredictable moments, persistence contexts that track entity state across transaction boundaries, and cascading rules that propagate changes through the object graph. These features serve real purposes, but they make agentic coding harder. The AI has to account for behavior that does not appear in the code. Code that compiles and looks correct can still break at runtime because of invisible framework state. Storm eliminates all of that. Entities are plain Kotlin data classes or Java records. There are no proxies, no managed state, no persistence context, and no transparent lazy loading: deferred loading is explicit, through `Ref`. Queries are explicit, and what you see in the source code is exactly what happens at runtime. This makes Storm's behavior predictable for AI tools: the code is the complete picture. @@ -112,7 +124,7 @@ The design choices that matter most: - **Compile-time metamodel.** Type errors caught at build time, not at runtime. The AI gets immediate feedback. - **Secure schema access.** The MCP server gives AI tools structural database knowledge without exposing credentials. Data access is opt-in, read-only by construction, and enforced at the database driver level. -Beyond the data model, Storm provides dedicated tooling for AI-assisted workflows: +Beyond the data model, Storm provides dedicated tooling for agentic workflows: - **Skills** guide AI tools through specific tasks (entity creation, queries, repositories, migrations) with framework-aware conventions and rules. - **A locally running MCP server** gives AI tools access to your live database schema: table definitions, column types, constraints, and foreign keys. Optionally, the AI can also query individual records (read-only) when sample data would improve type decisions. The AI can inspect your actual database structure to generate entities that match, or validate entities it just created. @@ -305,9 +317,9 @@ You can also ask the AI to keep the test as a permanent regression test. The cho --- -## The Gold Standard: Verify, Then Trust +## Verify, Then Trust -This is what makes Storm the gold standard for AI-assisted database development. The AI does not just generate code and hope for the best. It generates code, then validates it through Storm's own verification, before anything is committed. +The AI does not just generate code and hope for the best. It generates code, then validates it through Storm's own verification, before anything is committed. | Task | AI generates | Storm verifies | |------|-------------|-------------------| diff --git a/docs/getting-started.md b/docs/getting-started.md index eb79b71d5..e1e463cb1 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -1,7 +1,7 @@ --- title: Set Up Your Project sidebar_label: Set Up Your Project -description: "Wire Storm into a project you intend to keep: prerequisites, the four setup routes, and how to verify the result." +description: "Wire Storm into a project you intend to keep: prerequisites, the four setup routes (fastest with a coding agent), and how to verify the result." --- import Tabs from '@theme/Tabs'; @@ -9,7 +9,7 @@ import TabItem from '@theme/TabItem'; # Set Up Your Project -This page is about getting Storm into a real project: what it needs from your toolchain, which of the four setup routes fits your situation, and how to prove the wiring works before you write application code. +This page is about getting Storm into a real project: what it needs from your toolchain, which of the four setup routes fits your situation, and how to prove the wiring works before you write application code. If you work with a coding agent, the fastest route is to let it do the wiring: one command gives it everything it needs. :::tip Just want to see it work? The **[Quickstart](/quickstart)** takes about five minutes, needs no database server, and ends with a working query and the SQL it generated. It is the fastest way to judge Storm, and it is the recommended first stop. Come back here when you are setting up a project you intend to keep. @@ -31,10 +31,35 @@ The JDK 21 pin is a property of the platform, not of Storm: the Java API is buil ## Choose a Setup Route -All four routes end at the same place: a project with the Storm dependencies, the metamodel processor, and the Kotlin compiler plugin wired up. +All four routes end at the same place: a project with the Storm dependencies, the metamodel processor, and the Kotlin compiler plugin wired up. With a coding agent, the agent does this for you; the other three routes are the same setup by hand. - + + +### Setup with a coding agent (fastest) + +If you work with a coding agent (Claude Code, Cursor, GitHub Copilot, Windsurf, or Codex), let it do the wiring. Run one command from the root of your project: + +```bash +npx @storm-orm/cli init +``` + +It installs Storm's rules and skills for your agent, so the agent knows the conventions, the build setup for Gradle and Maven, and the common pitfalls. An existing `CLAUDE.md` or rules file keeps its content: Storm adds its own marked block. Optionally, it connects a schema-aware MCP server to your development database. That server runs on your machine and is read-only: the agent sees your schema, never your credentials, and sees data only if you allow it. + +Then ask the agent for what you need, for example: + +- *"Add Storm to this project with the Gradle plugin and the PostgreSQL dialect."* +- *"Generate Storm entities for the `customer` and `order` tables, and validate them against the schema."* +- *"Write a repository method that finds a customer's open orders, and show me the SQL it runs."* + +Storm entities carry every detail in the model, so the agent has what it needs to act, and it can check its own work: `validateSchema()` confirms the entities match the database, and `SqlCapture` shows the SQL a query really runs. + +Starting from an empty directory instead? `npx @storm-orm/cli demo` creates a Kotlin project and has your agent build a small web application on Storm. + +See [Agentic Coding](ai.md) for the full workflow and [Database Connections & MCP](database-and-mcp.md) for the schema-aware server. + + + ### Gradle plugin (recommended for Kotlin) @@ -85,21 +110,6 @@ Each starter template is a GitHub template repository holding one vertical slice What each one contains is on the [starter templates page](/templates/). The [example projects](/examples/) are a different thing: complete applications on the public IMDB dataset, written to be read and run rather than started from. - - - -### AI-assisted setup - -If you work with an AI coding tool (Claude Code, Cursor, GitHub Copilot, Windsurf, or Codex), one command installs Storm's rules and skills for it and can connect it to your development database: - -```bash -npx @storm-orm/cli init -``` - -The tool can then add the dependencies, generate entities from your existing tables, and write repository methods. It has Storm's documentation and, with the MCP server configured, your real schema. - -See [AI-Assisted Development](ai.md) for the full setup and [Database and MCP](database-and-mcp.md) for the schema-aware server. - diff --git a/docs/index.md b/docs/index.md index 89749c009..e496e87d4 100644 --- a/docs/index.md +++ b/docs/index.md @@ -8,7 +8,7 @@ import TabItem from '@theme/TabItem'; # Storm -**Storm** is an ORM for Kotlin 2.0+ and Java 21, built on a SQL template engine. Entities are plain immutable data classes and records, queries are checked at compile time, and every database call is explicit: no proxies, no persistence context, no accidental N+1 queries. +**Storm** is an ORM for Kotlin 2.0+ and Java 21, built for agentic coding and performance on a SQL template engine. Entities are plain immutable data classes and records, queries are checked at compile time, and every database call is explicit: no proxies, no persistence context, no accidental N+1 queries. ## Start Here @@ -16,6 +16,7 @@ import TabItem from '@theme/TabItem'; |----------------|-------| | See Storm work end to end, in five minutes | **[Quickstart](/quickstart)** | | Add Storm to a project you already have | [Set Up Your Project](getting-started.md) | +| Work with a coding agent (Claude Code, Cursor, Copilot, Windsurf, Codex) | [Agentic Coding](ai.md): `npx @storm-orm/cli init` | | Understand the model before writing code | [Entities](entities.md), then [Queries](queries.md) | | Decide whether to adopt it | [Evaluating for Production](#evaluating-for-production) | @@ -169,7 +170,7 @@ To talk the evaluation through with the engineers behind Storm, write to [hello@ Storm is focused on being a great ORM and SQL template engine. It intentionally does not include: -- **Schema migration or DDL generation.** Storm does not automatically create, alter, or drop tables at runtime. With Storm's [AI integration](ai.md), your coding assistant can read your database schema and generate Flyway or Liquibase migration scripts on demand. For schema versioning, use [Flyway](https://flywaydb.org/) or [Liquibase](https://www.liquibase.com/). +- **Schema migration or DDL generation.** Storm does not automatically create, alter, or drop tables at runtime. With Storm's [agentic coding support](ai.md), your coding agent can read your database schema and generate Flyway or Liquibase migration scripts on demand. For schema versioning, use [Flyway](https://flywaydb.org/) or [Liquibase](https://www.liquibase.com/). - **Second-level cache.** Storm's entity cache is transaction-scoped and cleared on commit. For cross-transaction caching, use Spring's `@Cacheable` or a dedicated cache layer like Caffeine or Redis. - **Lazy loading proxies.** Entities are plain records with no proxies. Related entities are loaded eagerly in a single query via JOINs. For deferred loading, use [Refs](refs.md) to explicitly control when related data is fetched. @@ -186,17 +187,17 @@ See [Database Dialects](dialects.md) for installation and configuration details. - Kotlin 2.0+ (JDK 21 or later), or Java on JDK 21 exactly (the Java API uses preview class files, which are version-locked) - Maven 3.9+ or Gradle 8+ -## AI-Assisted Development +## Agentic Coding -Storm's stateless, immutable entities mean what you see in the source code is exactly what exists at runtime: no hidden proxies, no lazy loading surprises, no persistence context rules that trip up generated code. When you ask an AI tool to write a query, define an entity, or build a repository, the output is straightforward data classes and explicit SQL. +Storm is built for agentic coding. What you see in the source code is exactly what runs: no hidden proxies, no lazy loading surprises, no persistence context rules that trip up generated code. One data class is the table, its keys and its relations, and the domain model already gives one-line, type-safe queries, so your agent has the exact details it needs and less to write. -One command configures your tool (Claude Code, Cursor, Copilot, Windsurf, or Codex) with Storm's rules, skills, and slash commands, and can connect it to your development database for schema-aware generation: +One command configures your tool (Claude Code, Cursor, Copilot, Windsurf, or Codex) with Storm's rules, skills, and slash commands, and can connect it to your development database through a local, read-only MCP server for schema-aware generation: ```bash npx @storm-orm/cli init ``` -See [AI-Assisted Development](ai.md) for the full setup, and [Database and MCP](database-and-mcp.md) for the schema-aware server. +See [Agentic Coding](ai.md) for the full setup, and [Database and MCP](database-and-mcp.md) for the schema-aware server. ## Glossary diff --git a/website/docusaurus.config.ts b/website/docusaurus.config.ts index 6b8b27889..4208e7870 100644 --- a/website/docusaurus.config.ts +++ b/website/docusaurus.config.ts @@ -25,7 +25,7 @@ const CONTACT_EMAIL = 'hello@orm.st'; const config: Config = { title: 'Storm Framework', - tagline: 'A modern, high-performance ORM for Kotlin 2.0+ and Java 21+', + tagline: 'A modern ORM for Kotlin 2.0+ and Java 21+, built for agentic coding and performance', favicon: 'img/storm-dark.png', // Load the marketing type pair (Inter + JetBrains Mono) on the docs pages too, @@ -244,6 +244,11 @@ const config: Config = { position: 'left', label: 'Documentation', }, + { + to: '/docs/ai', + label: 'AI', + position: 'left', + }, { to: '/tutorials/', label: 'Tutorials', @@ -283,6 +288,7 @@ const config: Config = { title: 'Learn', items: [ {label: 'Quickstart', to: '/quickstart'}, + {label: 'Agentic coding', to: '/docs/ai'}, {label: 'Installation', to: '/docs/installation'}, {label: 'Entities', to: '/docs/entities'}, {label: 'Queries', to: '/docs/queries'}, diff --git a/website/plugins/static-version-replace.js b/website/plugins/static-version-replace.js index a28dff6c7..e9c9b5c37 100644 --- a/website/plugins/static-version-replace.js +++ b/website/plugins/static-version-replace.js @@ -1,7 +1,8 @@ /** * Docusaurus plugin that replaces @@STORM_VERSION@@ in static files after they * are copied to the build output: the per-tool skill files (static/skills/*.md) - * and the AI-facing docs indexes (static/llms.txt and static/llms-full.txt). + * the AI-facing docs indexes (static/llms.txt and static/llms-full.txt) and the + * per-page Markdown copies of the docs (static/docs/**.md). * These files are copied verbatim and never pass through the remark version * plugin, so this postBuild pass is what keeps their install snippets on the * current version. @@ -34,6 +35,14 @@ module.exports = function staticVersionReplace(context, options) { // AI-facing docs indexes copied from static/. replaceInFile(path.join(outDir, 'llms.txt')); replaceInFile(path.join(outDir, 'llms-full.txt')); + + // Per-page Markdown copies of the docs, generated into static/docs/. + for (const dir of [path.join(outDir, 'docs'), path.join(outDir, 'docs', 'next')]) { + if (!fs.existsSync(dir)) continue; + for (const name of fs.readdirSync(dir)) { + if (name.endsWith('.md')) replaceInFile(path.join(dir, name)); + } + } }, }; }; diff --git a/website/scripts/generate-llms-full.sh b/website/scripts/generate-llms-full.sh index 91c4d79ae..3a5c497b8 100755 --- a/website/scripts/generate-llms-full.sh +++ b/website/scripts/generate-llms-full.sh @@ -1,6 +1,8 @@ #!/usr/bin/env bash # -# Generates llms-full.txt from all documentation files in sidebar order. +# Generates llms-full.txt from all documentation files in sidebar order, and a +# plain Markdown copy of every docs page beside its HTML route, so an agent can +# fetch /docs/.md instead of scraping the rendered page. # Strips Docusaurus-specific syntax (imports, JSX components, frontmatter, admonitions). # # Usage: bash website/scripts/generate-llms-full.sh @@ -23,6 +25,10 @@ DOCS=( first-entity.md first-query.md glossary.md + # Agentic Coding + ai.md + ai-reference.md + database-and-mcp.md # Core Concepts entities.md projections.md @@ -71,9 +77,6 @@ DOCS=( faq.md migration-from-jpa.md jpa-cascades-vs-write-sets.md - ai.md - ai-reference.md - database-and-mcp.md # API Reference api-kotlin.md api-java.md @@ -135,20 +138,23 @@ strip_docusaurus() { cat > "$OUTPUT" <<'HEADER' # Storm Framework - Complete Documentation -> Storm is an AI-first ORM framework for Kotlin 2.0+ and Java 21+, the gold -> standard for AI-assisted database development. +> Storm is an ORM for Kotlin 2.0+ and Java 21+, built for agentic coding and +> performance. > -> It uses immutable data classes and records instead of proxied entities, -> providing type-safe queries, predictable performance, and zero hidden magic. -> Storm works perfectly standalone, but its design and tooling make it uniquely -> suited for AI-assisted development: immutable entities produce stable code, -> the CLI installs per-tool skills, and a locally running MCP server exposes -> only schema metadata (table definitions, column types, constraints) while -> shielding your database credentials and data from the LLM. Built-in -> verification (validateSchema(), SqlCapture) lets the AI validate its own work -> before anything is committed. +> Every detail lives in the model. Entities are plain Kotlin data classes or Java +> records: one class is the table, its keys and its relations, and the queries +> follow from it. Underneath is a thin layer over JDBC. There is no persistence +> context, no transparent lazy loading, no proxy generation, and no entity state +> management, so the code is exactly what runs. The domain model gives one-line, +> type-safe queries across relations, returning the whole entity graph in one +> statement. The CLI installs rules and skills for coding +> agents, plus a local MCP server that exposes only schema metadata while +> keeping database credentials away from the LLM. Built-in verification +> (validateSchema(), SqlCapture) lets the agent check its own work before +> anything is committed. > -> Get started: `npx @storm-orm/cli` +> Get started: `npx @storm-orm/cli init` (existing project) or +> `npx @storm-orm/cli demo` (empty directory) > Website: https://orm.st > GitHub: https://github.com/storm-orm/storm-framework > License: Apache 2.0 @@ -173,3 +179,22 @@ for doc in "${DOCS[@]}"; do done echo "Generated $OUTPUT" + +# Per-page Markdown. /docs/ serves the latest released snapshot and +# /docs/next/ the docs in this repository, so each gets its Markdown copy +# from the same source: /docs/.md and /docs/next/.md. The output is +# generated on every build and not committed. +write_markdown_pages() { + local src="$1" out="$2" + mkdir -p "$out" + for filepath in "$src"/*.md; do + strip_docusaurus < "$filepath" > "$out/$(basename "$filepath")" + done +} +MARKDOWN_OUT="$WEBSITE_DIR/static/docs" +LATEST_VERSION="$(node -p "require('$WEBSITE_DIR/versions.json')[0]")" +rm -rf "$MARKDOWN_OUT" +write_markdown_pages "$WEBSITE_DIR/versioned_docs/version-$LATEST_VERSION" "$MARKDOWN_OUT" +write_markdown_pages "$DOCS_DIR" "$MARKDOWN_OUT/next" + +echo "Generated Markdown pages in $MARKDOWN_OUT" diff --git a/website/sidebars.ts b/website/sidebars.ts index 9a1373c44..71eabfb0a 100644 --- a/website/sidebars.ts +++ b/website/sidebars.ts @@ -25,6 +25,15 @@ const sidebars: SidebarsConfig = { 'glossary', ], }, + { + type: 'category', + label: 'Agentic Coding', + items: [ + 'ai', + 'ai-reference', + 'database-and-mcp', + ], + }, { type: 'category', label: 'Core Concepts', @@ -107,9 +116,6 @@ const sidebars: SidebarsConfig = { 'faq', 'migration-from-jpa', 'jpa-cascades-vs-write-sets', - 'ai', - 'ai-reference', - 'database-and-mcp', ], }, { diff --git a/website/src/components/tutorial/tutorialTheme.js b/website/src/components/tutorial/tutorialTheme.js index 69bd89c87..9efaca5b0 100644 --- a/website/src/components/tutorial/tutorialTheme.js +++ b/website/src/components/tutorial/tutorialTheme.js @@ -305,6 +305,7 @@ export const navHtml = (active) => `
+ AI Tutorials Examples Comparison @@ -342,7 +343,7 @@ export const heroArt = (page, {priority = false} = {}) => ` export const FOOT_HTML = ` `; export const TUT_CSS = ` @@ -370,6 +371,7 @@ export const TUT_CSS = ` .storm-tut .brand b{font-family:var(--mono);font-weight:700} .storm-tut .tech-tag{font-family:var(--mono);font-size:11px;color:var(--faint);letter-spacing:.02em;border-left:1px solid var(--border);padding-left:12px} .storm-tut .nav-links{display:flex;align-items:center;gap:24px;font-size:14px;color:var(--muted)} + .storm-tut .nav-links a{white-space:nowrap} .storm-tut .nav-links a:hover{color:var(--text)} .storm-tut .nav-links a.on{color:var(--text)} .storm-tut .nav-toggle{display:none} @@ -423,6 +425,9 @@ export const TUT_CSS = ` .storm-tut .sqlbtn:hover,.storm-tut .copybtn:hover{background:rgba(129,140,248,.12);border-color:rgba(129,140,248,.5)} .storm-tut .sqlbtn.on,.storm-tut .copybtn.on{background:rgba(129,140,248,.16);color:#aab2ff} .storm-tut .sqlbtn .ico,.storm-tut .copybtn .ico{width:13px;height:13px;opacity:.9} + .storm-tut .clonebar{display:flex;align-items:center;gap:10px;font-family:var(--mono);font-size:13px;color:var(--plain); + background:var(--panel);border:1px solid var(--border);border-radius:10px;padding:0 18px;min-height:44px;overflow-x:auto;white-space:nowrap} + .storm-tut .clonebar .dollar{color:var(--green);user-select:none} .storm-tut .clonebar .clonecmd{overflow-x:auto} .storm-tut .clonebar .copybtn{margin-left:auto;flex:none;gap:0;padding:5px 8px} .storm-tut .clonebar .copybtn .ico-check{display:none} @@ -630,10 +635,12 @@ export const TUT_CSS = ` .storm-tut footer{border-top:1px solid var(--border-soft);margin-top:70px;padding:36px 0;color:var(--faint);font-size:13.5px} .storm-tut .foot{display:flex;justify-content:space-between;align-items:center;flex-wrap:wrap;gap:14px} .storm-tut .foot .links{display:flex;gap:22px;font-family:var(--mono);flex-wrap:wrap}.storm-tut .foot a{color:var(--muted)}.storm-tut .foot a:hover{color:var(--text)} - @media(max-width:920px){.storm-tut .tech-tag{display:none}} - /* Mobile: replace the row of links with a hamburger that drops down a full - menu (CSS-only via a hidden checkbox, so no JS is needed on any page). */ - @media(max-width:760px){ + @media(max-width:1100px){.storm-tut .tech-tag{display:none}} + /* Narrow screens: replace the row of links with a hamburger that drops down a + full menu (CSS-only via a hidden checkbox, so no JS is needed on any page). + The breakpoint is where the full row of links stops fitting beside the + brand, not the phone breakpoint. */ + @media(max-width:1000px){ /* The menu is CSS-only (a checkbox drives the drop-down), so the checkbox is the control a keyboard reaches: clipped to 1px rather than display:none, which would take it out of the tab order and leave the mobile menu diff --git a/website/src/pages/benchmarks.js b/website/src/pages/benchmarks.js index 3a79c756a..b8f2c39ec 100644 --- a/website/src/pages/benchmarks.js +++ b/website/src/pages/benchmarks.js @@ -1559,9 +1559,6 @@ const BM_CSS = ` .storm-tut .art h3 + p{margin-top:0} .bm-stat b{background:linear-gradient(100deg,#feeeb0,#fbbf24 55%,#f59e0b);-webkit-background-clip:text;background-clip:text;color:transparent} .storm-tut .getit{display:flex;gap:12px;margin-top:26px;flex-wrap:wrap;align-items:stretch} - .storm-tut .clonebar{display:flex;align-items:center;gap:10px;font-family:var(--mono);font-size:13px;color:var(--plain); - background:var(--panel);border:1px solid var(--border);border-radius:10px;padding:0 18px;min-height:44px;overflow-x:auto;white-space:nowrap} - .storm-tut .clonebar .dollar{color:var(--green);user-select:none} .bm-lc{border:1px solid var(--border);border-radius:14px;background:#050507;margin:22px 0 10px;padding:20px 20px 14px} .bm-lc-head{display:flex;justify-content:space-between;align-items:baseline;gap:16px;flex-wrap:wrap;margin-bottom:8px} .storm-tut .art .bm-lc h3{margin:0;font-size:14.5px;color:var(--body)} diff --git a/website/src/pages/comparison.js b/website/src/pages/comparison.js index e26327155..5368b371c 100644 --- a/website/src/pages/comparison.js +++ b/website/src/pages/comparison.js @@ -98,7 +98,7 @@ ${navHtml('comparison')}

Your options.
Side by side.

-

There is no universally best data framework. Storm is built for teams who want explicit, predictable database access with concise, immutable models. Here is where it sits next to the alternatives, and where each of them is the better call.

+

There is no universally best data framework. Storm is built for teams, and the coding agents working alongside them, who want explicit, predictable database access with concise, immutable models. Here is where it sits next to the alternatives, and where each of them is the better call.

${heroArt('comparison', {priority: true})}
@@ -107,6 +107,10 @@ ${navHtml('comparison')}

Decision-relevant differences across the most common choices. This page compares the designs; the measured numbers, on identical workloads, live on the benchmarks page.

${matrix} +

When an agent writes the code

+

Three rows above decide how well a coding agent does with a framework. Entity model: in Storm one data class is the table, its keys and its relations, so the agent reads one file and has the full picture. Session state: with none, the code the agent reads is exactly what runs, and no flush or proxy acts on it later. Query across relations: the domain model already gives one-line, type-safe queries with the whole entity graph loaded, so there is less for the agent to write and fewer joins and mappings to get wrong.

+

On top of that, one command, npx @storm-orm/cli init, installs Storm's rules and skills for Claude Code, Cursor, GitHub Copilot, Windsurf and Codex, plus a local, read-only MCP server that gives the agent your schema without your credentials. See the agentic coding guide.

+

Framework by framework

A short, fair take on each. Every card links to the full pairing in the docs, with feature tables and code.

diff --git a/website/src/pages/index.js b/website/src/pages/index.js index 20b3e0641..b2522b2ff 100644 --- a/website/src/pages/index.js +++ b/website/src/pages/index.js @@ -27,6 +27,12 @@ const DISCORD = 'https://discord.gg/SgQpcweUJD'; // conduct reports have their own address, dev@orm.st. const CONTACT_EMAIL = 'hello@orm.st'; +// The CLI commands. The hero's terminal scene runs `init` through npx, so a +// visitor can copy one line without installing anything; the agentic coding +// section installs the CLI once and then uses the `storm` commands. +const CLI_INIT = 'npx @storm-orm/cli init'; +const CLI_INSTALL = 'npm install -g @storm-orm/cli'; + const CSS = ` :root{ --bg:#070709; --panel:#0f0f14; --panel-2:#0b0b0f; --statusbg:#08080b; @@ -56,6 +62,7 @@ const CSS = ` .storm-home .brand b{font-family:var(--mono);font-weight:700} .storm-home .tech-tag{font-family:var(--mono);font-size:11px;color:var(--faint);letter-spacing:.02em;border-left:1px solid var(--border);padding-left:12px} .storm-home .nav-links{display:flex;align-items:center;gap:24px;font-size:14px;color:var(--muted)} + .storm-home .nav-links a{white-space:nowrap} .storm-home .nav-links a:hover{color:var(--text)} .storm-home .nav-toggle{display:none} /* Off entirely above the breakpoint, where the links are always visible and a @@ -153,8 +160,6 @@ const CSS = ` .storm-home .sub-lead{font-size:16.5px;margin-top:16px} .storm-home .hero-cta{margin-top:20px} .storm-home .hero-cta .btn{flex:1 1 100%;justify-content:center;height:44px} - .storm-home .hero-talk{align-items:flex-start;margin-top:14px;font-size:13.5px} - .storm-home .hero-talk .ico{margin-top:2px} .storm-home .stage{margin-top:34px} } .storm-home .sub{max-width:600px;margin:24px 0 0;color:var(--muted);font-size:18px;line-height:1.62} @@ -170,14 +175,18 @@ const CSS = ` /* Hero CTA: the primary conversion action, kept high so it sits above the fold on phones. */ .storm-home .hero-cta{margin-top:26px} - /* The invitation to talk sits under the buttons, quieter than them, so it - reads as the next option rather than a third call to action. The address - is the link text so a reader whose browser has no mail client behind - mailto can still copy it. */ - .storm-home .hero-talk{display:flex;align-items:center;gap:9px;margin:18px 0 0;color:var(--muted);font-size:14.5px;line-height:1.5} - .storm-home .hero-talk .ico{width:16px;height:16px;flex:none;color:var(--accent)} - .storm-home .hero-talk a{color:var(--accent);font-weight:600;white-space:nowrap} - .storm-home .hero-talk a:hover{text-decoration:underline} + /* The copyable command chip, used in the agentic coding section. + The check mark replaces the copy icon for a moment after a copy. */ + .storm-home .clichip{display:inline-flex;align-items:center;gap:10px;height:36px;padding:0 12px;border-radius:9px;cursor:pointer; + font-family:var(--mono);font-size:13px;color:var(--text);border:1px solid rgba(129,140,248,.3);background:var(--panel-2);transition:border-color .16s,background .16s} + .storm-home .clichip:hover{border-color:rgba(129,140,248,.6);background:rgba(129,140,248,.08)} + .storm-home .clichip code{font-family:inherit;font-size:inherit;background:none;border:0;padding:0;color:inherit;white-space:nowrap} + .storm-home .clichip .dollar{color:var(--accent)} + .storm-home .clichip .ico{width:14px;height:14px;flex:none;color:var(--muted);margin-left:auto} + .storm-home .clichip .ico-check{display:none;color:var(--green)} + .storm-home .clichip.on{border-color:rgba(94,234,212,.5)} + .storm-home .clichip.on .ico-copy{display:none} + .storm-home .clichip.on .ico-check{display:inline-block} /* editor */ .storm-home .stage{margin:54px 0 0;max-width:880px} @@ -192,6 +201,9 @@ const CSS = ` .storm-home .sqlbtn:hover{background:rgba(129,140,248,.12);border-color:rgba(129,140,248,.5)} .storm-home .sqlbtn[aria-expanded="true"]{background:rgba(129,140,248,.16);color:#aab2ff} .storm-home .sqlbtn .ico{width:13px;height:13px;opacity:.9} + /* Copy control for the terminal scene; it takes the Show SQL slot, which + that scene has no use for. */ + .storm-home .clicopy.on{color:var(--green);border-color:rgba(94,234,212,.5)} .storm-home .sqlconsole{display:none;border-top:1px solid var(--border-soft);background:var(--statusbg)} .storm-home .editor.show-sql .sqlconsole{display:block} /* Solid background required on the horizontal scroller: on iOS Safari an @@ -270,6 +282,36 @@ const CSS = ` .storm-home .card .ic{width:34px;height:34px;border-radius:9px;display:grid;place-items:center;color:var(--accent); background:rgba(129,140,248,.1);border:1px solid rgba(129,140,248,.2);margin-bottom:16px} + /* Agentic coding: why the model suits a coding agent (three cards), then the + one command that sets the agent up. */ + .storm-home section.agents{padding:64px 0 40px} + .storm-home .agents .alabel{font-family:var(--mono);font-size:11px;letter-spacing:.16em;text-transform:uppercase;color:var(--accent)} + .storm-home .agents h2{font-size:clamp(28px,4vw,40px);letter-spacing:-.03em;font-weight:800;margin:10px 0 0} + .storm-home .agents .lede{color:var(--muted);font-size:17px;line-height:1.62;margin:16px 0 34px;max-width:820px} + .storm-home .agentkit{display:grid;grid-template-columns:1.15fr 1fr;gap:28px;align-items:center;margin-top:20px; + border:1px solid rgba(129,140,248,.22);border-radius:14px;padding:26px 28px;background:linear-gradient(135deg,rgba(129,140,248,.07),var(--panel-2) 60%)} + .storm-home .agentkit h3{margin:0 0 10px;font-size:19px;font-weight:650;letter-spacing:-.01em} + .storm-home .agentkit p{margin:0;color:var(--muted);font-size:14.5px;line-height:1.65} + .storm-home .agentkit p code{font-family:var(--mono);font-size:13px;color:var(--text)} + .storm-home .agentkit .akcopy a{display:inline-block;margin-top:14px;margin-right:18px;color:var(--accent);font-size:14px;font-weight:600} + /* The MCP server's guarantees as checkable facts, each one a chip. */ + .storm-home .aksafe{display:flex;flex-wrap:wrap;gap:8px;margin-top:16px} + .storm-home .aksafe span{display:inline-flex;align-items:center;gap:6px;font-family:var(--mono);font-size:11.5px;color:var(--text); + border:1px solid rgba(94,234,212,.3);background:rgba(94,234,212,.06);border-radius:999px;padding:5px 11px} + .storm-home .aksafe span::before{content:"✓";color:var(--green)} + .storm-home .agentkit .akcopy a:hover{text-decoration:underline} + .storm-home .akcmds{display:flex;flex-direction:column;gap:16px} + .storm-home .akcmd .clichip{width:100%} + .storm-home .aknote{display:block;margin-top:7px;color:var(--muted);font-size:13px;line-height:1.5} + .storm-home .aknote code,.storm-home .akreq code{font-family:var(--mono);font-size:12px;color:var(--text);background:none;border:0;padding:0;white-space:nowrap} + .storm-home .agentkit .akreq{margin:0;color:var(--faint);font-size:12.5px} + @media(max-width:920px){ + .storm-home .agentkit{grid-template-columns:1fr} + } + @media(max-width:600px){ + .storm-home .agentkit{padding:22px} + } + /* Production evaluation: the closing section answers "can I adopt this?" rather than restating the pitch. Facts first (release, license, runtime), then scope, then the places to verify each claim. */ @@ -317,16 +359,13 @@ const CSS = ` .storm-home footer{border-top:1px solid var(--border-soft);padding:36px 0;color:var(--faint);font-size:13.5px} .storm-home .foot{display:flex;justify-content:space-between;align-items:center;flex-wrap:wrap;gap:14px} .storm-home .foot .links{display:flex;gap:22px;font-family:var(--mono);flex-wrap:wrap}.storm-home .foot a{color:var(--muted)}.storm-home .foot a:hover{color:var(--text)} + @media(max-width:1100px){.storm-home .tech-tag{display:none}} @media(max-width:920px){ - .storm-home .tech-tag{display:none} .storm-home .facts,.storm-home .scope{grid-template-columns:1fr} } - @media(max-width:760px){ - .storm-home .three{grid-template-columns:1fr} - .storm-home .bgrid{grid-template-columns:repeat(2,1fr)} - /* Wrapped code is taller than the desktop floor and every scene wraps to a - different height, so the reserved height is released here. */ - .storm-home .codearea{min-height:0} + /* Narrow screens: the row of links gives way to the hamburger menu where it + stops fitting beside the brand, which is well above the phone breakpoint. */ + @media(max-width:1000px){ /* The menu is CSS-only (a checkbox drives the drop-down), so the checkbox is the control a keyboard reaches: clipped to 1px rather than display:none, which would take it out of the tab order and leave the mobile menu @@ -341,6 +380,13 @@ const CSS = ` .storm-home .nav-toggle-cb:checked ~ .nav-links{display:flex} .storm-home .nav-links a{padding:13px 24px;font-size:15px} .storm-home .nav-links a.btn{margin:10px 24px 6px;justify-content:center} + } + @media(max-width:760px){ + .storm-home .three{grid-template-columns:1fr} + .storm-home .bgrid{grid-template-columns:repeat(2,1fr)} + /* Wrapped code is taller than the desktop floor and every scene wraps to a + different height, so the reserved height is released here. */ + .storm-home .codearea{min-height:0} /* On phones the editor wraps long lines instead of scrolling them. iOS Safari desyncs the painted content of a composited overflow-x scroller whose DOM is mutated per frame by the typewriter (stale tiles render at @@ -361,6 +407,18 @@ const CSS = ` `; const esc = (s) => s.replace(/&/g, '&').replace(//g, '>'); +// For attribute values: esc() covers text content, an attribute also needs its +// quotes escaped so a value can never close the attribute it sits in. +const escAttr = (s) => esc(s).replace(/"/g, '"').replace(/'/g, '''); + +// A "$ " chip that copies the command on click. The whole chip is the +// button, so the target is large on phones and a keyboard reaches it directly. +const cliChip = (command) => + ``; const K = (x) => ({x, c: 'code-k'}), T = (x) => ({x, c: 'code-t'}), @@ -372,7 +430,28 @@ const K = (x) => ({x, c: 'code-k'}), P = (x) => ({x, c: 'code-pl'}); const SCENES = [ - { name:'1 · entities', file:'Entities.kt', + // The first scene is the Storm CLI, so the one animation above the fold + // shows how to start. The prompts, files and closing line follow what + // `storm init` prints for Claude Code, Kotlin and a PostgreSQL connection + // with data access left at its default (off), in a project that already has + // a CLAUDE.md: the CLI adds its marked block and leaves the rest as it was. + // `typed` marks the end of the command: it types, the output then appears + // line by line, as a terminal prints it. + { name:'1 · agent setup', file:'Terminal', copy:CLI_INIT, typed:CLI_INIT.length + 2, + caption:"up and running with your agent in one minute", + code:[ + A("$ "),P(CLI_INIT+"\n"), + S("✔ "),P("Which AI tools do you use? "),A("Claude Code\n"), + S("✔ "),P("Which language(s) does this project use? "),A("Kotlin\n"), + S("✔ "),P("Connect to a local database? "),A("Yes"),C(" · PostgreSQL\n"), + S("✔ "),P("Allow AI tools to query data? (read-only SELECT) "),A("No\n\n"), + A(" Created:\n"), + P(" + .claude/skills/storm-entity-kotlin/SKILL.md"),C(" + 11 more skills\n"), + P(" + .mcp.json"),C(" local, read-only, schema only\n"), + A(" Updated:\n"), + P(" ~ CLAUDE.md"),C(" Storm block added, your own content kept\n\n"), + S(" You're all set!") ] }, + { name:'2 · entities', file:'Entities.kt', caption:"the most concise way to define your entities", code:[ K("data class "),T("City"),P("(\n"), P(" "),A("@PK"),P(" "),K("val "),P("id: "),T("Int"),P(" = "),N("0"),P(",\n"), @@ -387,7 +466,7 @@ const SCENES = [ P(" "),A("@FK"),P(" "),K("val "),P("city: "),T("City"),P(" "),C("// foreign entities are available in queries and results\n"), P(") : "),T("Entity"),P("<"),T("Int"),P(">") ] }, - { name:'2 · query', file:'UserService.kt', + { name:'3 · query', file:'UserService.kt', caption:"one-line queries to get all the data you need · no N+1", code:[ C("// A user's city is loaded in the same query.\n"), K("val "),P("user = userRepository."),F("getById"),P("("),N("1"),P(")\n"), @@ -395,7 +474,7 @@ const SCENES = [ C("// Filter across the graph, fully type-safe using the static metamodel.\n"), K("val "),P("users = userRepository."),F("findAll"),P("(User_.city.name "),K("eq "),S('"Sunnyvale"'),P(")") ] }, - { name:'3 · repository', file:'UserRepository.kt', + { name:'4 · repository', file:'UserRepository.kt', caption:"your own type-safe queries · CRUD inherited", code:[ C("// Custom return types are just records. Define them in-place.\n"), K("data class "),T("CityCount"),P("("),K("val "),P("city: "),T("City"),P(", "),K("val "),P("count: "),T("Long"),P(")\n\n"), @@ -409,7 +488,7 @@ const SCENES = [ P(" .resultList\n"), P("}") ] }, - { name:'4 · transactions', file:'Transactions.kt', + { name:'5 · transactions', file:'Transactions.kt', caption:"full control with programmatic tx · Spring's declarative tx also supported", code:[ C("// Writes are explicit. One transaction.\n"), F("transaction"),P(" {\n"), @@ -425,7 +504,7 @@ const SCENES = [ P(" "),F("onCommit"),P(" { events."),F("publish"),P("("),T("UserCreated"),P("(user)) }"),P(" "),C("// runs only after successful commit\n"), P("}") ] }, - { name:'5 · sql', file:'UserService.kt', + { name:'6 · sql', file:'UserService.kt', caption:"full SQL when you want it, never locked in", code:[ C("// Full control of SQL, with typed columns and tables; rows map to any data class.\n"), K("data class "),T("RankedCity"),P("("),K("val "),P("name: "),T("String"),P(", "),K("val "),P("rank: "),T("Long"),P(")\n\n"), @@ -435,7 +514,7 @@ const SCENES = [ P(" "),K("WHERE "),T("${City_.country}"),P(" = "),T("$country"),P(" "),C("-- typed columns · bound value\n"), S('"""'),P(" }."),F("resultList"),P("<"),T("RankedCity"),P(">()") ] }, - { name:'6 · principles', file:'Core Principles', + { name:'7 · principles', file:'Core Principles', caption:"the core principles", grid:[ { t:"Enjoyable", d:"Write code that's a pleasure to read and maintain." }, @@ -455,6 +534,7 @@ const SCENES = [ // Generated SQL per scene (index-aligned with SCENES). Shown via the "Show SQL" toggle. const SQL = [ + null, // cli: no query, so the Show SQL button is hidden for this scene null, // entities: no query, so the Show SQL button is hidden for this scene '-- getById(1): joins the city graph, no N+1\n'+ @@ -576,6 +656,7 @@ function buildBody(version) {
+ AI Tutorials Examples Comparison @@ -599,13 +680,12 @@ function buildBody(version) { Radically Simple. Fast. ST/ORM for Kotlin. -

A modern alternative to Hibernate.

-

Immutable data-class entities. Concise queries checked at compile time. No proxies, persistence context, or accidental N+1 queries.

+

A modern alternative to Hibernate, built for agentic coding and performance.

+

Your data class is the type-safe model. Your agent gets the exact details it needs to act on, and your queries generally run faster than with any other ORM.

Try it in 5 minutes → Compare with your ORM
-

Evaluating Storm for your team or project? Talk to the engineers behind it: ${CONTACT_EMAIL}

@@ -613,6 +693,7 @@ function buildBody(version) { Entities.kt +
@@ -640,6 +721,41 @@ function buildBody(version) {
+
+
Agentic coding
+

Good for your agent. Good for you.

+

A coding agent is only as right as what it can read. In Storm every detail lives in the model: your data classes define the tables, keys and relations, and the queries follow from them. Underneath is a thin layer over JDBC, so nothing sits between the model and the database. The agent reads the model and has everything it needs, and the code it reads is exactly what runs.

+
+
+

What you see is what runs

+

No proxies, no lazy loading, no persistence context, no flush. An entity is a value, and every database call is a visible line of code. Nothing happens that the agent cannot see.

+
+
+

All in one place

+

One data class is the table, its keys and its relations. No second table definition beside it, and no session state deciding at runtime what a field holds. The agent reads one file and has the full picture.

+
+
+

Queries come from the domain

+

Your entities already give you one-line, type-safe queries across relations, with the whole graph loaded in one statement. Less for the agent to write, and fewer joins and mappings to get wrong.

+
+
+
+
+

Set up your agent in one minute

+

The Storm CLI installs rules and skills for Claude Code, Cursor, GitHub Copilot, Windsurf and Codex, plus an optional MCP server that runs on your machine and is read-only. The agent sees your schema, never your credentials, and sees data only if you allow it. The agent then checks its own work: validateSchema() proves the entities match the database, and SqlCapture shows the SQL a query really runs.

+
Runs locallyRead-onlySchema only by defaultCredentials never reach the AI
+ Agentic coding guide → + How access is secured → +
+
+
${cliChip(CLI_INSTALL)}Install the Storm CLI once.
+
${cliChip('storm init')}In your project: rules, skills and schema access for your agent. Run storm update later to refresh them.
+
${cliChip('storm demo')}In an empty directory: your agent builds a demo app on Storm.
+

Needs Node.js 18 or later.

+
+
+
+
@@ -726,15 +842,16 @@ function buildBody(version) { `; } const TITLE = 'ST/ORM · The type-safe Kotlin ORM'; const DESC = - 'Storm is a type-safe, SQL-first Kotlin ORM. Immutable data-class entities, ' + - 'one-line queries checked at compile time, no proxies, no N+1. Try it in 5 minutes.'; + 'Storm is a type-safe, SQL-first Kotlin ORM built for agentic coding and performance. Immutable ' + + 'data-class entities, one-line queries checked at compile time, no proxies, no N+1. ' + + 'Try it in 5 minutes.'; export default function Home() { const {siteConfig} = useDocusaurusContext(); @@ -763,6 +880,41 @@ export default function Home() { return [chip, onChipClick]; }); + // ---- CLI command chips: copy on click, check mark for a moment ---- + const cliTimers = new Map(); + const cliHandlers = [...document.querySelectorAll('.storm-home .clichip, .storm-home .clicopy')].map((chip) => { + const label = chip.querySelector('.cptext'); + const onCopy = () => { + const text = chip.dataset.copy; + // The Clipboard API needs a secure context; fall back to a throwaway + // textarea so copy also works on plain-http previews (e.g. LAN). + if (navigator.clipboard && window.isSecureContext) { + navigator.clipboard.writeText(text); + } else { + const ta = document.createElement('textarea'); + ta.value = text; + document.body.appendChild(ta); + ta.select(); + document.execCommand('copy'); + ta.remove(); + } + // Counted as a Plausible custom event, so the dashboard shows how many + // visitors take the CLI route and which command they pick. + if (typeof window.plausible === 'function') { + window.plausible('Copy CLI command', {props: {command: text}}); + } + chip.classList.add('on'); + if (label) label.textContent = 'Copied'; + clearTimeout(cliTimers.get(chip)); + cliTimers.set(chip, setTimeout(() => { + chip.classList.remove('on'); + if (label) label.textContent = 'Copy command'; + }, 1600)); + }; + chip.addEventListener('click', onCopy); + return [chip, onCopy]; + }); + const codeEl=document.getElementById('code'), gutEl=document.getElementById('gutter'), fnameEl=document.getElementById('fname'), scenesEl=document.getElementById('scenes'), statusEl=document.getElementById('status'), statusTextEl=document.getElementById('statustext'), @@ -770,6 +922,7 @@ export default function Home() { if(!codeEl) return; // ---- "Show SQL": reveals the generated SQL for the current scene ---- + const copyBtn=document.getElementById('copybtn'); const editorEl=document.querySelector('.storm-home .editor'), sqlBtn=document.getElementById('sqlbtn'), sqlBtnText=document.getElementById('sqlbtntext'), sqlPanel=document.getElementById('sqlpanel'); let showSql=false, curIdx=0; @@ -829,6 +982,10 @@ export default function Home() { curIdx=idx; const hasSql=!!SQL[idx]; sqlBtn.style.display=hasSql?'':'none'; + if(copyBtn){ + copyBtn.style.display=sc.copy?'':'none'; + if(sc.copy){ copyBtn.dataset.copy=sc.copy; copyBtn.setAttribute('aria-label','Copy command: '+sc.copy); } + } sqlBtn.setAttribute('aria-expanded',hasSql&&showSql?'true':'false'); sqlBtnText.textContent=showSql?'Hide SQL':'Show SQL'; editorEl.classList.toggle('show-sql',hasSql&&showSql); @@ -887,10 +1044,22 @@ export default function Home() { // roughly four seconds. It plays once per visit, so the visitor should // not be waiting on it to find out what the page is showing them. for(let n=0;n<=text.length;n++){ + // A terminal scene types its command, then prints the output a + // whole line at a time. + if(sc.typed!=null&&n>sc.typed){ + const nl=text.indexOf('\n',n); + n=nl<0?text.length:nl+1; + } codeEl.innerHTML=render(sc.code,n,true); + if(myGen!==gen) return; const ch=text[n-1]; let d=6+Math.random()*10; - if(ch==='\n')d=55; else if(ch===' ')d=4; else if('(){}.,'.includes(ch))d=22; + // Output pacing: a beat after the command while it "runs", then a + // line every third of a second, so the run reads as a live terminal + // rather than a flash of text. + if(sc.typed!=null&&n===sc.typed)d=800; + else if(sc.typed!=null&&n>sc.typed)d=320; + else if(ch==='\n')d=55; else if(ch===' ')d=4; else if('(){}.,'.includes(ch))d=22; await wait(d); } } @@ -935,6 +1104,8 @@ export default function Home() { gen++; clearTimeout(timer); vsChipHandlers.forEach(([chip, handler]) => chip.removeEventListener('click', handler)); + cliHandlers.forEach(([chip, handler]) => chip.removeEventListener('click', handler)); + cliTimers.forEach((t) => clearTimeout(t)); tabHandlers.forEach(([tab, onClick, onKey]) => { tab.removeEventListener('click', onClick); tab.removeEventListener('keydown', onKey); @@ -952,7 +1123,7 @@ export default function Home() { {/* Open Graph / Twitter: default og:title is just the site name ("Storm Framework") and og:description is absent, so set the @@ -985,6 +1156,7 @@ export default function Home() { 'One-line queries with an optional full SQL template engine', 'Works with PostgreSQL, MySQL, MariaDB, Oracle, SQL Server, SQLite and H2', 'Integrates with Spring Boot 3.x/4.x and Ktor', + 'Built for agentic coding: one CLI command installs rules, skills and a schema-aware MCP server for Claude Code, Cursor, GitHub Copilot, Windsurf and Codex', ], url: 'https://orm.st', sameAs: [ diff --git a/website/src/pages/quickstart.js b/website/src/pages/quickstart.js index 1a868657f..6e23889e9 100644 --- a/website/src/pages/quickstart.js +++ b/website/src/pages/quickstart.js @@ -6,6 +6,7 @@ import { navHtml, FOOT_HTML, editor, + clonebar, wireSqlToggles, KOTLIN_VARIANTS, DATABASE_VARIANTS, @@ -15,9 +16,10 @@ import { // The 5-minute quickstart. Built in the landing/tutorial style (see // tutorialTheme.js) rather than as a docs page so it deploys live immediately -// and is the target of every "Get started" button on the site. Kotlin-first; -// leads with the manual build, with the Storm CLI one-liner (AI-assisted -// setup) as a secondary suggestion below it. The install snippet renders the +// and is the target of every "Get started" button on the site. Kotlin-first. +// A short box up top hands visitors who work with a coding agent the Storm CLI +// (`init` for a project, `demo` for an empty directory); the walkthrough below +// it is the manual build, which is also exactly what the agent will write. The install snippet renders the // resolved release version, read from siteConfig.customFields.stormVersion // (docusaurus.config.ts). @@ -27,10 +29,15 @@ const DESC = 'query across the relation in one type-safe line. The whole path from empty ' + 'project to first query, with the SQL it generates.'; -function buildBody(version) { - const cliCommand = 'npx @storm-orm/cli init'; - const cli = C("# from the root of your project's workspace\n") + P(cliCommand); +// Spacing inside the agent box: the note style is built for a single line of +// copy, and this one stacks a paragraph, two command bars and a closing line. +const AGENT_NOTE_CSS = ` + .storm-tut .agentnote p{margin:0} + .storm-tut .agentnote .clonebar{margin:12px 0 0} + .storm-tut .agentnote .clonebar + p{margin-top:14px} +`; +function buildBody(version) { // One install snippet per supported Kotlin line (KOTLIN_VARIANTS in the // shared theme), switchable in the editor title bar. The Storm plugin applies // its bundled KSP itself, so only the Kotlin-paired lines declare KSP. @@ -125,6 +132,13 @@ ${navHtml('')}

Install Storm, define two linked entities as plain data classes, and query across the relation in one type-safe line. No persistence context, no proxies, no XML. Here is the whole path.

Kotlin~5 minJDK 21+
+
+

Working with a coding agent? Run one command from the root of your project and your agent knows Storm: rules and skills for Claude Code, Cursor, GitHub Copilot, Windsurf and Codex, plus an optional MCP server that runs on your machine, read-only: your agent sees the schema, never your credentials, and sees data only if you allow it. Starting from an empty directory instead? The demo command has your agent build a small app on Storm.

+ ${clonebar('npx @storm-orm/cli init')} + ${clonebar('npx @storm-orm/cli demo')} +

The steps below are the same path by hand, and worth a read either way: Storm code is what runs, so this is exactly what your agent will write. More in the agentic coding guide.

+
+

1Set up

Apply the Storm Gradle plugin. It imports the BOM and wires the core dependencies, the metamodel processor, and the Kotlin compiler plugin, so all that is left for a runnable project is an in-memory H2 database.

${editor({ @@ -135,8 +149,6 @@ ${navHtml('')} })}

The plugin generates the type-safe metamodel (Movie_) through KSP and makes SQL templates injection-safe by default through the compiler plugin, with no extra dependencies to declare. On a real database, swap storm-h2 for your dialect and add its JDBC driver. See the installation guide for all options.

Starting a project rather than reading along? A starter template is this build file with an application already around it: two entities and their migration, a repository query, a service, two endpoints and their tests, on Ktor or Spring Boot, in Kotlin or Java. Press Use this template on GitHub and it runs on H2 before you change a line.

-

Working with an AI coding assistant? One command, run from the root of your project's workspace, installs Storm-aware rules and skills for it (Claude, Cursor, Copilot, Windsurf, Codex) and sets up a schema-aware MCP server, so the entities and queries it generates match your real schema.

- ${editor({file: 'terminal', tag: 'shell', code: cli, copy: cliCommand})}

2Define two linked entities

Entities are plain immutable data classes that implement Entity<ID>. Field names map to columns automatically (camelCase to snake_case), and a relation is just a @FK field typed as the entity it points to. There is no base class to extend and no generated draft type to route through: the classes you write are the objects you get back.

@@ -213,7 +225,7 @@ export default function Quickstart() { rel="stylesheet" /> -