@djangocfg/nextjs 1.0.17 → 2.1.2

package/README.md

@@ -18,6 +18,7 @@
 ## Features
 
 - **Base Next.js Config** - Universal, reusable Next.js configuration factory for monorepos
+- **AI Documentation** - Search DjangoCFG docs via MCP server and CLI
 - **Sitemap Generation** - Dynamic XML sitemap generation for SEO
 - **Health Checks** - Production-ready health monitoring endpoints
 - **OG Images** - Dynamic Open Graph image generation with templates
@@ -38,6 +39,46 @@ yarn add @djangocfg/nextjs
 
 ## Quick Start
 
+### AI Documentation Search
+
+Search DjangoCFG documentation from the terminal:
+
+```bash
+# CLI
+pnpm ai-docs search "database configuration"
+pnpm ai-docs mcp
+```
+
+Or use the TypeScript API:
+
+```tsx
+import { search, getDocs, getMcpConfig } from '@djangocfg/nextjs/ai';
+
+// Search documentation
+const results = await search('database configuration');
+results.forEach(r => console.log(r.title, r.url));
+
+// Get formatted docs
+const docs = await getDocs('How to configure PostgreSQL?');
+
+// Get MCP server config for AI assistants
+const config = getMcpConfig();
+```
+
+### MCP Server for AI Assistants
+
+Add to your AI assistant configuration:
+
+```json
+{
+  "mcpServers": {
+    "djangocfg-docs": {
+      "url": "https://mcp.djangocfg.com/mcp"
+    }
+  }
+}
+```
+
 ### Base Next.js Configuration
 
 Create a reusable base configuration for all your Next.js projects:
@@ -203,6 +244,7 @@ import { RedirectPage } from '@djangocfg/layouts/components/RedirectPage';
 | Path | Description |
 |------|-------------|
 | `@djangocfg/nextjs` | Main exports (all modules) |
+| `@djangocfg/nextjs/ai` | AI documentation search and MCP config |
 | `@djangocfg/nextjs/config` | Base Next.js configuration factory |
 | `@djangocfg/nextjs/sitemap` | Sitemap generation utilities |
 | `@djangocfg/nextjs/health` | Health check handlers |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/nextjs",
-  "version": "1.0.17",
+  "version": "2.1.2",
   "description": "Next.js server utilities: sitemap, health, OG images, contact forms, navigation, config",
   "keywords": [
     "nextjs",
@@ -79,6 +79,11 @@
       "types": "./src/scripts/index.ts",
       "import": "./src/scripts/index.ts",
       "default": "./src/scripts/index.ts"
+    },
+    "./ai": {
+      "types": "./src/ai/index.ts",
+      "import": "./src/ai/index.ts",
+      "default": "./src/ai/index.ts"
     }
   },
   "files": [
@@ -86,22 +91,26 @@
     "README.md",
     "LICENSE"
   ],
