@korajs/cli 0.1.15 → 0.2.0

package/dist/index.d.cts

@@ -1,4 +1,5 @@
 import { KoraError, SchemaDefinition } from '@korajs/core';
+import * as citty from 'citty';
 
 /** Supported package managers */
 declare const PACKAGE_MANAGERS: readonly ["pnpm", "npm", "yarn", "bun"];
@@ -19,6 +20,7 @@ interface TemplateContext {
     projectName: string;
     packageManager: PackageManager;
     koraVersion: string;
+    dbProvider?: string;
 }
 
 /**
@@ -69,4 +71,618 @@ declare class DevServerError extends KoraError {
  */
 declare function generateTypes(schema: SchemaDefinition): string;
 
-export { CliError, DevServerError, InvalidProjectError, PACKAGE_MANAGERS, type PackageManager, ProjectExistsError, SchemaNotFoundError, TEMPLATES, TEMPLATE_INFO, type TemplateContext, type TemplateInfo, type TemplateName, generateTypes };
+/**
+ * The `deploy` command for Phase 13.
+ *
+ * This command orchestrates:
+ * - deploy state resolution and persistence
+ * - artifact generation
+ * - adapter-driven provision/build/deploy flows
+ */
+declare const deployCommand: citty.CommandDef<{
+    platform: {
+        type: "string";
+        description: string;
+    };
+    app: {
+        type: "string";
+        description: string;
+    };
+    region: {
+        type: "string";
+        description: string;
+    };
+    prod: {
+        type: "boolean";
+        description: string;
+        default: false;
+    };
+    confirm: {
+        type: "boolean";
+        description: string;
+        default: false;
+    };
+    reset: {
+        type: "boolean";
+        description: string;
+        default: false;
+    };
+}>;
+
+declare const DEPLOY_PLATFORMS: readonly ["fly", "railway", "render", "docker", "kora-cloud"];
+type DeployPlatform = (typeof DEPLOY_PLATFORMS)[number];
+interface ProjectConfig {
+    projectRoot: string;
+    appName: string;
+    region: string | null;
+    environment: 'preview' | 'production';
+    confirm: boolean;
+}
+interface ProvisionResult {
+    applicationId: string;
+    databaseId: string | null;
+    secretsSet: string[];
+}
+interface BuildArtifacts {
+    clientDirectory: string | null;
+    serverBundlePath: string | null;
+    deployDirectory: string;
+}
+interface DeployResult {
+    deploymentId: string;
+    liveUrl: string;
+    syncUrl: string | null;
+}
+interface LogOptions {
+    since?: string;
+    tail?: number;
+}
+interface LogLine {
+    timestamp: string;
+    level: 'debug' | 'info' | 'warn' | 'error';
+    message: string;
+}
+interface DeploymentStatus {
+    state: 'pending' | 'healthy' | 'failed' | 'unknown';
+    message: string;
+    liveUrl?: string;
+}
+/**
+ * Contract implemented by each deployment platform integration.
+ */
+interface DeployAdapter {
+    name: DeployPlatform;
+    detect(): Promise<boolean>;
+    install(): Promise<void>;
+    authenticate(): Promise<void>;
+    provision(config: ProjectConfig): Promise<ProvisionResult>;
+    build(config: ProjectConfig): Promise<BuildArtifacts>;
+    deploy(artifacts: BuildArtifacts): Promise<DeployResult>;
+    rollback(deploymentId: string): Promise<void>;
+    logs(options: LogOptions): AsyncIterable<LogLine>;
+    status(): Promise<DeploymentStatus>;
+}
+/**
+ * Optional adapter extension for commands that require runtime context
+ * (project root, app name, region) outside an initial provisioning run.
+ */
+interface ContextAwareDeployAdapter extends DeployAdapter {
+    setContext(context: {
+        projectRoot: string;
+        appName: string;
+        region: string | null;
+    }): void;
+}
+/**
+ * Checks whether the provided value is a known deploy platform.
+ */
+declare function isDeployPlatform(value: string): value is DeployPlatform;
+
+/**
+ * Execution abstraction for Fly CLI shell interactions.
+ * This keeps FlyAdapter deterministic and fully mockable in tests.
+ */
+interface FlyCommandRunner {
+    run(command: string, args: string[], cwd: string): Promise<FlyCommandResult>;
+}
+interface FlyCommandResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+}
+interface FlyAdapterOptions {
+    runner?: FlyCommandRunner;
+    context?: FlyAdapterContext;
+    commandCandidates?: readonly string[];
+}
+/**
+ * Fly.io deploy adapter implementation for Phase 13.
+ */
+declare class FlyAdapter implements ContextAwareDeployAdapter {
+    readonly name: "fly";
+    private readonly logger;
+    private readonly runner;
+    private readonly commandCandidates;
+    private flyCommand;
+    private currentContext;
+    private lastDeploymentId;
+    constructor(options?: FlyAdapterOptions);
+    /**
+     * Seeds runtime context for non-provisioning commands.
+     */
+    setContext(context: FlyAdapterContext): void;
+    /**
+     * Checks whether a Fly CLI executable can be resolved.
+     */
+    detect(): Promise<boolean>;
+    /**
+     * Ensures Fly CLI is available before deployment.
+     */
+    install(): Promise<void>;
+    /**
+     * Performs Fly authentication check/login.
+     */
+    authenticate(): Promise<void>;
+    /**
+     * Provisions app and optionally region-bound resources in Fly.
+     */
+    provision(config: ProjectConfig): Promise<ProvisionResult>;
+    /**
+     * Builds local artifacts consumed by Fly deploy.
+     */
+    build(config: ProjectConfig): Promise<BuildArtifacts>;
+    /**
+     * Deploys generated artifacts to Fly and returns live endpoints.
+     */
+    deploy(artifacts: BuildArtifacts): Promise<DeployResult>;
+    /**
+     * Rolls back to a deployment version.
+     */
+    rollback(deploymentId: string): Promise<void>;
+    /**
+     * Returns deployment logs as an async iterable.
+     */
+    logs(options: LogOptions): AsyncIterable<LogLine>;
+    /**
+     * Reads current deployment status from Fly.
+     */
+    status(): Promise<DeploymentStatus>;
+    private runFlyCommand;
+    private requireContext;
+    private resolveFlyCommand;
+    private tryResolveFlyCommand;
+}
+/**
+ * Default subprocess-backed runner for Fly commands.
+ */
+declare class NodeFlyCommandRunner implements FlyCommandRunner {
+    run(command: string, args: string[], cwd: string): Promise<FlyCommandResult>;
+}
+interface FlyAdapterContext {
+    projectRoot: string;
+    appName: string;
+    region: string | null;
+}
+
+/**
+ * Creates a deploy adapter instance for the selected platform.
+ */
+declare function createDeployAdapter(platform: DeployPlatform): DeployAdapter;
+
+/**
+ * Execution abstraction for Railway CLI shell interactions.
+ */
+interface RailwayCommandRunner {
+    run(command: string, args: string[], cwd: string): Promise<RailwayCommandResult>;
+}
+interface RailwayCommandResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+}
+interface RailwayAdapterOptions {
+    runner?: RailwayCommandRunner;
+    context?: RailwayAdapterContext;
+    commandCandidates?: readonly string[];
+}
+/**
+ * Railway deploy adapter implementation for Phase 13.
+ */
+declare class RailwayAdapter implements ContextAwareDeployAdapter {
+    readonly name: "railway";
+    private readonly logger;
+    private readonly runner;
+    private readonly commandCandidates;
+    private railwayCommand;
+    private currentContext;
+    private lastDeploymentId;
+    constructor(options?: RailwayAdapterOptions);
+    setContext(context: RailwayAdapterContext): void;
+    detect(): Promise<boolean>;
+    install(): Promise<void>;
+    authenticate(): Promise<void>;
+    provision(config: ProjectConfig): Promise<ProvisionResult>;
+    build(config: ProjectConfig): Promise<BuildArtifacts>;
+    deploy(artifacts: BuildArtifacts): Promise<DeployResult>;
+    rollback(deploymentId: string): Promise<void>;
+    logs(options: LogOptions): AsyncIterable<LogLine>;
+    status(): Promise<DeploymentStatus>;
+    private runRailwayCommand;
+    private requireContext;
+    private resolveRailwayCommand;
+    private tryResolveRailwayCommand;
+}
+/**
+ * Default subprocess-backed runner for Railway commands.
+ */
+declare class NodeRailwayCommandRunner implements RailwayCommandRunner {
+    run(command: string, args: string[], cwd: string): Promise<RailwayCommandResult>;
+}
+interface RailwayAdapterContext {
+    projectRoot: string;
+    appName: string;
+    region: string | null;
+}
+
+/**
+ * Lightweight scaffold adapter used for platforms not yet implemented.
+ * It provides explicit, deterministic errors while preserving the shared
+ * adapter contract and command wiring across all platforms.
+ */
+declare class StubDeployAdapter implements ContextAwareDeployAdapter {
+    readonly name: DeployPlatform;
+    private readonly contextLabel;
+    constructor(platform: DeployPlatform);
+    setContext(_context: {
+        projectRoot: string;
+        appName: string;
+        region: string | null;
+    }): void;
+    detect(): Promise<boolean>;
+    install(): Promise<void>;
+    authenticate(): Promise<void>;
+    provision(_config: ProjectConfig): Promise<ProvisionResult>;
+    build(_config: ProjectConfig): Promise<BuildArtifacts>;
+    deploy(_artifacts: BuildArtifacts): Promise<DeployResult>;
+    rollback(_deploymentId: string): Promise<void>;
+    logs(_options: LogOptions): AsyncIterable<LogLine>;
+    status(): Promise<DeploymentStatus>;
+    private notImplementedError;
+    private notImplementedMessage;
+}
+
+/**
+ * Durable deployment settings stored for subsequent `kora deploy` runs.
+ */
+interface DeployState {
+    platform: DeployPlatform;
+    appName: string;
+    region: string | null;
+    projectRoot: string;
+    liveUrl: string | null;
+    syncUrl: string | null;
+    databaseId: string | null;
+    lastDeploymentId: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * Input required to create a new deployment state record.
+ */
+interface DeployStateCreateInput {
+    platform: DeployPlatform;
+    appName: string;
+    region: string | null;
+    projectRoot: string;
+    liveUrl?: string | null;
+    syncUrl?: string | null;
+    databaseId?: string | null;
+    lastDeploymentId?: string | null;
+}
+/**
+ * Partial update fields for an existing deployment state record.
+ */
+interface DeployStatePatch {
+    platform?: DeployPlatform;
+    appName?: string;
+    region?: string | null;
+    projectRoot?: string;
+    liveUrl?: string | null;
+    syncUrl?: string | null;
+    databaseId?: string | null;
+    lastDeploymentId?: string | null;
+}
+/**
+ * Returns the absolute path to `.kora/deploy`.
+ */
+declare function resolveDeployDirectory(projectRoot: string): string;
+/**
+ * Returns the absolute path to `.kora/deploy/deploy.json`.
+ */
+declare function resolveDeployStatePath(projectRoot: string): string;
+/**
+ * Loads deployment state from `.kora/deploy/deploy.json`.
+ * Returns null when the file does not exist.
+ */
+declare function readDeployState(projectRoot: string): Promise<DeployState | null>;
+/**
+ * Writes a brand-new deployment state record, replacing any existing file.
+ */
+declare function writeDeployState(projectRoot: string, input: DeployStateCreateInput, now?: Date): Promise<DeployState>;
+/**
+ * Applies a partial update to deployment state.
+ * Throws when state does not exist.
+ */
+declare function updateDeployState(projectRoot: string, patch: DeployStatePatch, now?: Date): Promise<DeployState>;
+/**
+ * Removes the entire `.kora/deploy` directory tree.
+ */
+declare function resetDeployState(projectRoot: string): Promise<void>;
+
+/**
+ * Configuration for generating a production Dockerfile.
+ */
+interface DockerfileOptions {
+    nodeVersion?: string;
+    port?: number;
+    clientDirectory?: string;
+    serverBundleFile?: string;
+    /** Native modules that must be installed at runtime (externalized from bundle). */
+    nativeDependencies?: Record<string, string>;
+}
+/**
+ * Generates a multi-stage Dockerfile for Kora deployments.
+ *
+ * The generated image expects artifacts produced under `.kora/deploy`:
+ * - `dist/` for client assets
+ * - `server-bundled.js` for server runtime entry
+ * - `package.json` (if native dependencies are needed)
+ */
+declare function generateDockerfile(options?: DockerfileOptions): string;
+/**
+ * Generates a minimal package.json for native dependencies in the deploy container.
+ */
+declare function generateDeployPackageJson(nativeDependencies: Record<string, string>): string;
+/**
+ * Generates a `.dockerignore` tuned for Kora deploy output.
+ */
+declare function generateDockerIgnore(): string;
+/**
+ * Writes the generated Dockerfile (and package.json if needed) to `.kora/deploy/`.
+ */
+declare function writeDockerfileArtifact(deployDirectory: string, options?: DockerfileOptions): Promise<string>;
+/**
+ * Writes the generated `.dockerignore` to `.kora/deploy/.dockerignore`.
+ */
+declare function writeDockerIgnoreArtifact(deployDirectory: string): Promise<string>;
+
+/**
+ * Configuration options used to render `fly.toml`.
+ */
+interface FlyTomlOptions {
+    appName: string;
+    region: string;
+    internalPort?: number;
+}
+/**
+ * Generates a minimal Fly.io configuration file for Kora sync apps.
+ */
+declare function generateFlyToml(options: FlyTomlOptions): string;
+/**
+ * Writes `fly.toml` into `.kora/deploy`.
+ */
+declare function writeFlyTomlArtifact(deployDirectory: string, options: FlyTomlOptions): Promise<string>;
+
+/**
+ * Configuration used to render `railway.json`.
+ */
+interface RailwayJsonOptions {
+    appName: string;
+    region?: string;
+    environment?: string;
+    startCommand?: string;
+    healthcheckPath?: string;
+}
+/**
+ * Generates Railway deployment configuration in JSON format.
+ */
+declare function generateRailwayJson(options: RailwayJsonOptions): string;
+/**
+ * Writes `railway.json` into `.kora/deploy`.
+ */
+declare function writeRailwayJsonArtifact(deployDirectory: string, options: RailwayJsonOptions): Promise<string>;
+
+/**
+ * Inputs used to execute a client build through Vite.
+ */
+interface ClientBuildOptions {
+    projectRoot: string;
+    outDir: string;
+    mode?: 'development' | 'production';
+}
+/**
+ * Result returned after a successful Vite build.
+ */
+interface ClientBuildResult {
+    outDir: string;
+}
+/**
+ * Builds the client bundle with the project's local Vite installation.
+ *
+ * After Vite completes, patches the output to ensure SQLite WASM assets
+ * are present. The template's sqliteWasmHotfix Vite plugin writes to the
+ * default `dist/` directory, but `kora deploy` redirects output to
+ * `.kora/deploy/dist/`. This post-build step fills in any missing assets.
+ */
+declare function buildClient(options: ClientBuildOptions): Promise<ClientBuildResult>;
+
+/**
+ * Options used to produce a deployable server bundle artifact.
+ */
+interface ServerBundleOptions {
+    projectRoot: string;
+    deployDirectory: string;
+    entryFileCandidates?: readonly string[];
+}
+/**
+ * Result details for the generated server bundle artifact.
+ */
+interface ServerBundleResult {
+    entryFilePath: string;
+    outputFilePath: string;
+}
+/**
+ * Bundles the server entry into a single deployable JavaScript file.
+ */
+declare function bundleServer(options: ServerBundleOptions): Promise<ServerBundleResult>;
+
+interface ProjectNameValidationResult {
+    valid: boolean;
+    issues: readonly string[];
+}
+/**
+ * Validates a project name for scaffolded package creation.
+ *
+ * The create command uses this validation before writing files so users get a
+ * clear, early error if the name cannot be used as an npm package name.
+ */
+declare function validateProjectName(name: string): ProjectNameValidationResult;
+
+type FrameworkOption = 'react' | 'vue' | 'svelte' | 'solid';
+type AuthOption = 'none' | 'email-password' | 'oauth';
+type DatabaseOption = 'none' | 'sqlite' | 'postgres';
+type DatabaseProviderOption = 'none' | 'local' | 'supabase' | 'neon' | 'railway' | 'vercel-postgres' | 'custom';
+interface TemplateSelectionInput {
+    tailwind: boolean;
+    sync: boolean;
+    db: DatabaseOption;
+}
+/**
+ * Converts high-level scaffold selections into the currently supported
+ * concrete template names.
+ */
+declare function determineTemplateFromSelections(input: TemplateSelectionInput): TemplateName;
+declare function isFrameworkValue(value: string): value is FrameworkOption;
+declare function isAuthValue(value: string): value is AuthOption;
+declare function isDatabaseValue(value: string): value is DatabaseOption;
+declare function isDatabaseProviderValue(value: string): value is DatabaseProviderOption;
+
+interface SelectOption<T extends string> {
+    label: string;
+    value: T;
+    hint?: string;
+    disabled?: boolean;
+}
+interface PromptClient {
+    text(message: string, defaultValue?: string): Promise<string>;
+    select<T extends string>(message: string, options: readonly SelectOption<T>[]): Promise<T>;
+    confirm(message: string, defaultValue?: boolean): Promise<boolean>;
+    intro(message: string): void;
+    outro(message: string): void;
+}
+declare class PromptCancelledError extends Error {
+    constructor(message?: string);
+}
+/**
+ * Prompt client backed by the current readline helpers.
+ *
+ * Phase 12 will introduce a richer prompt backend. This adapter keeps command
+ * logic decoupled from the prompt implementation so we can migrate without
+ * reshaping command behavior.
+ */
+declare class ReadlinePromptClient implements PromptClient {
+    text(message: string, defaultValue?: string): Promise<string>;
+    select<T extends string>(message: string, options: readonly SelectOption<T>[]): Promise<T>;
+    confirm(message: string, defaultValue?: boolean): Promise<boolean>;
+    intro(message: string): void;
+    outro(message: string): void;
+}
+/**
+ * Returns the default prompt client for interactive CLI flows.
+ */
+declare function createPromptClient(): PromptClient;
+/**
+ * Prompt client backed by @clack/prompts for richer interactive UX.
+ * Falls back to readline in non-interactive contexts.
+ */
+declare class ClackPromptClient implements PromptClient {
+    text(message: string, defaultValue?: string): Promise<string>;
+    select<T extends string>(message: string, options: readonly SelectOption<T>[]): Promise<T>;
+    confirm(message: string, defaultValue?: boolean): Promise<boolean>;
+    intro(message: string): void;
+    outro(message: string): void;
+}
+
+interface CreatePreferences {
+    framework: FrameworkOption;
+    tailwind: boolean;
+    sync: boolean;
+    db: DatabaseOption;
+    dbProvider: DatabaseProviderOption;
+    auth: AuthOption;
+    packageManager: PackageManager;
+}
+/**
+ * Preference store for scaffold-time defaults in `create-kora-app`.
+ */
+declare class PreferenceStore {
+    private readonly store;
+    constructor();
+    getCreatePreferences(): CreatePreferences | null;
+    saveCreatePreferences(preferences: CreatePreferences): void;
+    clearCreatePreferences(): void;
+}
+/**
+ * Gets preferences from storage or returns defaults when not available.
+ */
+declare function getCreatePreferencesOrDefault(store: PreferenceStore): CreatePreferences;
+declare function getDefaultCreatePreferences(): CreatePreferences;
+
+interface CreateFlags {
+    framework?: string;
+    auth?: string;
+    db?: string;
+    dbProvider?: string;
+    tailwind?: boolean;
+    sync?: boolean;
+    useDefaults: boolean;
+}
+interface PreferenceResolutionResult {
+    framework: FrameworkOption;
+    auth: AuthOption;
+    db: DatabaseOption;
+    dbProvider: DatabaseProviderOption;
+    tailwind: boolean;
+    sync: boolean;
+    template: ReturnType<typeof determineTemplateFromSelections>;
+    usedStoredPreferences: boolean;
+}
+/**
+ * Resolves scaffold options with precedence:
+ * CLI flags > --yes defaults > stored preferences > interactive prompts.
+ */
+declare function resolveCreatePreferencesFlow(params: {
+    flags: CreateFlags;
+    prompts: PromptClient;
+    store: PreferenceStore;
+}): Promise<PreferenceResolutionResult>;
+declare function shouldSavePreferences(flags: CreateFlags): boolean;
+declare function saveResolvedPreferences(store: PreferenceStore, resolution: Omit<PreferenceResolutionResult, 'template' | 'usedStoredPreferences'> & {
+    packageManager: CreatePreferences['packageManager'];
+}): void;
+
+interface SyncProviderPresetOptions {
+    targetDir: string;
+    template: TemplateName;
+    db: DatabaseOption;
+    dbProvider: DatabaseProviderOption;
+}
+/**
+ * Applies provider-specific sync scaffolding adjustments after template copy.
+ *
+ * This is a lightweight bridge until template-layer composition lands.
+ * Today we only specialize the sync server template when Postgres is selected.
+ */
+declare function applySyncProviderPreset(options: SyncProviderPresetOptions): Promise<void>;
+
+export { type AuthOption, type BuildArtifacts, ClackPromptClient, CliError, type ClientBuildOptions, type ClientBuildResult, type ContextAwareDeployAdapter, type CreateFlags, type CreatePreferences, DEPLOY_PLATFORMS, type DatabaseOption, type DatabaseProviderOption, type DeployAdapter, type DeployPlatform, type DeployResult, type DeployState, type DeployStateCreateInput, type DeployStatePatch, type DeploymentStatus, DevServerError, type DockerfileOptions, FlyAdapter, type FlyAdapterContext, type FlyAdapterOptions, type FlyCommandResult, type FlyCommandRunner, type FlyTomlOptions, type FrameworkOption, InvalidProjectError, type LogLine, type LogOptions, NodeFlyCommandRunner, NodeRailwayCommandRunner, PACKAGE_MANAGERS, type PackageManager, type PreferenceResolutionResult, PreferenceStore, type ProjectConfig, ProjectExistsError, type ProjectNameValidationResult, PromptCancelledError, type PromptClient, type ProvisionResult, RailwayAdapter, type RailwayAdapterContext, type RailwayAdapterOptions, type RailwayCommandResult, type RailwayCommandRunner, type RailwayJsonOptions, ReadlinePromptClient, SchemaNotFoundError, type SelectOption, type ServerBundleOptions, type ServerBundleResult, StubDeployAdapter, TEMPLATES, TEMPLATE_INFO, type TemplateContext, type TemplateInfo, type TemplateName, type TemplateSelectionInput, applySyncProviderPreset, buildClient, bundleServer, createDeployAdapter, createPromptClient, deployCommand, determineTemplateFromSelections, generateDeployPackageJson, generateDockerIgnore, generateDockerfile, generateFlyToml, generateRailwayJson, generateTypes, getCreatePreferencesOrDefault, getDefaultCreatePreferences, isAuthValue, isDatabaseProviderValue, isDatabaseValue, isDeployPlatform, isFrameworkValue, readDeployState, resetDeployState, resolveCreatePreferencesFlow, resolveDeployDirectory, resolveDeployStatePath, saveResolvedPreferences, shouldSavePreferences, updateDeployState, validateProjectName, writeDeployState, writeDockerIgnoreArtifact, writeDockerfileArtifact, writeFlyTomlArtifact, writeRailwayJsonArtifact };