@djangocfg/ext-base 1.0.0 → 1.0.2

package/src/cli/index.ts

@@ -0,0 +1,274 @@
+/**
+ * DjangoCFG Extension CLI
+ *
+ * Interactive CLI for managing DjangoCFG extensions
+ */
+
+import { consola } from 'consola';
+import chalk from 'chalk';
+import prompts from 'prompts';
+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));
+
+// 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 = {
+  create: 'Create a new DjangoCFG extension',
+  help: 'Show help',
+  '--help': 'Show help',
+  '-h': 'Show help',
+} as const;
+
+type Command = keyof typeof COMMANDS;
+
+// 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() {
+  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 create')}`);
+  console.log();
+}
+
+// Create new extension
+async function createExtension() {
+  printBanner();
+
+  console.log(chalk.yellow('Create a new DjangoCFG extension'));
+  console.log();
+
+  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 (!response.name) {
+    consola.info('Extension creation cancelled');
+    return;
+  }
+
+  const extName = `ext-${response.name}`;
+  const extDir = join(process.cwd(), 'extensions', extName);
+
+  // Check if extension already exists
+  if (existsSync(extDir)) {
+    consola.error(`Extension already exists: ${extDir}`);
+    return;
+  }
+
+  console.log();
+  consola.start(`Creating extension: ${chalk.cyan(`@djangocfg/${extName}`)}`);
+
+  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;
+      }
+    }
+
+    if (!templateDir) {
+      throw new Error('Extension template not found');
+    }
+
+    // Copy template with replacements
+    consola.start('Copying template files...');
+    copyTemplateRecursive(templateDir, extDir, replacements);
+    consola.success('Extension files created');
+
+    console.log();
+    consola.success(`Extension created successfully: ${chalk.cyan(extDir)}`);
+    console.log();
+
+    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();
+
+    consola.info('Documentation: https://djangocfg.com/docs');
+  } catch (error) {
+    consola.error('Failed to create extension:', error);
+    process.exit(1);
+  }
+}
+
+// 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 'create':
+      await createExtension();
+      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);
+});

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';

package/src/metadata.ts

@@ -0,0 +1,73 @@
+/**
+ * Extension Base configuration
+ */
+
+import type { ExtensionMetadata } from './types';
+import packageJson from '../package.json';
+
+export const extensionConfig: ExtensionMetadata = {
+  name: 'base',
+  version: packageJson.version,
+  author: 'DjangoCFG Team',
+  displayName: 'Extension Base',
+  description: 'Base utilities and common code for building DjangoCFG extensions. Includes CLI tool for managing extensions.',
+  icon: 'Wrench',
+  license: 'MIT',
+  githubUrl: 'https://github.com/markolofsen/django-cfg',
+  homepage: 'https://djangocfg.com',
+  keywords: ['base', 'utilities', 'cli', 'toolkit', 'helpers', 'hooks'],
+
+  // Marketplace metadata
+  category: 'utilities',
+  tags: ['base', 'utilities', 'cli', 'toolkit'],
+  features: [
+    'Extension registration system',
+    'React hooks for pagination and infinite scroll',
+    'Environment utilities and helpers',
+    'CLI tool for extension management',
+    'Type-safe context helpers',
+    'Logger utilities',
+  ],
+  npmUrl: `https://www.npmjs.com/package/${packageJson.name}`,
+  installCommand: `pnpm add ${packageJson.name}`,
+  peerDependencies: packageJson.peerDependencies,
+  examples: [
+    {
+      title: 'Basic Extension Setup',
+      description: 'Initialize a new DjangoCFG extension',
+      code: `import { createExtension } from '@djangocfg/ext-base';
+
+const myExtension = createExtension({
+  name: 'my-extension',
+  version: '1.0.0',
+  register: (app) => {
+    console.log('Extension registered!');
+  },
+});
+
+export default myExtension;`,
+      language: 'typescript',
+    },
+    {
+      title: 'Using Pagination Hook',
+      description: 'Implement infinite scroll with usePagination',
+      code: `import { usePagination } from '@djangocfg/ext-base';
+
+function DataList() {
+  const { data, loading, hasMore, loadMore } = usePagination({
+    fetchFn: (page) => fetch(\`/api/data?page=\${page}\`),
+    pageSize: 20,
+  });
+
+  return (
+    <div>
+      {data.map(item => <div key={item.id}>{item.name}</div>)}
+      {hasMore && <button onClick={loadMore}>Load More</button>}
+    </div>
+  );
+}`,
+      language: 'tsx',
+    },
+  ],
+  githubStars: 245,
+};