+  "bin": {
+    "ai-docs": "./src/ai/cli.ts"
+  },
   "scripts": {
     "build": "tsup",
     "dev": "tsup --watch",
     "clean": "rm -rf dist",
     "lint": "eslint .",
     "check": "tsc --noEmit",
-    "check-links": "tsx src/scripts/check-links.ts"
+    "check-links": "tsx src/scripts/check-links.ts",
+    "ai-docs": "tsx src/ai/cli.ts"
   },
   "peerDependencies": {
-    "@djangocfg/api": "^1.4.47",
+    "@djangocfg/api": "^2.1.2",
     "next": "^15.5.7"
   },
   "devDependencies": {
-    "@djangocfg/imgai": "^1.0.33",
-    "@djangocfg/layouts": "^2.0.17",
-    "@djangocfg/typescript-config": "^1.4.47",
+    "@djangocfg/imgai": "^2.1.2",
+    "@djangocfg/layouts": "^2.1.2",
+    "@djangocfg/typescript-config": "^2.1.2",
     "@types/node": "^24.7.2",
     "@types/react": "19.2.2",
     "@types/react-dom": "19.2.1",

package/src/ai/CLAUDE.md

@@ -0,0 +1,48 @@
+# @djangocfg/nextjs - AI Documentation
+
+DjangoCFG documentation is available via MCP server.
+
+## MCP Server
+
+```json
+{
+    "mcpServers": {
+        "djangocfg-docs": {
+            "url": "https://mcp.djangocfg.com/mcp"
+        }
+    }
+}
+```
+
+## API
+
+```bash
+curl 'https://mcp.djangocfg.com/api/search?q=database+configuration&limit=5'
+```
+
+## TypeScript
+
+```ts
+import { search, getDocs, getMcpConfig } from '@djangocfg/nextjs/ai';
+
+// Search documentation
+const results = await search('database configuration');
+results.forEach(r => console.log(r.title, r.url));
+
+// Get formatted docs
+const docs = await getDocs('How to configure PostgreSQL?');
+
+// Get MCP config
+const config = getMcpConfig();
+```
+
+## Common Topics
+
+- DatabaseConfig - PostgreSQL, MySQL, SQLite
+- CacheConfig - Redis, Memcached
+- EmailConfig - SMTP, SendGrid
+- LoggingConfig - Logging setup
+- SecurityConfig - CORS, CSRF
+- DRFConfig - Django REST Framework
+- OG Image - Open Graph image generation
+- Sitemap - XML sitemap generation

package/src/ai/cli.ts

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+/**
+ * DjangoCFG AI Docs CLI
+ *
+ * Usage:
+ *   pnpm exec ai-docs search "database configuration"
+ *   pnpm exec ai-docs mcp
+ *   npx @djangocfg/nextjs ai-docs search "query"
+ */
+
+import { search, getMcpConfig, MCP_SERVER_URL, MCP_API_URL } from './index';
+
+const args = process.argv.slice(2);
+const command = args[0];
+const query = args.slice(1).join(' ');
+
+async function main() {
+  switch (command) {
+    case 'search':
+    case 's':
+      if (!query) {
+        console.error('Usage: ai-docs search "your query"');
+        process.exit(1);
+      }
+      console.log(`\n🔍 Searching: ${query}\n`);
+      try {
+        const results = await search(query, { limit: 5 });
+        if (results.length === 0) {
+          console.log('No results found.');
+        } else {
+          results.forEach((r, i) => {
+            console.log(`${i + 1}. ${r.title}`);
+            console.log(`   ${r.content.slice(0, 150)}...`);
+            if (r.url) console.log(`   📖 ${r.url}`);
+            console.log('');
+          });
+        }
+      } catch (err) {
+        console.error('Error:', err instanceof Error ? err.message : err);
+        process.exit(1);
+      }
+      break;
+
+    case 'mcp':
+      console.log('\n📡 MCP Server Configuration:\n');
+      console.log(JSON.stringify(getMcpConfig(), null, 2));
+      console.log('\nAdd this to your AI assistant configuration.');
+      break;
+
+    case 'info':
+    case 'i':
+      console.log('\n🤖 DjangoCFG AI Documentation\n');
+      console.log(`MCP Server: ${MCP_SERVER_URL}`);
+      console.log(`Search API: ${MCP_API_URL}`);
+      console.log('\nUsage:');
+      console.log('  pnpm exec ai-docs search "database configuration"');
+      console.log('  pnpm exec ai-docs mcp');
+      break;
+
+    default:
+      console.log('🤖 DjangoCFG AI Documentation CLI\n');
+      console.log('Commands:');
+      console.log('  search <query>  Search documentation');
+      console.log('  mcp             Show MCP server config');
+      console.log('  info            Show help\n');
+      console.log('Examples:');
+      console.log('  pnpm exec ai-docs search "database configuration"');
+      console.log('  pnpm exec ai-docs search "redis cache"');
+      console.log('  pnpm exec ai-docs mcp');
+      break;
+  }
+}
+
+main();

package/src/ai/client.ts

@@ -0,0 +1,171 @@
+/**
+ * DjangoCFG Documentation Client
+ *
+ * HTTP client for accessing DjangoCFG documentation via MCP server API.
+ */
+
+import {
+  MCP_BASE_URL,
+  API_SEARCH_ENDPOINT,
+  API_INFO_ENDPOINT,
+  DEFAULT_TIMEOUT,
+} from './constants';
+import type { SearchResult, SearchOptions, McpConfig, ApiSearchResponse } from './types';
+
+/**
+ * Client for DjangoCFG Documentation API.
+ */
+export class DjangoCfgDocsClient {
+  private baseUrl: string;
+  private timeout: number;
+
+  constructor(baseUrl: string = MCP_BASE_URL, timeout: number = DEFAULT_TIMEOUT) {
+    this.baseUrl = baseUrl.replace(/\/$/, '');
+    this.timeout = timeout;
+  }
+
+  private async makeRequest<T>(endpoint: string, params?: Record<string, string | number>): Promise<T> {
+    let url = `${this.baseUrl}${endpoint}`;
+
+    if (params) {
+      const searchParams = new URLSearchParams();
+      for (const [key, value] of Object.entries(params)) {
+        searchParams.set(key, String(value));
+      }
+      url = `${url}?${searchParams.toString()}`;
+    }
+
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+
+    try {
+      const response = await fetch(url, {
+        method: 'GET',
+        headers: {
+          Accept: 'application/json',
+          'User-Agent': 'DjangoCFG-AI-Client/1.0',
+        },
+        signal: controller.signal,
+      });
+
+      if (!response.ok) {
+        throw new Error(`HTTP Error ${response.status}: ${response.statusText}`);
+      }
+
+      return await response.json();
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+
+  /**
+   * Search documentation.
+   */
+  async search(query: string, options: SearchOptions = {}): Promise<SearchResult[]> {
+    const { limit = 5, category } = options;
+
+    const params: Record<string, string | number> = { q: query, limit };
+    if (category) {
+      params.category = category;
+    }
+
+    const data = await this.makeRequest<ApiSearchResponse>(API_SEARCH_ENDPOINT, params);
+
+    const results = data.results || (Array.isArray(data) ? data : []);
+
+    return results.map((item) => ({
+      title: item.title || '',
+      content: item.content || item.snippet || '',
+      url: item.url || '',
+      score: item.score || 0,
+      category: item.category || '',
+    }));
+  }
+
+  /**
+   * Get detailed info about a specific topic.
+   */
+  async getInfo(topic: string): Promise<Record<string, unknown>> {
+    return this.makeRequest(API_INFO_ENDPOINT, { topic });
+  }
+
+  /**
+   * Get MCP server configuration for AI assistants.
+   */
+  getMcpConfig(): McpConfig {
+    return {
+      mcpServers: {
+        'djangocfg-docs': {
+          url: `${this.baseUrl}/mcp`,
+        },
+      },
+    };
+  }
+}
+
+// Default client instance
+let defaultClient: DjangoCfgDocsClient | null = null;
+
+function getClient(): DjangoCfgDocsClient {
+  if (!defaultClient) {
+    defaultClient = new DjangoCfgDocsClient();
+  }
+  return defaultClient;
+}
+
+/**
+ * Search DjangoCFG documentation.
+ *
+ * @example
+ * ```ts
+ * const results = await search('database configuration');
+ * results.forEach(r => console.log(r.title, r.url));
+ * ```
+ */
+export async function search(query: string, options: SearchOptions = {}): Promise<SearchResult[]> {
+  return getClient().search(query, options);
+}
+
+/**
+ * Get documentation as formatted text.
+ *
+ * @example
+ * ```ts
+ * const docs = await getDocs('How to configure PostgreSQL?');
+ * console.log(docs);
+ * ```
+ */
+export async function getDocs(query: string, limit: number = 3): Promise<string> {
+  const results = await search(query, { limit });
+
+  if (results.length === 0) {
+    return `No documentation found for: ${query}`;
+  }
+
+  const output: string[] = [];
+
+  results.forEach((r, i) => {
+    output.push(`## ${i + 1}. ${r.title}`);
+    output.push(r.content);
+    if (r.url) {
+      output.push(`📖 Read more: ${r.url}`);
+    }
+    output.push('');
+  });
+
+  return output.join('\n');
+}
+
+/**
+ * Get detailed info about a topic.
+ */
+export async function getInfo(topic: string): Promise<Record<string, unknown>> {
+  return getClient().getInfo(topic);
+}
+
+/**
+ * Get MCP server configuration.
+ */
+export function getMcpConfig(): McpConfig {
+  return getClient().getMcpConfig();
+}

package/src/ai/constants.ts

@@ -0,0 +1,31 @@
+/**
+ * AI Documentation Constants
+ */
+
+// MCP Server URLs
+export const MCP_BASE_URL = 'https://mcp.djangocfg.com';
+export const MCP_SERVER_URL = `${MCP_BASE_URL}/mcp`;
+export const MCP_API_URL = `${MCP_BASE_URL}/api/search`;
+
+// API Endpoints
+export const API_SEARCH_ENDPOINT = '/api/search';
+export const API_INFO_ENDPOINT = '/api/info';
+export const DEFAULT_TIMEOUT = 10000; // ms
+
+// AI Hint for console output
+export const AI_DOCS_HINT = `🤖 AI Docs: ${MCP_SERVER_URL} | pnpm ai-docs search "query"`;
+
+// Full AI Hint description
+export const AI_HINT = `
+DjangoCFG Documentation is available via MCP server.
+
+To get help with DjangoCFG configuration:
+1. Use the MCP server: ${MCP_SERVER_URL}
+2. Or search directly: ${MCP_API_URL}?q=YOUR_QUERY&limit=5
+
+Example queries:
+- "How to configure PostgreSQL database?"
+- "What is DatabaseConfig?"
+- "How to setup Redis cache?"
+- "Email configuration with SMTP"
+`;

package/src/ai/index.ts

@@ -0,0 +1,29 @@
+/**
+ * DjangoCFG AI Documentation Client
+ *
+ * Provides access to DjangoCFG documentation via MCP server API.
+ *
+ * @example
+ * ```ts
+ * import { search, getDocs, getMcpConfig } from '@djangocfg/nextjs/ai';
+ *
+ * // Search documentation
+ * const results = await search('database configuration');
+ *
+ * // Get formatted docs
+ * const docs = await getDocs('How to configure PostgreSQL?');
+ *
+ * // Get MCP config for AI assistants
+ * const config = getMcpConfig();
+ * ```
+ */
+
+export { DjangoCfgDocsClient, search, getDocs, getInfo, getMcpConfig } from './client';
+export type { SearchResult, SearchOptions, McpConfig } from './types';
+export {
+  MCP_BASE_URL,
+  MCP_SERVER_URL,
+  MCP_API_URL,
+  AI_DOCS_HINT,
+  AI_HINT,
+} from './constants';

package/src/ai/types.ts

@@ -0,0 +1,35 @@
+/**
+ * AI Documentation Types
+ */
+
+export interface SearchResult {
+  title: string;
+  content: string;
+  url: string;
+  score: number;
+  category: string;
+}
+
+export interface SearchOptions {
+  limit?: number;
+  category?: string;
+}
+
+export interface McpConfig {
+  mcpServers: {
+    'djangocfg-docs': {
+      url: string;
+    };
+  };
+}
+
+export interface ApiSearchResponse {
+  results: Array<{
+    title: string;
+    content?: string;
+    snippet?: string;
+    url: string;
+    score?: number;
+    category?: string;
+  }>;
+}

package/src/config/constants.ts

@@ -31,7 +31,6 @@ export const DJANGOCFG_PACKAGES = [
   '@djangocfg/nextjs',
   '@djangocfg/api',
   '@djangocfg/centrifugo',
-  '@djangocfg/imgai',
   '@djangocfg/eslint-config',
   '@djangocfg/typescript-config',
 ] as const;

package/src/config/index.ts

@@ -24,6 +24,14 @@ export {
   DJANGO_CFG_BANNER,
 } from './constants';
 
+// Re-export AI constants from ai module
+export {
+  MCP_BASE_URL,
+  MCP_SERVER_URL,
+  MCP_API_URL,
+  AI_DOCS_HINT,
+} from '../ai/constants';
+
 // Utils
 export { deepMerge } from './utils/deepMerge';
 export {

package/src/config/packages/updater.ts

@@ -12,7 +12,7 @@ import chalk from 'chalk';
 import consola from 'consola';
 import Conf from 'conf';
 import semver from 'semver';
-import { DJANGOCFG_PACKAGES } from '../constants';
+import { DJANGOCFG_PACKAGES, PACKAGE_NAME } from '../constants';
 import { isCI } from '../utils/env';
 import { detectPackageManager } from './installer';
 
@@ -146,12 +146,21 @@ async function fetchLatestVersion(packageName: string): Promise<string | null> {
 
 /**
  * Check all @djangocfg packages for updates
+ * All packages are aligned to the version of @djangocfg/nextjs (master package)
  * Skips workspace:* packages unless forceCheckWorkspace is true
  */
 export async function checkForUpdates(options: { forceCheckWorkspace?: boolean } = {}): Promise<PackageVersion[]> {
   const results: PackageVersion[] = [];
 
-  // Check packages in parallel
+  // First, get the latest version of master package (@djangocfg/nextjs)
+  // All other packages should align to this version
+  const masterLatest = await fetchLatestVersion(PACKAGE_NAME);
+  if (!masterLatest) {
+    // Can't determine target version, skip update check
+    return results;
+  }
+
+  // Check packages against master version
   const checks = DJANGOCFG_PACKAGES.map(async (name) => {
     // Skip workspace packages unless force mode
     const isWorkspace = !shouldCheckUpdates(name);
@@ -164,10 +173,10 @@ export async function checkForUpdates(options: { forceCheckWorkspace?: boolean }
       return null;
     }
 
-    const latest = await fetchLatestVersion(name);
-    const hasUpdate = !!(latest && current && semver.gt(latest, current));
+    // All packages should update to master package version
+    const hasUpdate = !!(masterLatest && current && semver.gt(masterLatest, current));
 
-    return { name, current, latest, hasUpdate };
+    return { name, current, latest: masterLatest, hasUpdate };
   });
 
   const checkResults = await Promise.all(checks);
@@ -291,11 +300,12 @@ async function updateSinglePackage(
 
   spinner.start();
 
+  // Always install with @latest to keep package.json consistent
   const command = pm === 'pnpm'
-    ? `pnpm add ${pkg.name}@${pkg.latest}`
+    ? `pnpm add ${pkg.name}@latest`
     : pm === 'yarn'
-    ? `yarn add ${pkg.name}@${pkg.latest}`
-    : `npm install ${pkg.name}@${pkg.latest}`;
+    ? `yarn add ${pkg.name}@latest`
+    : `npm install ${pkg.name}@latest`;
 
   return new Promise((resolve) => {
     const proc = spawn(command, {

package/src/config/plugins/devStartup.ts

@@ -7,6 +7,7 @@
 import type { Compiler } from 'webpack';
 import chalk from 'chalk';
 import { DJANGO_CFG_BANNER } from '../constants';
+import { AI_DOCS_HINT } from '../../ai/constants';
 import { getCurrentVersion } from '../utils/version';
 import { checkAndInstallPackages } from '../packages/installer';
 import { checkAndUpdatePackages } from '../packages/updater';
@@ -64,10 +65,13 @@ export class DevStartupPlugin {
     // 2. Print current version
     const version = getCurrentVersion();
     if (version) {
-      console.log(chalk.dim(`  📦 @djangocfg/nextjs v${version}\n`));
+      console.log(chalk.dim(`  📦 @djangocfg/nextjs v${version}`));
     }
 
-    // 3. Check for package updates
+    // 3. Print AI docs hint
+    console.log(chalk.magenta(`  ${AI_DOCS_HINT}\n`));
+
+    // 4. Check for package updates
     if (this.options.checkUpdates !== false) {
       try {
         await checkAndUpdatePackages({
@@ -80,7 +84,7 @@ export class DevStartupPlugin {
       }
     }
 
-    // 4. Check for missing optional packages
+    // 5. Check for missing optional packages
     if (this.options.checkPackages !== false) {
       await checkAndInstallPackages({
         autoInstall: this.options.autoInstall,

package/src/index.ts

@@ -22,6 +22,9 @@ export * from './navigation';
 // Config
 export * from './config';
 
+// AI Documentation
+export * from './ai';
+
 // Types
 export type * from './types';