@contentrain/query 5.1.3 → 5.1.5

package/README.md

@@ -1,6 +1,7 @@
 # `@contentrain/query`
 
 [![npm version](https://img.shields.io/npm/v/%40contentrain%2Fquery?label=%40contentrain%2Fquery)](https://www.npmjs.com/package/@contentrain/query)
+[![Agent Skills](https://img.shields.io/badge/Agent_Skill-contentrain--query-8B5CF6)](https://agentskills.io)
 [![GitHub source](https://img.shields.io/badge/source-Contentrain%2Fai-181717?logo=github)](https://github.com/Contentrain/ai/tree/main/packages/sdk/js)
 [![Docs](https://img.shields.io/badge/docs-ai.contentrain.io-0f172a)](https://ai.contentrain.io/packages/sdk)
 
@@ -340,24 +341,31 @@ const client = await clientModule.init()
 const hero = client.singleton('hero').get()
 ```
 
-## 🛠 CLI
+## 🛠 Generation Commands
 
-Generate once:
+**Via the `contentrain` CLI (recommended for most users):**
 
 ```bash
-npx contentrain-query generate
+contentrain generate                # Generate once
+contentrain generate --watch        # Regenerate on model/content changes
+contentrain generate --json         # Machine-readable JSON for CI
 ```
 
-Generate in watch mode:
+**Via `contentrain-query` (programmatic / build tool flows):**
 
 ```bash
+npx contentrain-query generate
 npx contentrain-query generate --watch
+npx contentrain-query generate --root /path/to/project
 ```
 
-Use a different project root:
+Or from TypeScript:
 
-```bash
-npx contentrain-query generate --root /path/to/project
+```ts
+import { generate } from '@contentrain/query/generate'
+
+const result = await generate({ projectRoot: process.cwd() })
+console.log(result.generatedFiles.length)
 ```
 
 ## 📤 Package Exports
@@ -395,6 +403,16 @@ pnpm --filter @contentrain/query typecheck
 pnpm exec oxlint packages/sdk/js/src packages/sdk/js/tests
 ```
 
+## Agent Skill (embedded)
+
+This package ships an embedded [Agent Skill](https://agentskills.io) at `skills/contentrain-query/SKILL.md`. AI coding agents can discover and load it for type-safe SDK usage guidance, including:
+
+- QueryBuilder, SingletonAccessor, DictionaryAccessor, DocumentQuery APIs
+- Local mode vs CDN mode differences
+- Framework-specific bundler configuration (Vite, Next.js, Nuxt, SvelteKit, Metro)
+
+The skill is available via the `@contentrain/query/skills/*` subpath export.
+
 ## 🔗 Related Packages
 
 - `contentrain` — CLI that runs project initialization, validation, serve, and generation flows

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contentrain/query",
-  "version": "5.1.3",
+  "version": "5.1.5",
   "license": "MIT",
   "description": "Optional type-safe query SDK for Contentrain — generated TypeScript client for platform-independent JSON content",
   "type": "module",
@@ -22,6 +22,7 @@
     "i18n",
     "generated-client",
     "platform-independent",
+    "agent-skills",
     "json",
     "vue",
     "react",
@@ -52,17 +53,19 @@
       "types": "./dist/cdn/index.d.ts",
       "import": "./dist/cdn/index.mjs",
       "require": "./dist/cdn/index.cjs"
-    }
+    },
+    "./skills/*": "./skills/*"
   },
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.ts",
   "sideEffects": false,
   "files": [
-    "dist"
+    "dist",
+    "skills"
   ],
   "dependencies": {
-    "@contentrain/types": "0.4.1"
+    "@contentrain/types": "0.5.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

package/skills/contentrain-query/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: contentrain-query
+description: "Use the @contentrain/query SDK to query Contentrain content with type safety. Use when importing from #contentrain, using QueryBuilder, SingletonAccessor, DictionaryAccessor, DocumentQuery, or CDN client."
+metadata:
+  author: Contentrain
+  version: "1.0.0"
+---
+
+# Contentrain Query SDK
+
+`@contentrain/query` is a Prisma-pattern generated client that provides type-safe access to Contentrain content. Generated output lives in `.contentrain/client/` — never edit it manually.
+
+## Quick Start
+
+```bash
+npx contentrain generate     # Generate client from models
+```
+
+```typescript
+import { query, singleton, dictionary, document } from '#contentrain'
+
+// Collection
+const posts = query('blog-post').where('category', 'eq', 'engineering').sort('published_at', 'desc').limit(10).all()
+
+// Singleton
+const hero = singleton('hero').get()
+
+// Dictionary
+const t = dictionary('ui-texts').get()
+const loginLabel = t['auth.login.button']
+
+// Document
+const doc = document('blog-post').bySlug('getting-started')
+```
+
+## Runtime API
+
+### QueryBuilder (collections)
+
+| Method | Description |
+|--------|-------------|
+| `.all()` | Get all entries |
+| `.first()` | Get first entry |
+| `.count()` | Return count of matching entries |
+| `.where(field, value)` | Equality filter (shorthand for `eq`) |
+| `.where(field, op, value)` | Operator filter: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `contains` |
+| `.sort(field, direction?)` | Sort (`asc`/`desc`, default `asc`) |
+| `.limit(n)` | Limit results |
+| `.offset(n)` | Skip results |
+| `.include(relation)` | Resolve relation (1 level deep) |
+
+### SingletonAccessor
+
+| Method | Description |
+|--------|-------------|
+| `.get()` | Get the singleton data |
+| `.include(relation)` | Resolve relation fields |
+
+### DictionaryAccessor
+
+| Method | Description |
+|--------|-------------|
+| `.get()` | Get all key-value pairs |
+| `.get(key)` | Get single value by key |
+| `.get(key, params)` | Get with interpolation: `{placeholder}` → value |
+
+### DocumentQuery
+
+| Method | Description |
+|--------|-------------|
+| `.all()` | Get all documents |
+| `.bySlug(slug)` | Get document by slug |
+| `.first()` | Get first document |
+| `.count()` | Return count of matching documents |
+| `.where(field, value)` | Equality filter (shorthand) |
+| `.where(field, op, value)` | Operator filter (same ops as QueryBuilder) |
+| `.include(relation)` | Resolve relation fields |
+
+## CDN Mode (Remote Data)
+
+For server-side or client-side apps that fetch content from Contentrain Studio CDN:
+
+```typescript
+import { createContentrain } from '@contentrain/query/cdn'
+
+const client = createContentrain({
+  projectId: '350696e8-...',
+  apiKey: 'crn_live_xxx',
+})
+
+// All CDN queries are async (return Promise)
+const posts = await client.collection('faq').locale('en').all()
+const hero = await client.singleton('hero').locale('en').get()
+const t = await client.dictionary('ui').locale('en').get()
+const doc = await client.document('docs').locale('en').bySlug('intro')
+```
+
+## Key Rules
+
+- **Local mode** queries are **synchronous** — no `await` needed
+- **CDN mode** queries are **async** — always `await`
+- Relation resolution is **1 level deep** — no recursive resolution
+- Locale fallback chain: explicit → config default → first available
+- Generated files in `.contentrain/client/` are **immutable** — always regenerate, never edit
+- Run `contentrain generate` after any model change
+
+## Framework Integration
+
+| Framework | Import | Notes |
+|-----------|--------|-------|
+| Nuxt 3 | `import { query } from '#contentrain'` | Server-only (server routes, plugins) |
+| Next.js | `import { query } from '#contentrain'` | Works in RSC and API routes |
+| Astro | `import { query } from '#contentrain'` | Works in `.astro` frontmatter |
+| SvelteKit | `import { query } from '#contentrain'` | Works in `+page.server.ts` |
+| Vue + Vite | `import { query } from '#contentrain'` | Requires Vite alias config |
+| React + Vite | `import { query } from '#contentrain'` | Requires Vite alias config |
+| Node.js | `import { query } from '#contentrain'` | ESM with subpath imports |
+
+## References
+
+| Reference | Description |
+|-----------|-------------|
+| [Bundler Configuration](references/bundler-config.md) | Vite, Next.js, Nuxt, SvelteKit, Metro alias setup |
+
+## Related Skills
+
+- **contentrain-generate** — Generate the SDK client before using it
+- **contentrain-quality** — Content quality rules for entries you query
+- **contentrain** — Core architecture and MCP tool catalog

package/skills/contentrain-query/references/bundler-config.md

@@ -0,0 +1,135 @@
+---
+name: bundler-config
+description: "Framework-specific bundler configuration for #contentrain subpath imports"
+---
+
+# Bundler Configuration for #contentrain
+
+The `#contentrain` import requires subpath imports configuration in `package.json` and bundler-specific aliases.
+
+## package.json (all frameworks)
+
+```json
+{
+  "imports": {
+    "#contentrain": "./.contentrain/client/index.mjs"
+  }
+}
+```
+
+## Vite (Vue, React, Svelte)
+
+```typescript
+// vite.config.ts
+import { resolve } from 'node:path'
+import { defineConfig } from 'vite'
+
+export default defineConfig({
+  resolve: {
+    alias: {
+      '#contentrain': resolve(__dirname, '.contentrain/client/index.mjs')
+    }
+  }
+})
+```
+
+## Next.js
+
+```javascript
+// next.config.mjs
+import { resolve } from 'node:path'
+
+export default {
+  webpack(config) {
+    config.resolve.alias['#contentrain'] = resolve(process.cwd(), '.contentrain/client/index.mjs')
+    return config
+  }
+}
+```
+
+## Nuxt 3
+
+```typescript
+// nuxt.config.ts
+import { resolve } from 'node:path'
+
+export default defineNuxtConfig({
+  alias: {
+    '#contentrain': resolve(__dirname, '.contentrain/client/index.mjs')
+  }
+})
+```
+
+**Important:** Treat `#contentrain` as **server-only** in Nuxt. Use in server routes, server plugins, and `useAsyncData` callbacks only.
+
+## SvelteKit
+
+```javascript
+// svelte.config.js
+import { resolve } from 'node:path'
+
+export default {
+  kit: {
+    alias: {
+      '#contentrain': resolve('.contentrain/client/index.mjs')
+    }
+  }
+}
+```
+
+## Expo / React Native (Metro)
+
+```javascript
+// metro.config.js
+const { getDefaultConfig } = require('expo/metro-config')
+const path = require('path')
+
+const config = getDefaultConfig(__dirname)
+config.resolver.extraNodeModules = {
+  '#contentrain': path.resolve(__dirname, '.contentrain/client/index.cjs')
+}
+module.exports = config
+```
+
+**Bootstrap required:**
+```javascript
+// App.js (before any #contentrain import)
+require('#contentrain').init()
+```
+
+## Node.js (pure ESM)
+
+No alias needed — Node.js natively supports `#imports` in `package.json`:
+
+```json
+{
+  "type": "module",
+  "imports": {
+    "#contentrain": "./.contentrain/client/index.mjs"
+  }
+}
+```
+
+## Node.js (CJS)
+
+```json
+{
+  "imports": {
+    "#contentrain": "./.contentrain/client/index.cjs"
+  }
+}
+```
+
+Bootstrap required:
+```javascript
+const contentrain = require('#contentrain')
+await contentrain.init()
+```
+
+## Watch Mode
+
+For development, run the generator in watch mode to auto-regenerate on model/content changes:
+
+```bash
+npx contentrain generate --watch
+```