@nexical/cli 0.11.23 → 0.12.0

package/src/deploy/providers/railway.ts

@@ -1,52 +1,54 @@
 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 RailwayProvider implements DeploymentProvider {
+export interface RailwayConfig {
+  token?: string;
+  services?: {
+    type: string;
+    name: string;
+    [key: string]: unknown;
+  }[];
+}
+
+export class RailwayProvider implements HostingProvider {
   name = 'railway';
-  type = 'backend' as const;
 
-  async provision(context: DeploymentContext): Promise<void> {
-    const backendDir = path.join(context.cwd, 'apps/backend');
-    const env = (context.options.env as string) || 'production';
-    const baseProjectName = context.config.deploy?.backend?.projectName;
+  async provision(context: DeploymentContext, app: AppConfig): Promise<void> {
+    const targetDir = app.target ? path.resolve(context.cwd, app.target) : context.cwd;
+    const baseProjectName = app.projectName;
 
     if (!baseProjectName) {
       throw new Error(
-        "Railway project name not found in nexical.yaml. Please configure 'deploy.backend.projectName'.",
+        `Railway project name not found for ${app.name}. Please configure 'projectName'.`,
       );
     }
 
-    const railwayName = env === 'production' ? baseProjectName : `${baseProjectName}-${env}`;
+    const projectName = baseProjectName;
 
-    logger.info('Configuring Railway...');
+    logger.info(`Configuring Railway project "${projectName}" for ${app.name}...`);
 
     if (context.options.dryRun) {
-      logger.info(`[Dry Run] Would check Railway status and init project "${railwayName}".`);
+      logger.info(`[Dry Run] Would check Railway status and init project "${projectName}".`);
       return;
     }
 
     try {
-      // We consciously DO NOT pass any RAILWAY_API_TOKEN to the subprocess.
-      // The user may have an invalid token in their .env file (which process.env inherits).
-      // We want to force the Railway CLI to use the locally logged-in user's credentials.
-      const env = { ...process.env };
-      delete env.RAILWAY_API_TOKEN;
-      delete env.RAILWAY_TOKEN;
+      const processEnv = { ...process.env };
+      delete processEnv.RAILWAY_API_TOKEN;
+      delete processEnv.RAILWAY_TOKEN;
 
       logger.info('Using local Railway CLI credentials (environment variables stripped).');
 
-      // Check status to see if we are linked to a project
       try {
-        await execAsync('railway status', { cwd: backendDir, env });
+        await execAsync('railway status', { cwd: targetDir, env: processEnv });
       } catch (error: unknown) {
         const errMsg = error instanceof Error ? error.message : String(error);
         const stderr = (error as { stderr?: string }).stderr || '';
         const stdout = (error as { stdout?: string }).stdout || '';
         const fullError = `${errMsg} ${stderr} ${stdout}`;
 
-        // If status fails, likely project doesn't exist locally or we aren't linked.
         if (
           fullError.includes('Project not found') ||
           fullError.includes('No project') ||
@@ -54,38 +56,60 @@ export class RailwayProvider implements DeploymentProvider {
         ) {
           if (fullError.includes('Project is deleted')) {
             logger.info('[Railway] Project is deleted. Unlinking...');
-            // If it's deleted, we might need to unlink first to clean up local config
-            await execAsync('railway unlink', { cwd: backendDir }).catch(() => {});
+            await execAsync('railway unlink', { cwd: targetDir }).catch(() => {});
           }
-          const initCmd = `railway init --name ${railwayName}`;
+          const initCmd = `railway init --name ${projectName}`;
           logger.info(`No active Railway project linked. Initializing with: ${initCmd}`);
-          await execAsync(initCmd, { cwd: backendDir, env });
+          await execAsync(initCmd, { cwd: targetDir, env: processEnv });
         } else if (
           fullError.includes('Invalid RAILWAY_API_TOKEN') ||
           fullError.includes('Unauthorized')
         ) {
           throw new Error('Railway authentication failed during status check.');
         } else {
-          // Some other error (e.g. timeout), warn and try to proceed
           logger.warn(`Railway status check failed: ${errMsg}. Proceeding.`);
         }
       }
 
-      logger.info(`Adding PostgreSQL service if missing for "${railwayName}"...`);
-      const { stdout: status } = await execAsync('railway status', { cwd: backendDir, env }).catch(
-        () => ({ stdout: '' }),
-      );
-      if (!status.includes('postgres')) {
-        try {
-          await execAsync('railway add --database postgres', { cwd: backendDir, env });
-        } catch {
-          logger.warn('Failed to auto-add PostgreSQL.');
+      const rwConfig = (app.railway as RailwayConfig) || {};
+      const services = rwConfig.services || [];
+      if (services.length > 0) {
+        logger.info(`Provisioning ${services.length} services for project "${projectName}"...`);
+
+        // Re-check status once to see what's already there
+        const statusData = await execAsync('railway status', {
+          cwd: targetDir,
+          env: processEnv,
+        }).catch(() => ({ stdout: '' }));
+        const status = (statusData as { stdout: string }).stdout || '';
+
+        for (const service of services) {
+          if (service.type === 'database') {
+            const dbName = service.name;
+            if (!status.toLowerCase().includes(dbName.toLowerCase())) {
+              logger.info(`Adding ${dbName} service to project "${projectName}"...`);
+              try {
+                await execAsync(`railway add --database ${dbName}`, {
+                  cwd: targetDir,
+                  env: processEnv,
+                });
+              } catch (err: unknown) {
+                logger.warn(
+                  `Failed to auto-add ${dbName} database: ${err instanceof Error ? err.message : String(err)}`,
+                );
+              }
+            } else {
+              logger.info(`Service ${dbName} already present in project "${projectName}".`);
+            }
+          } else {
+            logger.warn(
+              `Service type "${service.type}" is not yet supported for automatic provisioning.`,
+            );
+          }
         }
       }
     } catch (e: unknown) {
-      // Rethrow explicit auth errors, otherwise warn
       const errMsg = e instanceof Error ? e.message : String(e);
-
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
       const stderr = (e as any).stderr || '';
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -103,9 +127,9 @@ export class RailwayProvider implements DeploymentProvider {
     }
   }
 
-  private resolveToken(context: DeploymentContext): string | undefined {
-    const options = context.config.deploy?.backend?.options || {};
-    const tokenEnvVar = typeof options.tokenEnvVar === 'string' ? options.tokenEnvVar : undefined;
+  private resolveToken(context: DeploymentContext, app: AppConfig): string | undefined {
+    const rwConfig = (app.railway as RailwayConfig) || {};
+    const tokenEnvVar = rwConfig.token;
     return (
       process.env.RAILWAY_API_TOKEN?.trim() ||
       (tokenEnvVar ? process.env[tokenEnvVar]?.trim() : undefined) ||
@@ -113,46 +137,102 @@ export class RailwayProvider implements DeploymentProvider {
     );
   }
 
-  async getSecrets(context: DeploymentContext): Promise<Record<string, string>> {
-    const token = this.resolveToken(context);
+  async deploy(context: DeploymentContext, app: AppConfig): Promise<void> {
+    const targetDir = app.target ? path.resolve(context.cwd, app.target) : context.cwd;
+
+    logger.info(`Deploying ${app.name} to Railway...`);
+
+    if (context.options.dryRun) {
+      logger.info(`[Dry Run] Would run "railway up" in ${targetDir}.`);
+      return;
+    }
+
+    const token = this.resolveToken(context, app);
+    const processEnv = { ...process.env };
+    if (token) {
+      processEnv.RAILWAY_TOKEN = token;
+    }
+
+    await execAsync('railway up --detach', {
+      cwd: targetDir,
+      env: processEnv,
+    });
+
+    logger.success(`Successfully deployed ${app.name} to Railway.`);
+  }
+
+  async getSecrets(context: DeploymentContext, app: AppConfig): Promise<Record<string, string>> {
+    const token = this.resolveToken(context, app);
     const secrets: Record<string, string> = {};
 
     if (!token) {
-      // Strict check: Error if token is missing
       throw new Error(
-        `Railway Token not found. Please provide it via:\n` +
+        `Railway Token not found for ${app.name}. Please provide it via:\n` +
           `1. Setting RAILWAY_API_TOKEN in .env (Recommended)\n` +
-          `2. Configuring 'deploy.backend.options.tokenEnvVar' in nexical.yaml\n` +
+          `2. Configuring 'railway.token' and setting that env var in .env\n` +
           `3. Setting RAILWAY_TOKEN in .env`,
       );
     }
 
     secrets['RAILWAY_API_TOKEN'] = token;
+
+    // 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?.backend?.projectName;
+    const baseProjectName = app.projectName;
 
     if (!baseProjectName) {
-      throw new Error(
-        "Railway project name not found in nexical.yaml. Please configure 'deploy.backend.projectName'.",
-      );
+      throw new Error(`Railway project name not found for ${app.name}.`);
     }
 
-    const projectName = env === 'production' ? baseProjectName : `${baseProjectName}-${env}`;
-    return {
-      RAILWAY_PROJECT_NAME: projectName,
+    const result: Record<string, string> = {
+      RAILWAY_PROJECT_NAME: baseProjectName,
+      RAILWAY_ENVIRONMENT: env,
     };
+
+    // Custom mapped variables
+    if (app.env) {
+      for (const [key, value] of Object.entries(app.env)) {
+        const resolvedValue = process.env[value] || value;
+        result[key] = resolvedValue;
+      }
+    }
+
+    return result;
   }
 
-  getCIConfig(): CIConfig {
+  getCIConfig(repoType: 'github' | 'gitlab', app: AppConfig): CIConfig {
     return {
       secrets: ['RAILWAY_API_TOKEN'],
-      variables: [],
+      variables: ['RAILWAY_ENVIRONMENT'],
       installSteps: ['npm install -g @railway/cli'],
-      deploySteps: ['railway up --detach --project=${{ vars.RAILWAY_PROJECT_NAME }}'],
+      deploySteps: [
+        `railway up --detach --project=\${{ vars.RAILWAY_PROJECT_NAME }} --environment=\${{ vars.RAILWAY_ENVIRONMENT }}`,
+      ],
     };
   }
+
+  getDefaultDnsTarget(app: AppConfig): string | undefined {
+    // Railway typically creates a [project-name]-[environment].up.railway.app domain.
+    // For simpler custom domain linking, users often just CNAME directly to up.railway.app
+    // or the specific assigned railway generated domain if it's predictable.
+    // For automatic resolution without runtime polling, returning the predictable project CNAME.
+    if (app.projectName) {
+      return `${app.projectName}.up.railway.app`;
+    }
+    return undefined;
+  }
 }

package/src/deploy/registry.ts

@@ -1,64 +1,85 @@
 import path from 'node:path';
 import fs from 'node:fs/promises';
 import { logger } from '@nexical/cli-core';
-import { DeploymentProvider, RepositoryProvider } from './types';
+import { HostingProvider, RepositoryProvider, DnsProvider } from './types';
 
 export class ProviderRegistry {
-  private deploymentProviders: Map<string, DeploymentProvider> = new Map();
+  private hostingProviders: Map<string, HostingProvider> = new Map();
   private repositoryProviders: Map<string, RepositoryProvider> = new Map();
+  private dnsProviders: Map<string, DnsProvider> = new Map();
 
-  registerDeploymentProvider(provider: DeploymentProvider) {
-    this.deploymentProviders.set(provider.name, provider);
+  registerHostingProvider(provider: HostingProvider) {
+    this.hostingProviders.set(provider.name, provider);
   }
 
   registerRepositoryProvider(provider: RepositoryProvider) {
     this.repositoryProviders.set(provider.name, provider);
   }
 
-  getDeploymentProvider(name: string): DeploymentProvider | undefined {
-    return this.deploymentProviders.get(name);
+  getHostingProvider(name: string): HostingProvider | undefined {
+    return this.hostingProviders.get(name);
   }
 
   getRepositoryProvider(name: string): RepositoryProvider | undefined {
     return this.repositoryProviders.get(name);
   }
 
+  registerDnsProvider(provider: DnsProvider) {
+    this.dnsProviders.set(provider.name, provider);
+  }
+
+  getDnsProvider(name: string): DnsProvider | undefined {
+    return this.dnsProviders.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;
+    const exports = module as Record<string, unknown>;
+    let ProviderCandidate = exports?.default;
 
     // Handle named exports if default is missing (fallback)
-    if (!provider && Object.keys(moduleAny).length > 0) {
+    if (!ProviderCandidate && exports && Object.keys(exports).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];
+      for (const key of Object.keys(exports)) {
+        if (typeof exports[key] === 'function') {
+          ProviderCandidate = exports[key];
           break;
         }
       }
     }
 
-    // If it's a class, instantiate it
-    if (typeof provider === 'function') {
+    if (!ProviderCandidate) return;
+
+    let instance: unknown;
+    if (typeof ProviderCandidate === 'function') {
       try {
-        provider = new provider();
+        instance = new (ProviderCandidate as new () => unknown)();
       } catch {
-        // Not a constructor or failed
+        // Not a constructor or failed, could be a regular function
+        instance = ProviderCandidate;
       }
+    } else {
+      instance = ProviderCandidate;
     }
 
-    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);
-      }
+    if (!instance || typeof instance !== 'object') return;
+
+    const provider = instance as Record<string, unknown>;
+
+    if (typeof provider.provision === 'function' && typeof provider.getCIConfig === 'function') {
+      const p = provider as unknown as HostingProvider;
+      logger.info(`[Registry] Loaded ${source} hosting provider: ${p.name}`);
+      this.registerHostingProvider(p);
+    } else if (
+      typeof provider.configureSecrets === 'function' &&
+      typeof provider.generateWorkflow === 'function'
+    ) {
+      const p = provider as unknown as RepositoryProvider;
+      logger.info(`[Registry] Loaded ${source} repository provider: ${p.name}`);
+      this.registerRepositoryProvider(p);
+    } else if (typeof provider.provision === 'function' && provider.type === 'dns') {
+      const p = provider as unknown as DnsProvider;
+      logger.info(`[Registry] Loaded ${source} DNS provider: ${p.name}`);
+      this.registerDnsProvider(p);
     }
   }
 

package/src/deploy/schema.ts

@@ -0,0 +1,39 @@
+import { z } from 'zod';
+
+export const AppConfigSchema = z
+  .object({
+    provider: z.string(),
+    projectName: z.string().optional(),
+    target: z.string().optional(),
+    buildCommand: z.string().optional(),
+    artifactPath: z.string().optional(),
+    paths: z.array(z.string()).optional(),
+    options: z.record(z.string(), z.any()).optional(),
+    env: z.record(z.string(), z.string()).optional(),
+    secrets: z.record(z.string(), z.string()).optional(),
+    domain: z.union([z.string(), z.array(z.string())]).optional(),
+    dnsTarget: z.string().optional(),
+  })
+  .passthrough();
+
+export const DeploymentSchema = z.object({
+  deploy: z
+    .object({
+      repository: z
+        .object({
+          provider: z.string(),
+          options: z.record(z.string(), z.any()).optional(),
+        })
+        .optional(),
+      dns: z
+        .object({
+          provider: z.string(),
+        })
+        .passthrough()
+        .optional(),
+      apps: z.record(z.string(), AppConfigSchema).optional(),
+    })
+    .optional(),
+});
+
+export type ValidatedNexicalConfig = z.infer<typeof DeploymentSchema>;

package/src/deploy/template-manager.ts

@@ -0,0 +1,32 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import YAML from 'yaml';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+export interface WorkflowTemplateData {
+  APP_NAME: string;
+  PROVIDER_NAME: string;
+  [key: string]: string;
+}
+
+export class TemplateManager {
+  private templatesDir: string;
+
+  constructor() {
+    this.templatesDir = path.join(__dirname, 'templates');
+  }
+
+  async loadWorkflow(name: string, data: WorkflowTemplateData): Promise<unknown> {
+    const templatePath = path.join(this.templatesDir, `${name}.yaml`);
+    let content = await fs.readFile(templatePath, 'utf-8');
+
+    // Simple placeholder replacement
+    for (const [key, value] of Object.entries(data)) {
+      content = content.split(`\${${key}}`).join(value);
+    }
+
+    return YAML.parse(content);
+  }
+}

package/src/deploy/templates/github-workflow.yaml

@@ -0,0 +1,23 @@
+name: Deploy ${APP_NAME} to ${PROVIDER_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

package/src/deploy/types.ts

@@ -8,28 +8,49 @@ export interface CIConfig {
   githubActionStep?: Record<string, unknown>;
 }
 
+export interface AppConfig {
+  name: string;
+  provider: string;
+  projectName?: string;
+  target?: string;
+  buildCommand?: string;
+  artifactPath?: string;
+  paths?: string[];
+  options?: Record<string, unknown>;
+  env?: Record<string, string>;
+  secrets?: Record<string, string>;
+  domain?: string | string[];
+  dnsTarget?: string;
+  [key: string]: unknown;
+}
+
 export interface DeploymentContext {
   cwd: string;
   config: NexicalConfig;
   options: Record<string, unknown>;
 }
 
-export interface DeploymentProvider {
+export interface HostingProvider {
   name: string;
-  type: 'frontend' | 'backend';
 
   // Interactive or automatic setup of the provider resources
-  provision(context: DeploymentContext): Promise<void>;
+  provision(context: DeploymentContext, app: AppConfig): Promise<void>;
 
   // Returns the CI configuration for this provider
-  getCIConfig(repoType: 'github' | 'gitlab'): CIConfig;
+  getCIConfig(repoType: 'github' | 'gitlab', app: AppConfig): 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>>;
+  getSecrets(context: DeploymentContext, app: AppConfig): 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>>;
+  getVariables(context: DeploymentContext, app: AppConfig): Promise<Record<string, string>>;
+
+  // Performs a manual build/deployment from the local machine
+  deploy?(context: DeploymentContext, app: AppConfig): Promise<void>;
+
+  // Optional: Automatically infer the DnsTarget from the hosting configuration
+  getDefaultDnsTarget?(app: AppConfig): string | undefined;
 }
 
 export interface RepositoryProvider {
@@ -40,24 +61,35 @@ export interface RepositoryProvider {
   configureVariables(context: DeploymentContext, variables: Record<string, string>): Promise<void>;
 
   // Generates and writes the CI workflow files
-  generateWorkflow(context: DeploymentContext, targets: DeploymentProvider[]): Promise<void>;
+  generateWorkflow(
+    context: DeploymentContext,
+    targets: { provider: HostingProvider; app: AppConfig }[],
+  ): Promise<void>;
 }
 
 export interface NexicalConfig {
   deploy?: {
-    backend?: {
+    apps?: Record<string, Omit<AppConfig, 'name'>>;
+    repository?: {
       provider: string;
-      projectName?: string;
       options?: Record<string, unknown>;
     };
-    frontend?: {
+    dns?: {
       provider: string;
-      projectName?: string;
-      options?: Record<string, unknown>;
-    };
-    repository?: {
-      provider: string;
-      options?: Record<string, unknown>;
+      [key: string]: unknown;
     };
   };
 }
+
+export interface DnsRecord {
+  type: string;
+  name: string;
+  content: string;
+  proxied?: boolean;
+}
+
+export interface DnsProvider {
+  name: string;
+  type?: 'dns';
+  provision(context: DeploymentContext, records: DnsRecord[]): Promise<void>;
+}