Skip to content

Commit 607a2a9

Browse files
zantvoortzantvoort
authored
Add AI setup. (#93) (#101)
1 parent f032dd7 commit 607a2a9

25 files changed

+21410
-0
lines changed

‎.github/workflows/docs.yml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -64,6 +64,9 @@ jobs:
6464
fi
6565
done
6666
67+
- name: Generate llms-full.txt
68+
run: bash website/scripts/generate-llms-full.sh
69+
6770
- name: Build Docusaurus
6871
run: npm run build
6972
working-directory: website

‎.github/workflows/release.yml‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -56,6 +56,35 @@ jobs:
5656
env:
5757
GPG_PASSPHRASE: ${{ secrets.GPG_PASSPHRASE }}
5858

59+
publish-npm:
60+
runs-on: ubuntu-latest
61+
62+
steps:
63+
- name: Checkout repository
64+
uses: actions/checkout@v4
65+
66+
- name: Set up Node.js
67+
uses: actions/setup-node@v4
68+
with:
69+
node-version: '22'
70+
registry-url: 'https://registry.npmjs.org'
71+
72+
- name: Extract version from tag
73+
id: version
74+
run: echo "VERSION=${GITHUB_REF_NAME#v}" >> $GITHUB_OUTPUT
75+
76+
- name: Set package version from tag
77+
run: |
78+
npm version ${{ steps.version.outputs.VERSION }} --no-git-tag-version
79+
sed -i "s/const VERSION = '.*'/const VERSION = '${{ steps.version.outputs.VERSION }}'/" storm.mjs
80+
working-directory: storm-cli
81+
82+
- name: Publish to npm
83+
run: npm publish --access public
84+
working-directory: storm-cli
85+
env:
86+
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
87+
5988
version-docs:
6089
runs-on: ubuntu-latest
6190
needs: publish

‎docs/ai-setup.md‎

Lines changed: 138 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
1+
# AI-Assisted Development
2+
3+
import Tabs from '@theme/Tabs';
4+
import TabItem from '@theme/TabItem';
5+
6+
Storm is an AI-first ORM. It works perfectly standalone, but its design and tooling make it uniquely suited for AI-assisted development. Immutable entities produce stable, predictable code. Skills guide AI tools through entity creation, queries, repositories, and migrations. A locally running MCP server exposes only schema metadata (table definitions, column types, constraints) while shielding your database credentials and data from the LLM.
7+
8+
Traditional ORMs carry hidden complexity (proxies, lazy loading, persistence contexts, cascading rules) that AI tools struggle to reason about. Storm eliminates all of that: entities are plain data classes, queries are explicit SQL, and what you see in the source code is exactly what happens at runtime.
9+
10+
---
11+
12+
## Quick Setup
13+
14+
Install the Storm CLI and run it in your project:
15+
16+
```bash
17+
npm install -g @storm-orm/cli
18+
storm init
19+
```
20+
21+
Or without installing globally:
22+
23+
```bash
24+
npx @storm-orm/cli init
25+
```
26+
27+
The interactive setup walks you through three steps:
28+
29+
### 1. Select AI tools
30+
31+
Choose which AI coding tools to configure. Storm supports:
32+
33+
| Tool | Rules | Skills | MCP |
34+
|------|-------|--------|-----|
35+
| Claude Code | CLAUDE.md (optional) | .claude/skills/ | .mcp.json |
36+
| Cursor | - | .cursor/rules/ | .cursor/mcp.json |
37+
| GitHub Copilot | .github/copilot-instructions.md | .github/instructions/ | (tool-dependent) |
38+
| Windsurf | - | .windsurf/rules/ | (manual config) |
39+
| Codex | AGENTS.md | - | (experimental) |
40+
41+
The MCP server configuration file location depends on the AI tool.
42+
43+
### 2. Rules and skills
44+
45+
For each selected tool, Storm installs:
46+
47+
- **Rules**: A project-level configuration file with Storm's key patterns and conventions.
48+
- **Skills**: Per-topic guides fetched from orm.st that help the AI tool with specific tasks. Skills can be updated automatically on each run without requiring a CLI update.
49+
50+
Available skills:
51+
52+
| Skill | Purpose |
53+
|-------|---------|
54+
| storm-docs | Load full Storm documentation |
55+
| storm-entity-kotlin | Create Kotlin entities |
56+
| storm-entity-java | Create Java entities |
57+
| storm-repository-kotlin | Write Kotlin repositories |
58+
| storm-repository-java | Write Java repositories |
59+
| storm-query-kotlin | Kotlin QueryBuilder queries |
60+
| storm-query-java | Java QueryBuilder queries |
61+
| storm-sql-kotlin | Kotlin SQL Templates |
62+
| storm-sql-java | Java SQL Templates |
63+
| storm-migration | Write Flyway/Liquibase migration SQL |
64+
65+
### 3. Database connection (optional)
66+
67+
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.
68+
69+
The MCP server:
70+
- Runs locally on your machine
71+
- Exposes only schema metadata, never actual data
72+
- Stores credentials in `~/.storm/` (outside your project, outside the LLM's reach)
73+
- Supports PostgreSQL, MySQL, MariaDB, Oracle, SQL Server, SQLite, and H2
74+
75+
With the database connected, three additional skills become available:
76+
77+
| Skill | Purpose |
78+
|-------|---------|
79+
| storm-schema | Inspect your live database schema |
80+
| storm-validate | Compare entities against the live schema |
81+
| storm-entity-from-schema | Generate, update, or refactor entities from database tables |
82+
83+
To reconfigure the database connection later, run `storm mcp`.
84+
85+
---
86+
87+
## Manual Setup
88+
89+
If you prefer to configure your AI tool manually, Storm publishes two machine-readable documentation files following the [llms.txt standard](https://llmstxt.org/):
90+
91+
| File | URL | Best for |
92+
|------|-----|----------|
93+
| `llms.txt` | [orm.st/llms.txt](https://orm.st/llms.txt) | Quick reference with essential patterns and gotchas |
94+
| `llms-full.txt` | [orm.st/llms-full.txt](https://orm.st/llms-full.txt) | Complete documentation for tools with large context windows |
95+
96+
<Tabs>
97+
<TabItem value="claude-code" label="Claude Code" default>
98+
99+
Use `@url` to fetch Storm context in a conversation:
100+
101+
```
102+
@url https://orm.st/llms-full.txt
103+
```
104+
105+
</TabItem>
106+
<TabItem value="cursor" label="Cursor">
107+
108+
Add Storm documentation as a doc source in Cursor settings:
109+
110+
1. Open **Settings > Features > Docs**
111+
2. Click **Add new doc**
112+
3. Enter `https://orm.st/llms-full.txt`
113+
114+
</TabItem>
115+
<TabItem value="generic" label="Other Tools">
116+
117+
Most AI coding tools support adding context through URLs or pasted text. Point your tool at `https://orm.st/llms-full.txt` for complete documentation.
118+
119+
</TabItem>
120+
</Tabs>
121+
122+
---
123+
124+
## Why Storm Works Well With AI
125+
126+
Storm's design principles align naturally with how AI coding tools operate:
127+
128+
| Design Choice | Why it helps AI |
129+
|---------------|-----------------|
130+
| **Immutable entities** | No hidden state transitions for the AI to track or miss |
131+
| **Explicit SQL** | The generated SQL is visible and predictable; the AI can reason about queries directly |
132+
| **No proxies** | The entity class *is* the entity; no invisible bytecode transformations to account for |
133+
| **No persistence context** | No session scope, flush ordering, or detachment rules that require deep framework knowledge |
134+
| **Convention over configuration** | Fewer annotations and config files for the AI to keep consistent |
135+
| **Compile-time metamodel** | Type errors caught at build time, not at runtime; the AI gets immediate feedback |
136+
| **Secure schema access** | The MCP server gives AI tools structural database knowledge without exposing credentials or data |
137+
138+
When you ask an AI tool to write Storm code, it produces the same straightforward data classes and explicit queries that a human developer would write. There is no framework magic to get wrong.

‎docs/index.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,10 @@ import TabItem from '@theme/TabItem';
88

99
# ST/ORM
1010

11+
:::info Built for the AI Era
12+
Storm's immutable design, skills, and secure MCP schema access make it the ORM that AI coding tools get right consistently. Install with `npm install -g @storm-orm/cli`, then run `storm init` in your project. See [AI-Assisted Development](ai-setup.md).
13+
:::
14+
1115
**Storm** is a modern, high-performance ORM for Kotlin 2.0+ and Java 21+, built around a powerful SQL template engine. It focuses on simplicity, type safety, and predictable performance through immutable models and compile-time metadata.
1216

1317
**Key benefits:**

‎storm-cli/package.json‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
{
2+
"name": "@storm-orm/cli",
3+
"version": "1.11.0",
4+
"description": "Storm ORM - AI assistant configuration tool",
5+
"type": "module",
6+
"bin": {
7+
"storm": "./storm.mjs"
8+
},
9+
"files": [
10+
"storm.mjs"
11+
],
12+
"keywords": [
13+
"storm",
14+
"orm",
15+
"ai",
16+
"llm",
17+
"claude",
18+
"cursor",
19+
"copilot",
20+
"windsurf"
21+
],
22+
"license": "Apache-2.0",
23+
"repository": {
24+
"type": "git",
25+
"url": "https://github.com/storm-orm/storm-framework.git",
26+
"directory": "storm-cli"
27+
},
28+
"homepage": "https://orm.st",
29+
"engines": {
30+
"node": ">=18"
31+
}
32+
}

0 commit comments

Comments
 (0)