@nexical/cli 0.11.23 → 0.12.0

package/src/deploy/providers/cloudflare.ts

@@ -1,74 +1,130 @@
+import path from 'node:path';
 import { logger } from '@nexical/cli-core';
-import { DeploymentProvider, DeploymentContext, CIConfig } from '../types';
+import { HostingProvider, DeploymentContext, CIConfig, AppConfig } from '../types';
 import { execAsync } from '../utils';
 
-export class CloudflareProvider implements DeploymentProvider {
+export interface CloudflareConfig {
+  token?: string;
+  account?: string;
+}
+
+export class CloudflareProvider implements HostingProvider {
   name = 'cloudflare';
-  type = 'frontend' as const;
 
-  async provision(context: DeploymentContext): Promise<void> {
+  async provision(context: DeploymentContext, app: AppConfig): Promise<void> {
     const env = (context.options.env as string) || 'production';
-    const baseProjectName = context.config.deploy?.frontend?.projectName;
+    const baseProjectName = app.projectName;
 
     if (!baseProjectName) {
       throw new Error(
-        "Cloudflare project name not found in nexical.yaml. Please configure 'deploy.frontend.projectName'.",
+        `Cloudflare project name not found for ${app.name}. Please configure 'projectName'.`,
       );
     }
 
     const projectName = env === 'production' ? baseProjectName : `${baseProjectName}-${env}`;
 
-    const options = context.config.deploy?.frontend?.options || {};
-
-    // Resolve credentials:
-    // 1. CLI flag (options)
-    // 2. Env var defined in config (options.apiTokenEnvVar)
-    // 3. Default env var (CLOUDFLARE_API_TOKEN)
-    const apiTokenEnvVar =
-      typeof options.apiTokenEnvVar === 'string' ? options.apiTokenEnvVar : undefined;
-    const apiToken =
-      (typeof context.options.cloudflareToken === 'string'
-        ? context.options.cloudflareToken
-        : undefined) ||
-      (apiTokenEnvVar ? process.env[apiTokenEnvVar] : undefined) ||
-      process.env.CLOUDFLARE_API_TOKEN;
-
-    const accountIdEnvVar =
-      typeof options.accountIdEnvVar === 'string' ? options.accountIdEnvVar : undefined;
-    const accountId =
-      (typeof context.options.cloudflareAccount === 'string'
-        ? context.options.cloudflareAccount
-        : undefined) ||
-      (accountIdEnvVar ? process.env[accountIdEnvVar] : undefined) ||
-      process.env.CLOUDFLARE_ACCOUNT_ID;
-
-    logger.info('Configuring Cloudflare Pages...');
+    logger.info(`Configuring Cloudflare Pages for ${app.name}...`);
 
     if (context.options.dryRun) {
       logger.info(
-        `[Dry Run] Would check Cloudflare Pages project "${projectName}" and create if missing.`,
+        `[Dry Run] Would check Cloudflare status and provision project "${projectName}".`,
       );
       return;
     }
 
-    if (!apiToken || !accountId) {
-      logger.warn('Cloudflare credentials missing. Skipping automated Cloudflare setup.');
-      logger.info('You can manually set up Cloudflare Pages and add the secrets to GitHub.');
-      return;
-    }
-
     try {
+      const secrets = await this.getSecrets(context, app).catch(() => undefined);
+      if (!secrets) {
+        logger.warn(
+          `Cloudflare credentials missing for ${app.name}. Skipping provisioning. ` +
+            'Ensure CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID are set.',
+        );
+        return;
+      }
+
+      const processEnv = {
+        ...process.env,
+        ...secrets,
+        NODE_OPTIONS: `${process.env.NODE_OPTIONS || ''} --dns-result-order=ipv4first`.trim(),
+      };
       logger.info(`Ensuring Cloudflare Pages project "${projectName}" exists...`);
       try {
         await execAsync(`wrangler pages project create ${projectName} --production-branch main`, {
-          env: {
-            ...process.env,
-            CLOUDFLARE_API_TOKEN: apiToken,
-            CLOUDFLARE_ACCOUNT_ID: accountId,
-          },
+          env: processEnv,
         });
-      } catch {
-        logger.info('Cloudflare project might already exist.');
+      } catch (err: unknown) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (message.includes('already exists')) {
+          logger.info('Cloudflare project already exists.');
+        } else {
+          throw err;
+        }
+      }
+
+      // Handle Linked Domains
+      if (app.domain) {
+        const domains = Array.isArray(app.domain) ? app.domain : [app.domain];
+        logger.info(
+          `Linking ${domains.length} domains to Cloudflare Pages project "${projectName}"...`,
+        );
+
+        const apiToken = secrets.CLOUDFLARE_API_TOKEN;
+        const accountId = secrets.CLOUDFLARE_ACCOUNT_ID;
+
+        // Fetch existing domains to avoid redundant calls
+        const listRes = await fetch(
+          `https://api.cloudflare.com/client/v4/accounts/${accountId}/pages/projects/${projectName}/domains`,
+          {
+            headers: {
+              Authorization: `Bearer ${apiToken}`,
+              'Content-Type': 'application/json',
+            },
+          },
+        );
+
+        if (!listRes.ok) {
+          const errorText = await listRes.text();
+          logger.warn(`Failed to fetch existing linked domains: ${errorText}`);
+        } else {
+          const listJson = (await listRes.json()) as {
+            success: boolean;
+            result: { domain: string }[];
+          };
+          const existingDomains = listJson.success ? listJson.result.map((d) => d.domain) : [];
+
+          for (const domain of domains) {
+            if (existingDomains.includes(domain)) {
+              logger.info(`[Cloudflare Pages] Domain ${domain} is already linked.`);
+              continue;
+            }
+
+            logger.info(`[Cloudflare Pages] Linking domain ${domain}...`);
+            const linkRes = await fetch(
+              `https://api.cloudflare.com/client/v4/accounts/${accountId}/pages/projects/${projectName}/domains`,
+              {
+                method: 'POST',
+                headers: {
+                  Authorization: `Bearer ${apiToken}`,
+                  'Content-Type': 'application/json',
+                },
+                body: JSON.stringify({ name: domain }), // Pages API uses 'name' for the domain string in some versions, but docs suggest 'name' or just object. Let's verify 'name' vs 'domain'.
+                // Correction: The API docs say POST body should be { "name": "example.com" }
+              },
+            );
+
+            if (!linkRes.ok) {
+              const errorText = await linkRes.text();
+              // If it failed because it exists but wasn't in list (unlikely but safe)
+              if (errorText.includes('already exists') || errorText.includes('1008')) {
+                logger.info(`[Cloudflare Pages] Domain ${domain} already linked.`);
+              } else {
+                logger.warn(`[Cloudflare Pages] Failed to link domain ${domain}: ${errorText}`);
+              }
+            } else {
+              logger.success(`[Cloudflare Pages] Linked domain ${domain}.`);
+            }
+          }
+        }
       }
     } catch (e: unknown) {
       logger.warn('Cloudflare setup failed.');
@@ -76,76 +132,143 @@ export class CloudflareProvider implements DeploymentProvider {
     }
   }
 
-  async getSecrets(context: DeploymentContext): Promise<Record<string, string>> {
-    const options = context.config.deploy?.frontend?.options || {};
-    const secrets: Record<string, string> = {};
+  async getSecrets(context: DeploymentContext, app: AppConfig): Promise<Record<string, string>> {
+    const cfConfig = (app.cloudflare as CloudflareConfig) || {};
+    const apiTokenEnvVar = cfConfig.token;
+    const accountIdEnvVar = cfConfig.account;
 
-    // Resolve API Token
-    const apiTokenEnvVar =
-      typeof options.apiTokenEnvVar === 'string' ? options.apiTokenEnvVar : undefined;
     const apiToken =
-      (apiTokenEnvVar ? process.env[apiTokenEnvVar] : undefined) ||
-      process.env.CLOUDFLARE_API_TOKEN;
+      process.env.CLOUDFLARE_API_TOKEN?.trim() ||
+      (apiTokenEnvVar ? process.env[apiTokenEnvVar]?.trim() : undefined);
+    const accountId =
+      process.env.CLOUDFLARE_ACCOUNT_ID?.trim() ||
+      (accountIdEnvVar ? process.env[accountIdEnvVar]?.trim() : undefined);
 
     if (!apiToken) {
       throw new Error(
-        `Cloudflare API Token not found. Please provide it via:\n` +
-          `1. Configuring 'deploy.frontend.options.apiTokenEnvVar' in nexical.yaml and setting that env var in .env\n` +
-          `2. Setting CLOUDFLARE_API_TOKEN in .env`,
+        `Cloudflare API Token not found for ${app.name}. Please provide it via:\n` +
+          `1. Setting CLOUDFLARE_API_TOKEN in .env (Recommended)\n` +
+          `2. Configuring 'cloudflare.token' and setting that env var in .env`,
       );
     }
-    secrets['CLOUDFLARE_API_TOKEN'] = apiToken;
-
-    // Resolve Account ID
-    const accountIdEnvVar =
-      typeof options.accountIdEnvVar === 'string' ? options.accountIdEnvVar : undefined;
-    const accountId =
-      (accountIdEnvVar ? process.env[accountIdEnvVar] : undefined) ||
-      process.env.CLOUDFLARE_ACCOUNT_ID;
 
     if (!accountId) {
       throw new Error(
-        `Cloudflare Account ID not found. Please provide it via:\n` +
-          `1. Configuring 'deploy.frontend.options.accountIdEnvVar' in nexical.yaml and setting that env var in .env\n` +
-          `2. Setting CLOUDFLARE_ACCOUNT_ID in .env`,
+        `Cloudflare Account ID not found for ${app.name}. Please provide it via:\n` +
+          `1. Setting CLOUDFLARE_ACCOUNT_ID in .env (Recommended)\n` +
+          `2. Configuring 'cloudflare.account' and setting that env var in .env`,
       );
     }
-    secrets['CLOUDFLARE_ACCOUNT_ID'] = accountId;
+
+    const secrets: Record<string, string> = {
+      CLOUDFLARE_API_TOKEN: apiToken,
+      CLOUDFLARE_ACCOUNT_ID: accountId,
+    };
+
+    // Custom mapped secrets
+    if (app.secrets) {
+      for (const [key, envVar] of Object.entries(app.secrets)) {
+        const value = process.env[envVar];
+        if (!value) {
+          throw new Error(`Custom secret '${key}' mapping failed: Env var '${envVar}' not found.`);
+        }
+        secrets[key] = value;
+      }
+    }
 
     return secrets;
   }
 
-  async getVariables(context: DeploymentContext): Promise<Record<string, string>> {
+  async getVariables(context: DeploymentContext, app: AppConfig): Promise<Record<string, string>> {
     const env = (context.options.env as string) || 'production';
-    const baseProjectName = context.config.deploy?.frontend?.projectName;
+    const baseProjectName = app.projectName;
 
     if (!baseProjectName) {
-      throw new Error(
-        "Cloudflare project name not found in nexical.yaml. Please configure 'deploy.frontend.projectName'.",
-      );
+      throw new Error(`Cloudflare project name not found for ${app.name}.`);
     }
 
     const projectName = env === 'production' ? baseProjectName : `${baseProjectName}-${env}`;
-    return {
-      CLOUDFLARE_PROJECT_NAME: projectName,
+    const varName = `CLOUDFLARE_PROJECT_NAME_${app.name.toUpperCase().replace(/-/g, '_')}`;
+    const result: Record<string, string> = {
+      [varName]: projectName,
     };
+
+    // Custom mapped variables
+    if (app.env) {
+      for (const [key, value] of Object.entries(app.env)) {
+        // If it looks like an env var, try to resolve it, otherwise use literal
+        const resolvedValue = process.env[value] || value;
+        result[key] = resolvedValue;
+      }
+    }
+
+    return result;
   }
 
-  getCIConfig(): CIConfig {
+  getCIConfig(repoType: 'github' | 'gitlab', app: AppConfig): CIConfig {
+    const varName = `CLOUDFLARE_PROJECT_NAME_${app.name.toUpperCase().replace(/-/g, '_')}`;
+    const artifactPath = app.artifactPath || 'dist';
     return {
       secrets: ['CLOUDFLARE_API_TOKEN', 'CLOUDFLARE_ACCOUNT_ID'],
-      variables: ['CLOUDFLARE_PROJECT_NAME'],
+      variables: [varName],
       deploySteps: [], // Handled by action
       githubActionStep: {
-        name: 'Deploy to Cloudflare Pages',
+        name: `Deploy ${app.name} to Cloudflare Pages`,
         uses: 'cloudflare/wrangler-action@v3',
         with: {
           apiToken: '${{ secrets.CLOUDFLARE_API_TOKEN }}',
           accountId: '${{ secrets.CLOUDFLARE_ACCOUNT_ID }}',
-          command: 'pages deploy dist --project-name=${{ vars.CLOUDFLARE_PROJECT_NAME }}',
-          workingDirectory: 'apps/frontend',
+          command: `pages deploy ${artifactPath} --project-name=\${{ vars.${varName} }}`,
+          workingDirectory: app.target || '.',
         },
       },
     };
   }
+
+  async deploy(context: DeploymentContext, app: AppConfig): Promise<void> {
+    const env = (context.options.env as string) || 'production';
+    const baseProjectName = app.projectName;
+    const artifactPath = app.artifactPath || 'dist';
+    const targetDir = app.target ? path.resolve(context.cwd, app.target) : context.cwd;
+
+    if (!baseProjectName) {
+      throw new Error(`Cloudflare project name not found for ${app.name}.`);
+    }
+
+    const projectName = env === 'production' ? baseProjectName : `${baseProjectName}-${env}`;
+
+    logger.info(`Deploying ${app.name} to Cloudflare Pages project "${projectName}"...`);
+
+    if (context.options.dryRun) {
+      logger.info(
+        `[Dry Run] Would deploy directory "${artifactPath}" to Cloudflare project "${projectName}".`,
+      );
+      return;
+    }
+
+    const secrets = await this.getSecrets(context, app);
+    const processEnv = {
+      ...process.env,
+      ...secrets,
+      NODE_OPTIONS: `${process.env.NODE_OPTIONS || ''} --dns-result-order=ipv4first`.trim(),
+    };
+
+    await execAsync(`wrangler pages deploy ${artifactPath} --project-name=${projectName}`, {
+      cwd: targetDir,
+      env: processEnv,
+    });
+
+    logger.success(`Successfully deployed ${app.name} to Cloudflare Pages.`);
+  }
+
+  getDefaultDnsTarget(app: AppConfig): string | undefined {
+    // Cloudflare pages gives a predictable .pages.dev alias
+    // Note: This does not take environment into account for custom domains usually,
+    // custom domains are typically linked to the production project alias or a specific branch alias.
+    // For standard custom domain linkage, we return the production project alias.
+    if (app.projectName) {
+      return `${app.projectName}.pages.dev`;
+    }
+    return undefined;
+  }
 }

package/src/deploy/providers/dns-cloudflare.ts

@@ -0,0 +1,134 @@
+import { logger } from '@nexical/cli-core';
+import { DnsProvider, DeploymentContext, DnsRecord } from '../types';
+
+export class CloudflareDnsProvider implements DnsProvider {
+  name = 'cloudflare';
+  type = 'dns' as const;
+
+  async provision(context: DeploymentContext, records: DnsRecord[]): Promise<void> {
+    const dnsConfig = context.config.deploy?.dns;
+
+    // Cloudflare specific token handling
+    const cfConfig = dnsConfig?.cloudflare as { token?: string; zone?: string } | undefined;
+    const apiToken = process.env.CLOUDFLARE_API_TOKEN || cfConfig?.token;
+    const zoneId = process.env.CLOUDFLARE_ZONE_ID || cfConfig?.zone;
+
+    if (!apiToken) {
+      throw new Error(
+        'Cloudflare API token not found. Set CLOUDFLARE_API_TOKEN environment variable or deploy.dns.cloudflare.token in nexical.yaml',
+      );
+    }
+    if (!zoneId) {
+      throw new Error(
+        'Cloudflare Zone ID not found. Set CLOUDFLARE_ZONE_ID environment variable or deploy.dns.cloudflare.zone in nexical.yaml',
+      );
+    }
+
+    if (records.length === 0) {
+      logger.info(`[Cloudflare DNS] No DNS records to provision.`);
+      return;
+    }
+
+    logger.info(`[Cloudflare DNS] Provisioning ${records.length} records...`);
+
+    if (context.options.dryRun) {
+      for (const record of records) {
+        logger.info(
+          `[Dry Run] Would create/update DNS record: ${record.name} -> ${record.content} (${record.type})`,
+        );
+      }
+      return;
+    }
+
+    // Fetch existing records for this zone to avoid creating duplicates
+    const response = await fetch(
+      `https://api.cloudflare.com/client/v4/zones/${zoneId}/dns_records`,
+      {
+        headers: {
+          Authorization: `Bearer ${apiToken}`,
+          'Content-Type': 'application/json',
+        },
+      },
+    );
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      throw new Error(
+        `Failed to fetch Cloudflare DNS records: ${response.status} ${response.statusText} - ${errorText}`,
+      );
+    }
+
+    const jsonRes = (await response.json()) as {
+      success: boolean;
+      result: { id: string; type: string; name: string; content: string; proxied: boolean }[];
+    };
+
+    if (!jsonRes.success) {
+      throw new Error('Cloudflare API returned success: false when fetching DNS records.');
+    }
+
+    const existingRecords = jsonRes.result || [];
+
+    for (const record of records) {
+      // Find matching record by name and type
+      const match = existingRecords.find((r) => r.name === record.name && r.type === record.type);
+
+      const payload = {
+        type: record.type,
+        name: record.name,
+        content: record.content,
+        proxied: record.proxied ?? true, // Default to proxied for Cloudflare
+        ttl: 1, // Automatic
+      };
+
+      if (match) {
+        // Update if content or proxied status differs
+        if (match.content !== record.content || match.proxied !== payload.proxied) {
+          logger.info(
+            `[Cloudflare DNS] Updating ${record.name} (${record.type}) -> ${record.content}`,
+          );
+          const updateRes = await fetch(
+            `https://api.cloudflare.com/client/v4/zones/${zoneId}/dns_records/${match.id}`,
+            {
+              method: 'PUT',
+              headers: {
+                Authorization: `Bearer ${apiToken}`,
+                'Content-Type': 'application/json',
+              },
+              body: JSON.stringify(payload),
+            },
+          );
+          if (!updateRes.ok) {
+            const errorText = await updateRes.text();
+            throw new Error(`Failed to update DNS record ${record.name}: ${errorText}`);
+          }
+        } else {
+          logger.info(`[Cloudflare DNS] Record ${record.name} is already up to date.`);
+        }
+      } else {
+        // Create new record
+        logger.info(
+          `[Cloudflare DNS] Creating ${record.name} (${record.type}) -> ${record.content}`,
+        );
+        const createRes = await fetch(
+          `https://api.cloudflare.com/client/v4/zones/${zoneId}/dns_records`,
+          {
+            method: 'POST',
+            headers: {
+              Authorization: `Bearer ${apiToken}`,
+              'Content-Type': 'application/json',
+            },
+            body: JSON.stringify(payload),
+          },
+        );
+        if (!createRes.ok) {
+          const errorText = await createRes.text();
+          throw new Error(`Failed to create DNS record ${record.name}: ${errorText}`);
+        }
+      }
+    }
+    logger.success(`[Cloudflare DNS] Finished provisioning DNS records.`);
+  }
+}
+
+export default CloudflareDnsProvider;

package/src/deploy/providers/github.ts

@@ -2,11 +2,13 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 import YAML from 'yaml';
 import { logger } from '@nexical/cli-core';
-import { RepositoryProvider, DeploymentContext, DeploymentProvider } from '../types';
+import { RepositoryProvider, DeploymentContext, HostingProvider, AppConfig } from '../types';
 import { execAsync } from '../utils';
+import { TemplateManager } from '../template-manager';
 
 export class GitHubProvider implements RepositoryProvider {
   name = 'github';
+  private templateManager = new TemplateManager();
 
   async configureSecrets(
     context: DeploymentContext,
@@ -38,58 +40,48 @@ export class GitHubProvider implements RepositoryProvider {
     }
   }
 
-  async generateWorkflow(context: DeploymentContext, targets: DeploymentProvider[]): Promise<void> {
+  async generateWorkflow(
+    context: DeploymentContext,
+    targets: { provider: HostingProvider; app: AppConfig }[],
+  ): Promise<void> {
     const workflowsDir = path.join(context.cwd, '.github/workflows');
     await fs.mkdir(workflowsDir, { recursive: true });
 
-    for (const target of targets) {
-      const config = target.getCIConfig('github');
+    for (const { provider, app } of targets) {
+      const config = provider.getCIConfig('github', app);
       if (!config) continue;
 
-      const filename = `deploy-${target.type}.yml`;
+      const filename = `deploy-${app.name}.yml`;
       const filepath = path.join(workflowsDir, filename);
 
-      const workflow: Record<string, unknown> = {
-        name: `Deploy ${target.type === 'backend' ? 'Backend' : 'Frontend'} to ${target.name}`,
-        on: {
-          push: { branches: ['main'] },
-          workflow_dispatch: {},
-        },
-        jobs: {
-          deploy: {
-            'runs-on': 'ubuntu-latest',
-            permissions: {
-              contents: 'read',
-              deployments: 'write',
-            },
-            steps: [
-              {
-                name: 'Checkout',
-                uses: 'actions/checkout@v4',
-                with: { submodules: 'recursive' },
-              },
-              {
-                name: 'Setup Node',
-                uses: 'actions/setup-node@v4',
-                with: { 'node-version': 20, cache: 'npm' },
-              },
-              {
-                name: 'Install Dependencies',
-                run: 'npm ci',
-              },
-            ],
-          },
-        },
-      };
+      const workflow = await this.templateManager.loadWorkflow('github-workflow', {
+        APP_NAME: app.name,
+        PROVIDER_NAME: provider.name,
+      });
+
+      // Update push trigger if paths are specified
+      if (app.paths && app.paths.length > 0) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const workflowAny = workflow as any;
+        if (typeof workflowAny.on === 'string') {
+          workflowAny.on = {
+            push: { branches: [workflowAny.on] },
+          };
+        }
+        if (!workflowAny.on.push) {
+          workflowAny.on.push = { branches: ['main'] };
+        }
+        workflowAny.on.push.paths = app.paths;
+      }
 
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
       const steps = (workflow as any).jobs.deploy.steps;
 
-      // Build (if frontend)
-      if (target.type === 'frontend') {
+      // Build (if applicable)
+      if (app.buildCommand) {
         steps.push({
-          name: 'Build Frontend',
-          run: 'npm run build --workspace=@app/frontend',
+          name: `Build ${app.name}`,
+          run: app.buildCommand,
         });
       }
 
@@ -97,7 +89,7 @@ export class GitHubProvider implements RepositoryProvider {
       if (config.installSteps) {
         for (const step of config.installSteps) {
           steps.push({
-            name: `Install ${target.name} CLI`,
+            name: `Install ${provider.name} CLI`,
             run: step,
           });
         }
@@ -107,13 +99,18 @@ export class GitHubProvider implements RepositoryProvider {
       if (config.deploySteps) {
         for (const step of config.deploySteps) {
           const deployStep: Record<string, unknown> = {
-            name: `Deploy to ${target.name}`,
+            name: `Deploy ${app.name} to ${provider.name}`,
             run: step,
-            'working-directory': target.type === 'backend' ? 'apps/backend' : 'apps/frontend',
+            'working-directory': app.target || '.',
           };
 
-          if (config.secrets && config.secrets.length > 0) {
-            deployStep.env = config.secrets.reduce((acc: Record<string, string>, secret) => {
+          const allSecrets = [...(config.secrets || [])];
+          if (app.secrets) {
+            allSecrets.push(...Object.keys(app.secrets));
+          }
+
+          if (allSecrets.length > 0) {
+            deployStep.env = allSecrets.reduce((acc: Record<string, string>, secret) => {
               acc[secret] = `\${{ secrets.${secret} }}`;
               return acc;
             }, {});
@@ -128,7 +125,7 @@ export class GitHubProvider implements RepositoryProvider {
         steps.push(config.githubActionStep);
       }
 
-      await fs.writeFile(filepath, YAML.stringify(workflow), 'utf-8');
+      await fs.writeFile(filepath, YAML.stringify(workflow, { lineWidth: 0 }), 'utf-8');
       logger.info(`Generated workflow: ${filepath}`);
     }
   }