@nexical/cli 0.11.3 → 0.11.5

package/src/deploy/providers/github.ts

@@ -0,0 +1,135 @@
+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 { execAsync } from '../utils';
+
+export class GitHubProvider implements RepositoryProvider {
+  name = 'github';
+
+  async configureSecrets(
+    context: DeploymentContext,
+    secrets: Record<string, string>,
+  ): Promise<void> {
+    for (const [key, value] of Object.entries(secrets)) {
+      if (!value) continue;
+      logger.info(`Setting secret ${key} in GitHub...`);
+      if (context.options.dryRun) {
+        logger.info(`[Dry Run] Would set secret ${key}`);
+      } else {
+        await execAsync(`gh secret set ${key} --body "${value}"`);
+      }
+    }
+  }
+
+  async configureVariables(
+    context: DeploymentContext,
+    variables: Record<string, string>,
+  ): Promise<void> {
+    for (const [key, value] of Object.entries(variables)) {
+      if (!value) continue;
+      logger.info(`Setting variable ${key} in GitHub...`);
+      if (context.options.dryRun) {
+        logger.info(`[Dry Run] Would set variable ${key}`);
+      } else {
+        await execAsync(`gh variable set ${key} --body "${value}"`);
+      }
+    }
+  }
+
+  async generateWorkflow(context: DeploymentContext, targets: DeploymentProvider[]): 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');
+      if (!config) continue;
+
+      const filename = `deploy-${target.type}.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',
+              },
+            ],
+          },
+        },
+      };
+
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const steps = (workflow as any).jobs.deploy.steps;
+
+      // Build (if frontend)
+      if (target.type === 'frontend') {
+        steps.push({
+          name: 'Build Frontend',
+          run: 'npm run build --workspace=@app/frontend',
+        });
+      }
+
+      // Provider Install Steps
+      if (config.installSteps) {
+        for (const step of config.installSteps) {
+          steps.push({
+            name: `Install ${target.name} CLI`,
+            run: step,
+          });
+        }
+      }
+
+      // Provider Deploy Steps
+      if (config.deploySteps) {
+        for (const step of config.deploySteps) {
+          const deployStep: Record<string, unknown> = {
+            name: `Deploy to ${target.name}`,
+            run: step,
+            'working-directory': target.type === 'backend' ? 'apps/backend' : 'apps/frontend',
+          };
+
+          if (config.secrets && config.secrets.length > 0) {
+            deployStep.env = config.secrets.reduce((acc: Record<string, string>, secret) => {
+              acc[secret] = `\${{ secrets.${secret} }}`;
+              return acc;
+            }, {});
+          }
+
+          steps.push(deployStep);
+        }
+      }
+
+      // Provider Action Step
+      if (config.githubActionStep) {
+        steps.push(config.githubActionStep);
+      }
+
+      await fs.writeFile(filepath, YAML.stringify(workflow), 'utf-8');
+      logger.info(`Generated workflow: ${filepath}`);
+    }
+  }
+}

package/src/deploy/providers/railway.ts

@@ -0,0 +1,103 @@
+import path from 'node:path';
+import { logger } from '@nexical/cli-core';
+import { DeploymentProvider, DeploymentContext, CIConfig } from '../types';
+import { execAsync } from '../utils';
+
+export class RailwayProvider implements DeploymentProvider {
+  name = 'railway';
+  type = 'backend' as const;
+
+  async provision(context: DeploymentContext): Promise<void> {
+    const backendDir = path.join(context.cwd, 'apps/backend');
+    // Resolve project name/token
+    const railwayName = context.config.deploy?.backend?.projectName;
+
+    if (!railwayName) {
+      throw new Error(
+        "Railway project name not found in nexical.yaml. Please configure 'deploy.backend.projectName'.",
+      );
+    }
+
+    // Service name defaults to project name for the primary backend
+    const serviceName = railwayName || 'nexical-backend';
+    // Note: Token is usually handled by `railway login` for CLI, but for CI we need it.
+    // The provider might not need to know the token for `provision` if we rely on CLI auth.
+    // However, we might need to export it for GitHub secrets.
+
+    logger.info('Configuring Railway...');
+
+    if (context.options.dryRun) {
+      logger.info('[Dry Run] Would check Railway status and init project.');
+      return;
+    }
+
+    try {
+      try {
+        await execAsync('railway status', { cwd: backendDir });
+      } catch {
+        const initCmd = railwayName ? `railway init --name ${railwayName}` : 'railway init';
+        logger.info(`No Railway project detected in apps/backend. Initializing with: ${initCmd}`);
+        await execAsync(initCmd, { cwd: backendDir });
+      }
+
+      logger.info(`Adding PostgreSQL service if missing for "${serviceName}"...`);
+      const { stdout: status } = await execAsync('railway status', { cwd: backendDir });
+      if (!status.includes('postgres')) {
+        await execAsync('railway add --database postgres', { cwd: backendDir });
+      }
+    } catch (e: unknown) {
+      logger.warn(
+        'Railway setup encountered an issue. Ensure you are logged in with `railway login`.',
+      );
+      throw e;
+    }
+  }
+
+  async getSecrets(context: DeploymentContext): Promise<Record<string, string>> {
+    const options = context.config.deploy?.backend?.options || {};
+    const secrets: Record<string, string> = {};
+
+    // Resolve Railway Token
+    // Priority: Configured Env Var > Default Env Var
+    const tokenEnvVar = typeof options.tokenEnvVar === 'string' ? options.tokenEnvVar : undefined;
+    const token = (tokenEnvVar ? process.env[tokenEnvVar] : undefined) || process.env.RAILWAY_TOKEN;
+
+    if (!token) {
+      // Strict check: Error if token is missing
+      throw new Error(
+        `Railway Token not found. Please provide it via:\n` +
+          `1. Configuring 'deploy.backend.options.tokenEnvVar' in nexical.yaml and setting that env var in .env\n` +
+          `2. Setting RAILWAY_TOKEN in .env`,
+      );
+    }
+
+    secrets['RAILWAY_TOKEN'] = token;
+    return secrets;
+  }
+
+  async getVariables(context: DeploymentContext): Promise<Record<string, string>> {
+    const railwayName = context.config.deploy?.backend?.projectName;
+
+    if (!railwayName) {
+      throw new Error(
+        "Railway project name not found in nexical.yaml. Please configure 'deploy.backend.projectName'.",
+      );
+    }
+
+    // Service name defaults to project name
+    const serviceName = railwayName || 'nexical-backend';
+
+    return {
+      RAILWAY_SERVICE_NAME: serviceName,
+    };
+  }
+
+  getCIConfig(): CIConfig {
+    return {
+      secrets: ['RAILWAY_TOKEN'],
+      variables: ['RAILWAY_SERVICE_NAME'],
+      installSteps: ['npm install -g @railway/cli'],
+      deploySteps: ['railway up --service ${{ vars.RAILWAY_SERVICE_NAME }} --detach'],
+    };
+  }
+}

package/src/deploy/registry.ts

@@ -0,0 +1,136 @@
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import { logger } from '@nexical/cli-core';
+import { DeploymentProvider, RepositoryProvider } from './types';
+
+export class ProviderRegistry {
+  private deploymentProviders: Map<string, DeploymentProvider> = new Map();
+  private repositoryProviders: Map<string, RepositoryProvider> = new Map();
+
+  registerDeploymentProvider(provider: DeploymentProvider) {
+    this.deploymentProviders.set(provider.name, provider);
+  }
+
+  registerRepositoryProvider(provider: RepositoryProvider) {
+    this.repositoryProviders.set(provider.name, provider);
+  }
+
+  getDeploymentProvider(name: string): DeploymentProvider | undefined {
+    return this.deploymentProviders.get(name);
+  }
+
+  getRepositoryProvider(name: string): RepositoryProvider | undefined {
+    return this.repositoryProviders.get(name);
+  }
+
+  private registerProviderFromModule(module: unknown, source: string) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const moduleAny = module as any;
+    let provider = moduleAny.default;
+
+    // Handle named exports if default is missing (fallback)
+    if (!provider && Object.keys(moduleAny).length > 0) {
+      // Try to find a class export that looks like a provider
+      for (const key of Object.keys(moduleAny)) {
+        if (typeof moduleAny[key] === 'function') {
+          provider = moduleAny[key];
+          break;
+        }
+      }
+    }
+
+    // If it's a class, instantiate it
+    if (typeof provider === 'function') {
+      try {
+        provider = new provider();
+      } catch {
+        // Not a constructor or failed
+      }
+    }
+
+    if (provider) {
+      if (typeof provider.provision === 'function' && typeof provider.getCIConfig === 'function') {
+        logger.info(`[Registry] Loaded ${source} deployment provider: ${provider.name}`);
+        this.registerDeploymentProvider(provider as DeploymentProvider);
+      } else if (
+        typeof provider.configureSecrets === 'function' &&
+        typeof provider.generateWorkflow === 'function'
+      ) {
+        logger.info(`[Registry] Loaded ${source} repository provider: ${provider.name}`);
+        this.registerRepositoryProvider(provider as RepositoryProvider);
+      }
+    }
+  }
+
+  async loadCoreProviders() {
+    const dirname = path.dirname(new URL(import.meta.url).pathname);
+
+    // Try multiple paths to find the providers directory
+    // 1. 'providers' - Standard source structure / flattened dist
+    // 2. 'src/deploy/providers' - tsup output (chunk in root, files in src/...)
+    const candidates = [
+      path.join(dirname, 'providers'),
+      path.join(dirname, 'src/deploy/providers'),
+    ];
+
+    let providersDir = '';
+    for (const candidate of candidates) {
+      try {
+        await fs.access(candidate);
+        providersDir = candidate;
+        break;
+      } catch {
+        // Ignore missing dir
+      }
+    }
+
+    if (!providersDir) {
+      logger.warn(
+        `[Registry] Could not locate core providers directory. Checked: ${candidates.join(', ')}`,
+      );
+      return;
+    }
+
+    try {
+      const files = await fs.readdir(providersDir);
+      for (const file of files) {
+        if (file.endsWith('.js') || (file.endsWith('.ts') && !file.endsWith('.d.ts'))) {
+          try {
+            const providerPath = path.join(providersDir, file);
+            const module = await import(providerPath);
+            this.registerProviderFromModule(module, 'core');
+          } catch (e: unknown) {
+            const message = e instanceof Error ? e.message : String(e);
+            logger.warn(`Failed to load core provider from ${file}: ${message}`);
+          }
+        }
+      }
+    } catch (e: unknown) {
+      const message = e instanceof Error ? e.message : String(e);
+      logger.warn(`Failed to scan core providers at ${providersDir}: ${message}`);
+    }
+  }
+
+  async loadLocalProviders(cwd: string) {
+    const deployDir = path.join(cwd, 'deploy');
+    try {
+      const files = await fs.readdir(deployDir);
+      for (const file of files) {
+        if (file.endsWith('.ts') || file.endsWith('.js')) {
+          try {
+            const providerPath = path.join(deployDir, file);
+            // Use jiti to load TS/JS files dynamically
+            const jiti = (await import('jiti')).createJiti(import.meta.url);
+            const module = (await jiti.import(providerPath)) as unknown;
+            this.registerProviderFromModule(module, 'local');
+          } catch (e: unknown) {
+            const message = e instanceof Error ? e.message : String(e);
+            logger.warn(`Failed to load local provider from ${file}: ${message}`);
+          }
+        }
+      }
+    } catch {
+      // Ignore if deploy dir doesn't exist
+    }
+  }
+}

package/src/deploy/types.ts

@@ -0,0 +1,63 @@
+export interface CIConfig {
+  secrets: string[];
+  variables: string[];
+  installSteps?: string[];
+  buildSteps?: string[];
+  deploySteps?: string[];
+  // Platform specific overrides (e.g. uses: action/...)
+  githubActionStep?: Record<string, unknown>;
+}
+
+export interface DeploymentContext {
+  cwd: string;
+  config: NexicalConfig;
+  options: Record<string, unknown>;
+}
+
+export interface DeploymentProvider {
+  name: string;
+  type: 'frontend' | 'backend';
+
+  // Interactive or automatic setup of the provider resources
+  provision(context: DeploymentContext): Promise<void>;
+
+  // Returns the CI configuration for this provider
+  getCIConfig(repoType: 'github' | 'gitlab'): CIConfig;
+
+  // Returns a map of secrets to be set in the repository (e.g. tokens, account IDs)
+  // The provider is responsible for resolving these from config/env and throwing if missing.
+  getSecrets(context: DeploymentContext): Promise<Record<string, string>>;
+
+  // Returns a map of variables to be set in the repository (e.g. project names, service names)
+  getVariables(context: DeploymentContext): Promise<Record<string, string>>;
+}
+
+export interface RepositoryProvider {
+  name: string;
+
+  // Sets secrets/variables in the repo
+  configureSecrets(context: DeploymentContext, secrets: Record<string, string>): Promise<void>;
+  configureVariables(context: DeploymentContext, variables: Record<string, string>): Promise<void>;
+
+  // Generates and writes the CI workflow files
+  generateWorkflow(context: DeploymentContext, targets: DeploymentProvider[]): Promise<void>;
+}
+
+export interface NexicalConfig {
+  deploy?: {
+    backend?: {
+      provider: string;
+      projectName?: string;
+      options?: Record<string, unknown>;
+    };
+    frontend?: {
+      provider: string;
+      projectName?: string;
+      options?: Record<string, unknown>;
+    };
+    repository?: {
+      provider: string;
+      options?: Record<string, unknown>;
+    };
+  };
+}

package/src/deploy/utils.ts

@@ -0,0 +1,13 @@
+import { exec } from 'node:child_process';
+import { promisify } from 'node:util';
+
+export const execAsync = promisify(exec);
+
+export async function checkCommand(command: string): Promise<boolean> {
+  try {
+    await execAsync(command);
+    return true;
+  } catch {
+    return false;
+  }
+}