@djangocfg/ext-base 1.0.0 → 1.0.1

package/README.md

@@ -6,17 +6,16 @@ Base utilities and common code for building DjangoCFG extensions.
 
 ## What is this?
 
-`@djangocfg/ext-base` is a foundation library for DjangoCFG extensions. It provides:
+`@djangocfg/ext-base` provides the foundation for DjangoCFG extensions with:
 
-- **Extension registration system** - automatic extension metadata tracking
-- **Common React hooks** - pagination, infinite scroll, data fetching patterns
-- **Environment utilities** - isDevelopment, isProduction, isStaticBuild helpers
-- **Type-safe context helpers** - factory functions for creating contexts
-- **Logger utilities** - structured logging with tags
-- **Auth integration** - convenient re-exports of useAuth
-- **TypeScript types** - shared types for all extensions
+- Extension registration system and metadata tracking
+- React hooks for pagination, infinite scroll, and data fetching
+- Environment utilities (isDevelopment, isProduction, isStaticBuild)
+- Type-safe context helpers and logger utilities
+- Auth integration and API factory
+- **CLI tool** for managing extensions
 
-This package is used internally by all official DjangoCFG extensions (newsletter, payments, support, leads, knowbase) and can be used to build your own custom extensions.
+Used internally by official extensions (newsletter, payments, support, leads, knowbase) and for building custom extensions.
 
 ## Install
 
