@djangocfg/ext-base 1.0.0 → 1.0.2

package/README.md

@@ -1,3 +1,9 @@
+<div align="center">
+
+![DjangoCFG Extension Preview](https://unpkg.com/@djangocfg/ext-base@latest/preview.png)
+
+</div>
+
 # @djangocfg/ext-base
 
 Base utilities and common code for building DjangoCFG extensions.
@@ -6,17 +12,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,27 +29,64 @@ 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 creating new DjangoCFG extensions:
+
+```bash
+# Create a new extension with interactive wizard
+djangocfg-ext create
+
+# Show help
+djangocfg-ext help
+```
+
+The CLI will guide you through creating a new extension with proper structure and configuration using the `createExtensionConfig` helper.
+
 ## Quick Start
 
 ### 1. Create extension metadata
 
+Use the `createExtensionConfig` helper to automatically pull data from package.json:
+
 ```typescript
 // src/config.ts
-import type { ExtensionMetadata } from '@djangocfg/ext-base';
+import { createExtensionConfig } from '@djangocfg/ext-base';
+import packageJson from '../package.json';
 
-export const extensionConfig: ExtensionMetadata = {
+export const extensionConfig = createExtensionConfig(packageJson, {
   name: 'my-extension',
-  version: '1.0.0',
-  author: 'Your Name',
   displayName: 'My Extension',
-  description: 'Amazing extension functionality',
-  icon: '🚀',
-  license: 'MIT',
-  keywords: ['extension', 'feature'],
-};
+  icon: 'Rocket', // Lucide icon name
+  category: 'utilities',
+  features: [
+    'Feature 1',
+    'Feature 2',
+    'Feature 3',
+  ],
+  minVersion: '2.0.0',
+  examples: [
+    {
+      title: 'Basic Usage',
+      description: 'How to use this extension',
+      code: `import { MyComponent } from '@your-org/my-extension';`,
+      language: 'tsx',
+    },
+  ],
+});
 ```
 
-### 2. Create your extension provider
+This automatically imports from package.json:
+- version
+- author
+- description
+- license
+- homepage
+- githubUrl (from repository)
+- keywords
+- peerDependencies
+
+### 2. Create extension provider
 
 ```typescript
 // src/contexts/MyExtensionProvider.tsx
@@ -56,7 +98,6 @@ import { extensionConfig } from '../config';
 export function MyExtensionProvider({ children }) {
   return (
     <ExtensionProvider metadata={extensionConfig}>
-      {/* Your extension contexts here */}
       {children}
     </ExtensionProvider>
   );
@@ -77,60 +118,73 @@ 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
+### Extension Config Helper
 
-```typescript
-import { isDevelopment, isProduction, isStaticBuild, isClient, isServer } from '@djangocfg/ext-base';
+The `createExtensionConfig` helper creates a typed extension configuration by combining package.json data with manual metadata:
 
-if (isDevelopment) {
-  console.log('Running in development mode');
-}
+```typescript
+import { createExtensionConfig, type ExtensionConfigInput } from '@djangocfg/ext-base';
+import packageJson from '../package.json';
 
-if (isStaticBuild) {
-  // Special handling for Next.js static export
-}
+export const extensionConfig = createExtensionConfig(packageJson, {
+  // Required fields
+  name: 'my-extension',
+  displayName: 'My Extension',
+  icon: 'Package', // Lucide icon name
+  category: 'utilities', // 'forms' | 'payments' | 'content' | 'support' | 'utilities' | 'analytics' | 'security' | 'integration' | 'other'
+  features: ['Feature list for marketplace'],
+
+  // Optional fields
+  minVersion: '2.0.0',
+  githubStars: 100,
+  relatedExtensions: ['other-extension'],
+  examples: [
+    {
+      title: 'Example title',
+      description: 'Example description',
+      code: 'import { Component } from "@your-org/my-extension";',
+      language: 'tsx',
+    },
+  ],
+});
 ```
 
-### API Factory
+**Automatically imported from package.json:**
+- `version` - Package version
+- `author` - Author name (from string or object)
+- `description` - Package description
+- `license` - License type
+- `homepage` - Homepage URL
+- `githubUrl` - Repository URL
+- `keywords` - Keywords array
+- `peerDependencies` - Peer dependencies
+
+**Auto-generated:**
+- `npmUrl` - npm package URL
+- `installCommand` - pnpm install command
+- `tags` - Same as keywords
 
-Create extension API instances with shared authentication in one line:
+### Environment Configuration
 
 ```typescript
-// src/api/index.ts
-import { API } from './generated/ext_myextension';
-import { createExtensionAPI } from '@djangocfg/ext-base/api';
+import { isDevelopment, isProduction, isStaticBuild } from '@djangocfg/ext-base';
 
-// 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);
+if (isDevelopment) {
+  console.log('Running in development mode');
+}
 ```
 
-**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;
+### API Factory
 
-export const apiMyExtension = new API(apiUrl, { storage });
-```
+Create extension API instances with automatic configuration:
 
-**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 +194,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 +225,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 +232,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,62 +247,34 @@ 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
+  // Extension configuration
   ExtensionMetadata,
+  ExtensionConfigInput,
+  ExtensionCategory,
+  ExtensionExample,
+
+  // Provider
   ExtensionProviderProps,
 
   // Pagination
@@ -270,71 +283,22 @@ import type {
   PaginationState,
   InfinitePaginationReturn,
 
-  // Logger
+  // Utilities
   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
+- Use `createExtensionConfig` helper to maintain Single Source of Truth from package.json
+- Always wrap your extension with `ExtensionProvider` for proper registration
+- Use Lucide icon names (not emoji) for `icon` field
+- Include comprehensive `features` list for marketplace visibility
+- Provide code `examples` with proper syntax highlighting
+- 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.2",
   "description": "Base utilities and common code for DjangoCFG extensions",
   "keywords": [
     "django",
@@ -27,54 +27,70 @@
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.cjs",
-  "module": "./dist/index.mjs",
+  "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.mjs",
+      "import": "./dist/index.js",
       "require": "./dist/index.cjs"
     },
     "./hooks": {
       "types": "./dist/hooks.d.ts",
-      "import": "./dist/hooks.mjs",
+      "import": "./dist/hooks.js",
       "require": "./dist/hooks.cjs"
     },
     "./auth": {
       "types": "./dist/auth.d.ts",
-      "import": "./dist/auth.mjs",
+      "import": "./dist/auth.js",
       "require": "./dist/auth.cjs"
     },
     "./api": {
       "types": "./dist/api.d.ts",
-      "import": "./dist/api.mjs",
+      "import": "./dist/api.js",
       "require": "./dist/api.cjs"
     }
   },
   "files": [
     "dist",
-    "src"
+    "src",
+    "preview.png",
+    "templates"
   ],
+  "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"
   }
 }