package/src/types/context.ts

@@ -10,6 +10,60 @@ export interface ExtensionContextOptions {
   revalidateIfStale?: boolean;
 }
 
+/**
+ * Extension category types
+ */
+export type ExtensionCategory =
+  | 'forms'       // Forms, CRM, Lead Management
+  | 'payments'    // Payment Processing, Billing
+  | 'content'     // Content Management, Marketing
+  | 'support'     // Support, Helpdesk, Tickets
+  | 'utilities'   // Tools, Base, Infrastructure
+  | 'analytics'   // Analytics, Tracking, Monitoring
+  | 'security'    // Security, Authentication, Authorization
+  | 'integration' // Third-party Integrations
+  | 'other';      // Other/Uncategorized
+
+/**
+ * Extension categories with display names for CLI and UI
+ */
+export const EXTENSION_CATEGORIES: Array<{ title: string; value: ExtensionCategory }> = [
+  { title: 'Forms', value: 'forms' },
+  { title: 'Payments', value: 'payments' },
+  { title: 'Content', value: 'content' },
+  { title: 'Support', value: 'support' },
+  { title: 'Utilities', value: 'utilities' },
+  { title: 'Analytics', value: 'analytics' },
+  { title: 'Security', value: 'security' },
+  { title: 'Integration', value: 'integration' },
+  { title: 'Other', value: 'other' },
+];
+
+/**
+ * Code example for extension documentation
+ */
+export interface ExtensionExample {
+  /**
+   * Example title
+   */
+  title: string;
+
+  /**
+   * Example description
+   */
+  description?: string;
+
+  /**
+   * Code snippet
+   */
+  code: string;
+
+  /**
+   * Programming language for syntax highlighting
+   */
+  language: string;
+}
+
 export interface ExtensionMetadata {
   /**
    * Unique extension name (e.g., 'newsletter', 'payments')
@@ -58,13 +112,13 @@ export interface ExtensionMetadata {
   keywords?: string[];
 
   /**
-   * Extension icon URL or emoji
-   * @example '📧' or 'https://example.com/icon.png'
+   * Extension icon - Lucide icon name or emoji
+   * @example 'Mail' or '📧'
    */
   icon?: string;
 
   /**
-   * List of extension dependencies
+   * List of extension dependencies (other extension names)
    * @example ['payments', 'auth']
    */
   dependencies?: string[];
@@ -73,6 +127,73 @@ export interface ExtensionMetadata {
    * Minimum required DjangoCFG version
    */
   minVersion?: string;
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // Marketplace-specific fields
+  // ─────────────────────────────────────────────────────────────────────────
+
+  /**
+   * Extension category for marketplace organization
+   */
+  category?: ExtensionCategory;
+
+  /**
+   * Tags for search and filtering
+   */
+  tags?: string[];
+
+  /**
+   * List of key features
+   */
+  features?: string[];
+
+  /**
+   * npm package URL
+   * @example 'https://www.npmjs.com/package/@djangocfg/ext-newsletter'
+   */
+  npmUrl?: string;
+
+  /**
+   * Installation command
+   * @example 'pnpm add @djangocfg/ext-newsletter'
+   */
+  installCommand?: string;
+
+  /**
+   * Code examples for documentation
+   */
+  examples?: ExtensionExample[];
+
+  /**
+   * npm package dependencies
+   */
+  packageDependencies?: Record<string, string>;
+
+  /**
+   * npm peer dependencies
+   */
+  peerDependencies?: Record<string, string>;
+
+  /**
+   * Related extension IDs
+   */
+  relatedExtensions?: string[];
+
+  /**
+   * README content in markdown
+   */
+  readme?: string;
+
+  /**
+   * Preview image URL (1200x630 recommended)
+   * @example 'https://unpkg.com/@djangocfg/ext-leads@latest/preview.svg'
+   */
+  preview?: string;
+
+  /**
+   * GitHub stars count
+   */
+  githubStars?: number;
 }
 
 export interface ExtensionProviderProps {

package/src/utils/createExtensionConfig.ts

@@ -0,0 +1,139 @@
+/**
+ * Helper to create extension configuration from package.json
+ */
+
+import type { ExtensionMetadata } from '../types';
+
+/**
+ * Package.json structure
+ */
+interface PackageJson {
+  name: string;
+  version: string;
+  description?: string;
+  keywords?: string[];
+  author?: string | { name: string; email?: string; url?: string };
+  license?: string;
+  homepage?: string;
+  repository?: string | { type: string; url: string; directory?: string };
+  peerDependencies?: Record<string, string>;
+  dependencies?: Record<string, string>;
+}
+
+/**
+ * Manual metadata fields that must be provided
+ */
+export interface ExtensionConfigInput {
+  /**
+   * Extension short name (e.g., 'leads', 'payments')
+   */
+  name: string;
+
+  /**
+   * Display name for marketplace
+   */
+  displayName: string;
+
+  /**
+   * Lucide icon name
+   * @example 'FileText', 'CreditCard', 'Mail'
+   */
+  icon: string;
+
+  /**
+   * Extension category
+   */
+  category: ExtensionMetadata['category'];
+
+  /**
+   * Key features list
+   */
+  features: string[];
+
+  /**
+   * Code examples (optional)
+   */
+  examples?: ExtensionMetadata['examples'];
+
+  /**
+   * Minimum required DjangoCFG version (optional)
+   */
+  minVersion?: string;
+
+  /**
+   * Related extension IDs (optional)
+   */
+  relatedExtensions?: string[];
+
+  /**
+   * GitHub stars count (optional)
+   */
+  githubStars?: number;
+}
+
+/**
+ * Create extension configuration from package.json + manual metadata
+ *
+ * @example
+ * ```ts
+ * import packageJson from '../package.json';
+ * import { createExtensionConfig } from '@djangocfg/ext-base';
+ *
+ * export const extensionConfig = createExtensionConfig(packageJson, {
+ *   name: 'leads',
+ *   displayName: 'Leads & Forms',
+ *   icon: 'FileText',
+ *   category: 'forms',
+ *   features: [
+ *     'Contact form components',
+ *     'Lead tracking',
+ *   ],
+ * });
+ * ```
+ */
+export function createExtensionConfig(
+  packageJson: PackageJson,
+  config: ExtensionConfigInput
+): ExtensionMetadata {
+  // Extract author name
+  const author = typeof packageJson.author === 'string'
+    ? packageJson.author
+    : packageJson.author?.name || 'Unknown';
+
+  // Extract repository URL
+  const githubUrl = typeof packageJson.repository === 'string'
+    ? packageJson.repository
+    : packageJson.repository?.url;
+
+  return {
+    // From package.json
+    name: config.name,
+    version: packageJson.version,
+    author,
+    description: packageJson.description,
+    keywords: packageJson.keywords,
+    license: packageJson.license,
+    homepage: packageJson.homepage,
+    githubUrl,
+    peerDependencies: packageJson.peerDependencies,
+
+    // From manual config
+    displayName: config.displayName,
+    icon: config.icon,
+    category: config.category,
+    features: config.features,
+    examples: config.examples,
+    minVersion: config.minVersion,
+    relatedExtensions: config.relatedExtensions,
+    githubStars: config.githubStars,
+
+    // Auto-generated
+    npmUrl: `https://www.npmjs.com/package/${packageJson.name}`,
+    installCommand: `pnpm add ${packageJson.name}`,
+    tags: packageJson.keywords,
+    preview: `https://unpkg.com/${packageJson.name}@latest/preview.png`,
+
+    // Dependencies (empty by default, can be set via keywords)
+    dependencies: [],
+  };
+}

package/src/utils/index.ts

@@ -8,3 +8,8 @@ export {
   formatErrorMessage,
   handleExtensionError,
 } from './errors';
+
+export {
+  createExtensionConfig,
+  type ExtensionConfigInput,
+} from './createExtensionConfig';