@djangocfg/ext-base 1.0.1 → 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.
@@ -25,50 +31,61 @@ pnpm add @djangocfg/ext-base
 
 ## CLI Usage
 
-The package includes a CLI tool for managing DjangoCFG extensions:
+The package includes a CLI tool for creating new 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
+# Create a new extension with interactive wizard
+djangocfg-ext create
 
 # 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
+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',
   displayName: 'My Extension',
-  description: 'Amazing extension functionality',
-  icon: '🚀',
-};
+  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',
+    },
+  ],
+});
 ```
 
+This automatically imports from package.json:
+- version
+- author
+- description
+- license
+- homepage
+- githubUrl (from repository)
+- keywords
+- peerDependencies
+
 ### 2. Create extension provider
 
 ```typescript
@@ -103,6 +120,52 @@ export default function RootLayout({ children }) {
 
 ## Core Features
 
+### Extension Config Helper
+
+The `createExtensionConfig` helper creates a typed extension configuration by combining package.json data with manual metadata:
+
+```typescript
+import { createExtensionConfig, type ExtensionConfigInput } from '@djangocfg/ext-base';
+import packageJson from '../package.json';
+
+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',
+    },
+  ],
+});
+```
+
+**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
+
 ### Environment Configuration
 
 ```typescript
@@ -205,12 +268,22 @@ function MyComponent() {
 
 ```typescript
 import type {
+  // Extension configuration
   ExtensionMetadata,
+  ExtensionConfigInput,
+  ExtensionCategory,
+  ExtensionExample,
+
+  // Provider
   ExtensionProviderProps,
+
+  // Pagination
   PaginatedResponse,
   PaginationParams,
   PaginationState,
   InfinitePaginationReturn,
+
+  // Utilities
   ExtensionLogger,
   ExtensionError,
 } from '@djangocfg/ext-base';
@@ -218,8 +291,11 @@ import type {
 
 ## Best Practices
 
+- Use `createExtensionConfig` helper to maintain Single Source of Truth from package.json
 - Always wrap your extension with `ExtensionProvider` for proper registration
-- Define complete metadata in `config.ts`
+- 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/ext-base",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Base utilities and common code for DjangoCFG extensions",
   "keywords": [
     "django",
@@ -27,33 +27,35 @@
   "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"

package/src/cli/index.ts

@@ -7,9 +7,10 @@
 import { consola } from 'consola';
 import chalk from 'chalk';
 import prompts from 'prompts';
-import { readFileSync } from 'fs';
+import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync, statSync } from 'fs';
 import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
+import { EXTENSION_CATEGORIES } from '../types/context';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
@@ -26,43 +27,62 @@ function getVersion(): string {
 
 // CLI Commands
 const COMMANDS = {
-  install: 'Install an extension',
-  list: 'List available extensions',
-  info: 'Show extension info',
-  init: 'Initialize extension in your project',
+  create: 'Create a new DjangoCFG extension',
   help: 'Show help',
+  '--help': 'Show help',
+  '-h': '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;
+// Template helpers
+function replacePlaceholders(content: string, replacements: Record<string, string>): string {
+  let result = content;
+  for (const [key, value] of Object.entries(replacements)) {
+    result = result.replaceAll(key, value);
+  }
+  return result;
+}
+
+function copyTemplateRecursive(src: string, dest: string, replacements: Record<string, string>) {
+  if (!existsSync(src)) {
+    throw new Error(`Template not found: ${src}`);
+  }
+
+  const stats = statSync(src);
+
+  if (stats.isDirectory()) {
+    // Create destination directory
+    if (!existsSync(dest)) {
+      mkdirSync(dest, { recursive: true });
+    }
+
+    // Copy all files recursively
+    const files = readdirSync(src);
+    for (const file of files) {
+      const srcPath = join(src, file);
+      let destFile = file;
+
+      // Replace __PROVIDER_NAME__ in filenames
+      if (file.includes('__PROVIDER_NAME__')) {
+        destFile = file.replaceAll('__PROVIDER_NAME__', replacements['__PROVIDER_NAME__']);
+      }
+
+      // Remove .template extension
+      if (destFile.endsWith('.template')) {
+        destFile = destFile.slice(0, -9); // Remove '.template'
+      }
+
+      const destPath = join(dest, destFile);
+      copyTemplateRecursive(srcPath, destPath, replacements);
+    }
+  } else {
+    // Copy file with placeholder replacement
+    const content = readFileSync(src, 'utf-8');
+    const replaced = replacePlaceholders(content, replacements);
+    writeFileSync(dest, replaced, 'utf-8');
+  }
+}
 
 // Print banner
 function printBanner() {
@@ -87,139 +107,134 @@ function printHelp() {
   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(`  ${chalk.gray('$')} ${chalk.cyan('djangocfg-ext create')}`);
   console.log();
 }
 
-// List extensions
-function listExtensions() {
+// Create new extension
+async function createExtension() {
   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();
-  });
-}
+  console.log(chalk.yellow('Create a new DjangoCFG extension'));
+  console.log();
 
-// Show extension info
-function showInfo(extensionKey: string) {
-  const ext = EXTENSIONS[extensionKey as keyof typeof EXTENSIONS];
+  const response = await prompts([
+    {
+      type: 'text',
+      name: 'name',
+      message: 'Extension name (e.g., "leads", "payments"):',
+      validate: (value: string) => {
+        if (!value) return 'Extension name is required';
+        if (!/^[a-z][a-z0-9-]*$/.test(value)) {
+          return 'Extension name must start with a letter and contain only lowercase letters, numbers, and hyphens';
+        }
+        return true;
+      },
+    },
+    {
+      type: 'text',
+      name: 'displayName',
+      message: 'Display name (e.g., "Leads & Forms"):',
+      validate: (value: string) => value ? true : 'Display name is required',
+    },
+    {
+      type: 'text',
+      name: 'description',
+      message: 'Description:',
+      validate: (value: string) => value ? true : 'Description is required',
+    },
+    {
+      type: 'text',
+      name: 'icon',
+      message: 'Lucide icon name (e.g., "Mail", "CreditCard"):',
+      initial: 'Package',
+    },
+    {
+      type: 'select',
+      name: 'category',
+      message: 'Category:',
+      choices: EXTENSION_CATEGORIES,
+    },
+  ]);
 
-  if (!ext) {
-    consola.error(`Extension not found: ${extensionKey}`);
-    consola.info('Run `djangocfg-ext list` to see available extensions');
+  if (!response.name) {
+    consola.info('Extension creation cancelled');
     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,
-    })),
-  });
+  const extName = `ext-${response.name}`;
+  const extDir = join(process.cwd(), 'extensions', extName);
 
-  if (!response.extension) {
-    consola.info('Installation cancelled');
+  // Check if extension already exists
+  if (existsSync(extDir)) {
+    consola.error(`Extension already exists: ${extDir}`);
     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();
+  consola.start(`Creating extension: ${chalk.cyan(`@djangocfg/${extName}`)}`);
 
-  console.log(chalk.yellow.bold('Then import in your app:'));
-  console.log(chalk.gray(`  import { ExtensionProvider } from '${ext.name}';`));
-  console.log();
+  try {
+    const providerName = response.displayName.replace(/[^a-zA-Z]/g, '');
+
+    // Prepare replacements
+    const replacements = {
+      '__NAME__': response.name,
+      '__DISPLAY_NAME__': response.displayName,
+      '__DESCRIPTION__': response.description,
+      '__ICON__': response.icon,
+      '__CATEGORY__': response.category,
+      '__PROVIDER_NAME__': providerName,
+    };
+
+    // Find template directory
+    const templatePaths = [
+      // When installed from npm
+      join(__dirname, '../templates/extension-template'),
+      // Workspace path (for development)
+      join(process.cwd(), 'extensions', 'ext-base', 'templates', 'extension-template'),
+    ];
+
+    let templateDir: string | null = null;
+    for (const path of templatePaths) {
+      if (existsSync(path)) {
+        templateDir = path;
+        break;
+      }
+    }
 
-  consola.success('See documentation at https://djangocfg.com/docs');
-}
+    if (!templateDir) {
+      throw new Error('Extension template not found');
+    }
 
-// Init extension in project
-async function initExtension() {
-  printBanner();
+    // Copy template with replacements
+    consola.start('Copying template files...');
+    copyTemplateRecursive(templateDir, extDir, replacements);
+    consola.success('Extension files created');
 
-  console.log(chalk.yellow('This will create extension configuration in your project'));
-  console.log();
+    console.log();
+    consola.success(`Extension created successfully: ${chalk.cyan(extDir)}`);
+    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,
-    },
-  ]);
+    console.log(chalk.yellow.bold('Next steps:'));
+    console.log();
+    console.log(chalk.gray('1. Install dependencies:'));
+    console.log(chalk.cyan(`   cd ${extDir} && pnpm install`));
+    console.log();
+    console.log(chalk.gray('2. Build the extension:'));
+    console.log(chalk.cyan(`   pnpm build`));
+    console.log();
+    console.log(chalk.gray('3. Add your features and customize:'));
+    console.log(chalk.cyan(`   - Edit src/config.ts to add features`));
+    console.log(chalk.cyan(`   - Add components, hooks, and utilities`));
+    console.log(chalk.cyan(`   - Update README.md with usage examples`));
+    console.log();
 
-  if (!response.confirm) {
-    consola.info('Initialization cancelled');
-    return;
+    consola.info('Documentation: https://djangocfg.com/docs');
+  } catch (error) {
+    consola.error('Failed to create extension:', error);
+    process.exit(1);
   }
-
-  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
@@ -235,26 +250,8 @@ async function main() {
 
   // 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();
+    case 'create':
+      await createExtension();
       break;
 
     case 'help':

package/src/config.ts

@@ -0,0 +1,17 @@
+/**
+ * Extension configuration and environment utilities
+ */
+
+export const isDevelopment = process.env.NODE_ENV === 'development';
+export const isProduction = process.env.NODE_ENV === 'production';
+export const isStaticBuild = process.env.STATIC_BUILD === 'true';
+
+/**
+ * Get API URL from environment or default
+ */
+export function getApiUrl(): string {
+  return process.env.NEXT_PUBLIC_API_URL || '/api';
+}
+
+// Re-export metadata
+export * from './metadata';

package/src/index.ts

@@ -5,8 +5,9 @@
  * Server-safe entry point - can be used in both server and client components.
  */
 
-// Types
+// Types & Constants
 export type * from './types';
+export { EXTENSION_CATEGORIES } from './types/context';
 
 // Config
 export * from './config';