@@ -24,6 +23,35 @@ This package is used internally by all official DjangoCFG extensions (newsletter
 pnpm add @djangocfg/ext-base
 ```
 
+## CLI Usage
+
+The package includes a CLI tool for managing DjangoCFG extensions:
+
+```bash
+# List available extensions
+djangocfg-ext list
+
+# Show extension info
+djangocfg-ext info ext-leads
+
+# Interactive installation wizard
+djangocfg-ext install
+
+# Initialize extension in your project
+djangocfg-ext init
+
+# Show help
+djangocfg-ext help
+```
+
+### Available Extensions
+
+- **@djangocfg/ext-leads** - Lead management and contact forms
+- **@djangocfg/ext-payments** - Payment processing with multiple providers
+- **@djangocfg/ext-newsletter** - Newsletter and email campaigns
+- **@djangocfg/ext-support** - Customer support and ticketing
+- **@djangocfg/ext-knowbase** - Knowledge base and documentation
+
 ## Quick Start
 
 ### 1. Create extension metadata
@@ -35,16 +63,13 @@ import type { ExtensionMetadata } from '@djangocfg/ext-base';
 export const extensionConfig: ExtensionMetadata = {
   name: 'my-extension',
   version: '1.0.0',
-  author: 'Your Name',
   displayName: 'My Extension',
   description: 'Amazing extension functionality',
   icon: '🚀',
-  license: 'MIT',
-  keywords: ['extension', 'feature'],
 };
 ```
 
-### 2. Create your extension provider
+### 2. Create extension provider
 
 ```typescript
 // src/contexts/MyExtensionProvider.tsx
@@ -56,7 +81,6 @@ import { extensionConfig } from '../config';
 export function MyExtensionProvider({ children }) {
   return (
     <ExtensionProvider metadata={extensionConfig}>
-      {/* Your extension contexts here */}
       {children}
     </ExtensionProvider>
   );
@@ -77,60 +101,27 @@ export default function RootLayout({ children }) {
 }
 ```
 
-The extension will automatically register itself and log in development mode:
-```
-[ext-base] Extension registered: My Extension v1.0.0
-```
-
 ## Core Features
 
 ### Environment Configuration
 
 ```typescript
-import { isDevelopment, isProduction, isStaticBuild, isClient, isServer } from '@djangocfg/ext-base';
+import { isDevelopment, isProduction, isStaticBuild } from '@djangocfg/ext-base';
 
 if (isDevelopment) {
   console.log('Running in development mode');
 }
-
-if (isStaticBuild) {
-  // Special handling for Next.js static export
-}
 ```
 
 ### API Factory
 
-Create extension API instances with shared authentication in one line:
+Create extension API instances with automatic configuration:
 
-```typescript
-// src/api/index.ts
-import { API } from './generated/ext_myextension';
-import { createExtensionAPI } from '@djangocfg/ext-base/api';
-
-// That's it! All configuration is handled automatically:
-// - API URL from environment
-// - Static build detection
-// - Shared authentication storage from @djangocfg/api
-export const apiMyExtension = createExtensionAPI(API);
-```
-
-**Before (manual setup):**
-```typescript
-import { API } from './generated/ext_myextension';
-import { api as accountsApi } from '@djangocfg/api';
-
-const isStaticBuild = process.env.NEXT_PUBLIC_STATIC_BUILD === 'true';
-const apiUrl = isStaticBuild ? '' : process.env.NEXT_PUBLIC_API_URL || '';
-const storage = (accountsApi as any)._storage;
-
-export const apiMyExtension = new API(apiUrl, { storage });
-```
-
-**After (with factory):**
 ```typescript
 import { API } from './generated/ext_myextension';
 import { createExtensionAPI } from '@djangocfg/ext-base/api';
 
+// Handles API URL, static build detection, and shared auth automatically
 export const apiMyExtension = createExtensionAPI(API);
 ```
 
@@ -140,23 +131,19 @@ export const apiMyExtension = createExtensionAPI(API);
 import { usePagination, useInfinitePagination } from '@djangocfg/ext-base/hooks';
 
 // Standard pagination
-const { items, page, pageSize, totalPages, goToPage, nextPage, prevPage } = usePagination({
+const { items, page, totalPages, goToPage, nextPage, prevPage } = usePagination({
   keyPrefix: 'articles',
   fetcher: async (page, pageSize) => {
     const response = await api.articles.list({ page, page_size: pageSize });
     return response.data;
   },
-  initialPage: 1,
   pageSize: 20,
 });
 
 // Infinite scroll
 const { items, isLoading, hasMore, loadMore } = useInfinitePagination({
   keyPrefix: 'articles',
-  fetcher: async (page, pageSize) => {
-    const response = await api.articles.list({ page, page_size: pageSize });
-    return response.data;
-  },
+  fetcher: async (page, pageSize) => api.articles.list({ page, page_size: pageSize }).then(r => r.data),
   pageSize: 20,
 });
 ```
@@ -175,12 +162,6 @@ const { Provider, useContext: useMyContext } = createExtensionContext<MyContextV
   displayName: 'MyContext',
   errorMessage: 'useMyContext must be used within MyProvider',
 });
-
-// In components
-export function MyComponent() {
-  const { data, refresh } = useMyContext();
-  return <div>{data.length} items</div>;
-}
 ```
 
 ### Logger
@@ -188,14 +169,11 @@ export function MyComponent() {
 ```typescript
 import { createExtensionLogger } from '@djangocfg/ext-base';
 
-const logger = createExtensionLogger({
-  tag: 'my-extension',
-  level: 'info',
-});
+const logger = createExtensionLogger({ tag: 'my-extension' });
 
 logger.info('Extension initialized');
-logger.error('Something went wrong', error);
-logger.success('Operation completed!');
+logger.error('Operation failed', error);
+logger.success('Completed!');
 ```
 
 ### Auth Integration
@@ -206,135 +184,45 @@ import { useAuth } from '@djangocfg/ext-base/auth';
 function MyComponent() {
   const { user, isAuthenticated, login, logout } = useAuth();
 
-  if (!isAuthenticated) {
-    return <button onClick={login}>Login</button>;
-  }
-
-  return <div>Welcome, {user?.email}</div>;
-}
-```
-
-### Error Handling
-
-```typescript
-import { handleError, formatError } from '@djangocfg/ext-base';
-
-try {
-  await someOperation();
-} catch (error) {
-  handleError(error, (formattedError) => {
-    logger.error('Operation failed:', formattedError);
-  });
+  return isAuthenticated ? (
+    <div>Welcome, {user?.email}</div>
+  ) : (
+    <button onClick={login}>Login</button>
+  );
 }
 ```
 
 ## Package Exports
 
-### Main entry (`@djangocfg/ext-base`)
-Server-safe exports - can be used in both client and server components:
-- All TypeScript types
-- Environment configuration (isDevelopment, isProduction, etc.)
-- API factory (createExtensionAPI)
-- Logger utilities
-- Error handling utilities
-
-### Hooks entry (`@djangocfg/ext-base/hooks`)
-Client-only exports:
-- `ExtensionProvider` - main provider component
-- `usePagination` - standard pagination hook
-- `useInfinitePagination` - infinite scroll hook
-- `createExtensionContext` - context factory
-
-### Auth entry (`@djangocfg/ext-base/auth`)
-Auth re-exports:
-- `useAuth` - authentication hook
-- `UserProfile` type
-- `AuthContextType` type
-
-### API entry (`@djangocfg/ext-base/api`)
-API utilities:
-- `createExtensionAPI` - API instance factory
-- `getSharedAuthStorage` - Get shared auth storage
+| Export | Description | Usage |
+|--------|-------------|-------|
+| `@djangocfg/ext-base` | Server-safe exports (types, environment, API factory, logger, error handling) | Server & client components |
+| `@djangocfg/ext-base/hooks` | Client-only exports (ExtensionProvider, pagination hooks, context factory) | Client components only |
+| `@djangocfg/ext-base/auth` | Auth re-exports (useAuth, types) | Client components only |
+| `@djangocfg/ext-base/api` | API utilities (createExtensionAPI, getSharedAuthStorage) | Server & client components |
 
 ## TypeScript Types
 
 ```typescript
 import type {
-  // Extension metadata
   ExtensionMetadata,
   ExtensionProviderProps,
-
-  // Pagination
   PaginatedResponse,
   PaginationParams,
   PaginationState,
   InfinitePaginationReturn,
-
-  // Logger
   ExtensionLogger,
-  LoggerOptions,
-
-  // Errors
   ExtensionError,
-  ErrorHandler,
-
-  // Context
-  ExtensionContextOptions,
 } from '@djangocfg/ext-base';
 ```
 
-## Example: Complete Extension
-
-```typescript
-// config.ts
-export const extensionConfig: ExtensionMetadata = {
-  name: 'blog',
-  version: '1.0.0',
-  author: 'Your Company',
-  displayName: 'Blog',
-  description: 'Blog management system',
-  icon: '📝',
-  keywords: ['blog', 'articles'],
-};
-
-// contexts/BlogProvider.tsx
-'use client';
-
-import { ExtensionProvider } from '@djangocfg/ext-base/hooks';
-import { useInfinitePagination } from '@djangocfg/ext-base/hooks';
-import { createExtensionLogger } from '@djangocfg/ext-base';
-import { extensionConfig } from '../config';
-
-const logger = createExtensionLogger({ tag: 'blog' });
-
-export function BlogProvider({ children }) {
-  const { items, loadMore, hasMore } = useInfinitePagination({
-    keyPrefix: 'blog-articles',
-    fetcher: async (page, pageSize) => {
-      const response = await api.articles.list({ page, page_size: pageSize });
-      return response.data;
-    },
-  });
-
-  logger.info('Blog provider initialized with', items.length, 'articles');
-
-  return (
-    <ExtensionProvider metadata={extensionConfig}>
-      {/* Your contexts here */}
-      {children}
-    </ExtensionProvider>
-  );
-}
-```
-
 ## Best Practices
 
-1. **Always use ExtensionProvider** - Wrap your extension with it for proper registration
-2. **Define metadata** - Create a `config.ts` file with complete metadata
-3. **Use provided hooks** - Leverage `usePagination` and `useInfinitePagination`
-4. **Structured logging** - Use `createExtensionLogger` with consistent tags
-5. **Type safety** - Import types from `@djangocfg/ext-base`
-6. **Separate entry points** - Use `/hooks` for client code, main entry for server-safe code
+- Always wrap your extension with `ExtensionProvider` for proper registration
+- Define complete metadata in `config.ts`
+- Use provided pagination hooks for consistent data fetching
+- Use `createExtensionLogger` with consistent tags for structured logging
+- Separate client-only code using `/hooks` entry point
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/ext-base",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Base utilities and common code for DjangoCFG extensions",
   "keywords": [
     "django",
@@ -55,26 +55,40 @@
     "dist",
     "src"
   ],
+  "bin": {
+    "djangocfg-ext": "./dist/cli.mjs"
+  },
   "scripts": {
     "build": "tsup",
     "dev": "tsup --watch",
-    "check": "tsc --noEmit"
+    "check": "tsc --noEmit",
+    "cli": "tsx src/cli/index.ts",
+    "cli:help": "tsx src/cli/index.ts --help",
+    "cli:list": "tsx src/cli/index.ts list",
+    "cli:info": "tsx src/cli/index.ts info"
   },
   "peerDependencies": {
-    "@djangocfg/api": "^2.1.14",
+    "@djangocfg/api": "^2.1.15",
     "consola": "^3.4.2",
     "react": "^18 || ^19",
     "react-dom": "^18 || ^19",
     "swr": "^2.3.7"
   },
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "consola": "^3.4.2",
+    "picocolors": "^1.1.1",
+    "prompts": "^2.4.2"
+  },
   "devDependencies": {
-    "@djangocfg/api": "^2.1.14",
-    "@djangocfg/typescript-config": "^2.1.14",
+    "@djangocfg/api": "^2.1.15",
+    "@djangocfg/typescript-config": "^2.1.15",
     "@types/node": "^24.7.2",
+    "@types/prompts": "^2.4.9",
     "@types/react": "^19.0.0",
-    "consola": "^3.4.2",
     "swr": "^2.3.7",
     "tsup": "^8.5.0",
+    "tsx": "^4.19.2",
     "typescript": "^5.9.3"
   }
 }

package/src/cli/index.ts

@@ -0,0 +1,277 @@
+/**
+ * DjangoCFG Extension CLI
+ *
+ * Interactive CLI for managing DjangoCFG extensions
+ */
+
+import { consola } from 'consola';
+import chalk from 'chalk';
+import prompts from 'prompts';
+import { readFileSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// Read package version
+function getVersion(): string {
+  try {
+    const pkgPath = join(__dirname, '../../package.json');
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+    return pkg.version;
+  } catch {
+    return '1.0.0';
+  }
+}
+
+// CLI Commands
+const COMMANDS = {
+  install: 'Install an extension',
+  list: 'List available extensions',
+  info: 'Show extension info',
+  init: 'Initialize extension in your project',
+  help: 'Show help',
+} as const;
+
+type Command = keyof typeof COMMANDS;
+
+// Available extensions
+const EXTENSIONS = {
+  'ext-leads': {
+    name: '@djangocfg/ext-leads',
+    description: 'Lead management and contact forms',
+    features: ['Contact forms', 'Lead tracking', 'Email integration'],
+  },
+  'ext-payments': {
+    name: '@djangocfg/ext-payments',
+    description: 'Payment processing with multiple providers',
+    features: ['NowPayments', 'Crypto payments', 'Payment tracking'],
+  },
+  'ext-newsletter': {
+    name: '@djangocfg/ext-newsletter',
+    description: 'Newsletter and email campaigns',
+    features: ['Subscription management', 'Email templates', 'Campaign tracking'],
+  },
+  'ext-support': {
+    name: '@djangocfg/ext-support',
+    description: 'Customer support and ticketing',
+    features: ['Ticket system', 'Chat support', 'Knowledge base'],
+  },
+  'ext-knowbase': {
+    name: '@djangocfg/ext-knowbase',
+    description: 'Knowledge base and documentation',
+    features: ['Articles', 'Categories', 'Search', 'Markdown support'],
+  },
+} as const;
+
+// Print banner
+function printBanner() {
+  console.log();
+  console.log(chalk.cyan.bold('  🚀 DjangoCFG Extension Manager'));
+  console.log(chalk.gray(`     v${getVersion()}`));
+  console.log();
+}
+
+// Print help
+function printHelp() {
+  printBanner();
+
+  console.log(chalk.yellow.bold('Usage:'));
+  console.log(`  ${chalk.cyan('djangocfg-ext')} ${chalk.gray('[command]')}`);
+  console.log();
+
+  console.log(chalk.yellow.bold('Commands:'));
+  Object.entries(COMMANDS).forEach(([cmd, desc]) => {
+    console.log(`  ${chalk.cyan(cmd.padEnd(12))} ${chalk.gray(desc)}`);
+  });
+  console.log();
+
+  console.log(chalk.yellow.bold('Examples:'));
+  console.log(`  ${chalk.gray('$')} ${chalk.cyan('djangocfg-ext install')}`);
+  console.log(`  ${chalk.gray('$')} ${chalk.cyan('djangocfg-ext list')}`);
+  console.log(`  ${chalk.gray('$')} ${chalk.cyan('djangocfg-ext info ext-leads')}`);
+  console.log();
+}
+
+// List extensions
+function listExtensions() {
+  printBanner();
+  console.log(chalk.yellow.bold('Available Extensions:'));
+  console.log();
+
+  Object.entries(EXTENSIONS).forEach(([key, ext]) => {
+    console.log(chalk.cyan.bold(`  📦 ${ext.name}`));
+    console.log(chalk.gray(`     ${ext.description}`));
+    console.log(chalk.gray(`     Features: ${ext.features.join(', ')}`));
+    console.log();
+  });
+}
+
+// Show extension info
+function showInfo(extensionKey: string) {
+  const ext = EXTENSIONS[extensionKey as keyof typeof EXTENSIONS];
+
+  if (!ext) {
+    consola.error(`Extension not found: ${extensionKey}`);
+    consola.info('Run `djangocfg-ext list` to see available extensions');
+    return;
+  }
+
+  printBanner();
+  console.log(chalk.cyan.bold(`📦 ${ext.name}`));
+  console.log();
+  console.log(chalk.white(ext.description));
+  console.log();
+  console.log(chalk.yellow.bold('Features:'));
+  ext.features.forEach(feature => {
+    console.log(chalk.gray(`  • ${feature}`));
+  });
+  console.log();
+  console.log(chalk.yellow.bold('Installation:'));
+  console.log(chalk.gray(`  pnpm add ${ext.name}`));
+  console.log();
+}
+
+// Install extension
+async function installExtension() {
+  printBanner();
+
+  const response = await prompts({
+    type: 'select',
+    name: 'extension',
+    message: 'Which extension would you like to install?',
+    choices: Object.entries(EXTENSIONS).map(([key, ext]) => ({
+      title: ext.name,
+      description: ext.description,
+      value: key,
+    })),
+  });
+
+  if (!response.extension) {
+    consola.info('Installation cancelled');
+    return;
+  }
+
+  const ext = EXTENSIONS[response.extension as keyof typeof EXTENSIONS];
+
+  console.log();
+  consola.info(`Installing ${chalk.cyan(ext.name)}...`);
+  console.log();
+
+  // Show installation command
+  console.log(chalk.yellow.bold('Run this command:'));
+  console.log(chalk.cyan(`  pnpm add ${ext.name}`));
+  console.log();
+
+  console.log(chalk.yellow.bold('Then import in your app:'));
+  console.log(chalk.gray(`  import { ExtensionProvider } from '${ext.name}';`));
+  console.log();
+
+  consola.success('See documentation at https://djangocfg.com/docs');
+}
+
+// Init extension in project
+async function initExtension() {
+  printBanner();
+
+  console.log(chalk.yellow('This will create extension configuration in your project'));
+  console.log();
+
+  const response = await prompts([
+    {
+      type: 'select',
+      name: 'extension',
+      message: 'Which extension do you want to configure?',
+      choices: Object.entries(EXTENSIONS).map(([key, ext]) => ({
+        title: ext.name,
+        description: ext.description,
+        value: key,
+      })),
+    },
+    {
+      type: 'confirm',
+      name: 'confirm',
+      message: 'Generate extension configuration?',
+      initial: true,
+    },
+  ]);
+
+  if (!response.confirm) {
+    consola.info('Initialization cancelled');
+    return;
+  }
+
+  const ext = EXTENSIONS[response.extension as keyof typeof EXTENSIONS];
+
+  console.log();
+  consola.info(`Initializing ${chalk.cyan(ext.name)}...`);
+  console.log();
+
+  // Show what to do next
+  console.log(chalk.yellow.bold('Next steps:'));
+  console.log(chalk.gray('  1. Install the extension: ') + chalk.cyan(`pnpm add ${ext.name}`));
+  console.log(chalk.gray('  2. Add provider to your layout:'));
+  console.log();
+  console.log(chalk.gray('     ') + chalk.white('import { ExtensionProvider } from \'' + ext.name + '\';'));
+  console.log();
+  console.log(chalk.gray('     ') + chalk.white('<ExtensionProvider>'));
+  console.log(chalk.gray('       ') + chalk.white('{children}'));
+  console.log(chalk.gray('     ') + chalk.white('</ExtensionProvider>'));
+  console.log();
+
+  consola.success('Initialization complete!');
+}
+
+// Main CLI
+async function main() {
+  const args = process.argv.slice(2);
+  const command = args[0] as Command;
+
+  // No command - show help
+  if (!command) {
+    printHelp();
+    return;
+  }
+
+  // Handle commands
+  switch (command) {
+    case 'list':
+      listExtensions();
+      break;
+
+    case 'info':
+      const extKey = args[1];
+      if (!extKey) {
+        consola.error('Please specify an extension');
+        consola.info('Example: djangocfg-ext info ext-leads');
+        return;
+      }
+      showInfo(extKey);
+      break;
+
+    case 'install':
+      await installExtension();
+      break;
+
+    case 'init':
+      await initExtension();
+      break;
+
+    case 'help':
+    case '--help':
+    case '-h':
+      printHelp();
+      break;
+
+    default:
+      consola.error(`Unknown command: ${command}`);
+      console.log();
+      printHelp();
+      process.exit(1);
+  }
+}
+
+main().catch((error) => {
+  consola.error('CLI error:', error);
+  process.exit(1);
+});