stopgap_cli/

lib.rs

use std::{fmt, fs, io::Write, path::Path};

use anyhow::{Context, Result};
use clap::{Parser, ValueEnum};
use postgres::{Client, NoTls, Row};
use regex::Regex;
use serde_json::{Value, json};

pub const EXIT_DB_CONNECT: u8 = 10;
pub const EXIT_DB_QUERY: u8 = 11;
pub const EXIT_RESPONSE_DECODE: u8 = 12;
pub const EXIT_OUTPUT_FORMAT: u8 = 13;
pub const EXIT_PROJECT_LAYOUT: u8 = 14;

#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize)]
pub struct StopgapExport {
    pub module_path: String,
    pub export_name: String,
    pub function_path: String,
    pub kind: String,
}

#[derive(Debug, Clone, Copy, ValueEnum)]
pub enum OutputMode {
    Human,
    Json,
}

impl fmt::Display for OutputMode {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::Human => write!(f, "human"),
            Self::Json => write!(f, "json"),
        }
    }
}

#[derive(Debug, Parser)]
#[command(name = "stopgap", version, about = "Stopgap deployment CLI")]
pub struct Cli {
    #[arg(long, env = "STOPGAP_DB")]
    pub db: String,

    #[arg(long, value_enum, default_value_t = OutputMode::Human)]
    pub output: OutputMode,

    #[command(subcommand)]
    pub command: Command,
}

#[derive(Debug, clap::Subcommand)]
pub enum Command {
    Deploy {
        #[arg(long, default_value = "prod")]
        env: String,
        #[arg(long = "from-schema")]
        from_schema: String,
        #[arg(long)]
        label: Option<String>,
        #[arg(long)]
        prune: bool,
    },
    Rollback {
        #[arg(long, default_value = "prod")]
        env: String,
        #[arg(long, default_value_t = 1)]
        steps: i32,
        #[arg(long = "to")]
        to_id: Option<i64>,
    },
    Status {
        #[arg(long, default_value = "prod")]
        env: String,
    },
    Deployments {
        #[arg(long, default_value = "prod")]
        env: String,
    },
    Diff {
        #[arg(long, default_value = "prod")]
        env: String,
        #[arg(long = "from-schema")]
        from_schema: String,
    },
}

#[derive(Debug)]
pub enum AppError {
    DbConnect(anyhow::Error),
    DbQuery(anyhow::Error),
    Decode(anyhow::Error),
    Print(anyhow::Error),
    ProjectLayout(anyhow::Error),
}

impl AppError {
    pub fn code(&self) -> u8 {
        match self {
            Self::DbConnect(_) => EXIT_DB_CONNECT,
            Self::DbQuery(_) => EXIT_DB_QUERY,
            Self::Decode(_) => EXIT_RESPONSE_DECODE,
            Self::Print(_) => EXIT_OUTPUT_FORMAT,
            Self::ProjectLayout(_) => EXIT_PROJECT_LAYOUT,
        }
    }
}

impl fmt::Display for AppError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::DbConnect(err) => write!(f, "database connection failed: {err:#}"),
            Self::DbQuery(err) => write!(f, "database command failed: {err:#}"),
            Self::Decode(err) => write!(f, "invalid database response: {err:#}"),
            Self::Print(err) => write!(f, "failed to print output: {err:#}"),
            Self::ProjectLayout(err) => write!(f, "project layout check failed: {err:#}"),
        }
    }
}

pub trait StopgapApi {
    fn deploy(
        &mut self,
        env: &str,
        from_schema: &str,
        label: Option<&str>,
        prune: bool,
        deploy_exports_json: Option<&str>,
    ) -> Result<i64>;

    fn rollback(&mut self, env: &str, steps: i32, to_id: Option<i64>) -> Result<i64>;

    fn status(&mut self, env: &str) -> Result<Option<Value>>;

    fn deployments(&mut self, env: &str) -> Result<Value>;

    fn diff(&mut self, env: &str, from_schema: &str) -> Result<Value>;
}

pub struct PgStopgapApi {
    client: Client,
}

impl PgStopgapApi {
    pub fn connect(db: &str) -> std::result::Result<Self, AppError> {
        let client = Client::connect(db, NoTls).map_err(|err| AppError::DbConnect(err.into()))?;
        Ok(Self { client })
    }
}

impl StopgapApi for PgStopgapApi {
    fn deploy(
        &mut self,
        env: &str,
        from_schema: &str,
        label: Option<&str>,
        prune: bool,
        deploy_exports_json: Option<&str>,
    ) -> Result<i64> {
        let mut tx = self.client.build_transaction().start()?;
        let prune_setting = if prune { "on" } else { "off" };
        tx.batch_execute(&format!("SET LOCAL stopgap.prune = '{prune_setting}'"))?;
        if let Some(raw_exports) = deploy_exports_json {
            tx.execute("SELECT set_config('stopgap.deploy_exports', $1, true)", &[&raw_exports])?;
        }
        let row = tx.query_one(
            "SELECT stopgap.deploy($1, $2, $3) AS deployment_id",
            &[&env, &from_schema, &label],
        )?;
        tx.commit()?;
        Ok(row.get("deployment_id"))
    }

    fn rollback(&mut self, env: &str, steps: i32, to_id: Option<i64>) -> Result<i64> {
        let row = self.client.query_one(
            "SELECT stopgap.rollback($1, $2, $3) AS deployment_id",
            &[&env, &steps, &to_id],
        )?;
        Ok(row.get("deployment_id"))
    }

    fn status(&mut self, env: &str) -> Result<Option<Value>> {
        let row = self.client.query_one("SELECT stopgap.status($1) AS status", &[&env])?;
        read_json_column(&row, "status")
    }

    fn deployments(&mut self, env: &str) -> Result<Value> {
        let row =
            self.client.query_one("SELECT stopgap.deployments($1) AS deployments", &[&env])?;
        read_required_json_column(&row, "deployments")
    }

    fn diff(&mut self, env: &str, from_schema: &str) -> Result<Value> {
        let row =
            self.client.query_one("SELECT stopgap.diff($1, $2) AS diff", &[&env, &from_schema])?;
        read_required_json_column(&row, "diff")
    }
}

pub fn run(cli: Cli, writer: &mut dyn Write) -> std::result::Result<(), AppError> {
    let mut api = PgStopgapApi::connect(&cli.db)?;
    execute_command(cli.command, cli.output, &mut api, writer)
}

pub fn execute_command(
    command: Command,
    output: OutputMode,
    api: &mut dyn StopgapApi,
    writer: &mut dyn Write,
) -> std::result::Result<(), AppError> {
    let project_root =
        std::env::current_dir().map_err(|err| AppError::ProjectLayout(err.into()))?;
    execute_command_with_project_root(command, output, api, writer, &project_root)
}

pub fn execute_command_with_project_root(
    command: Command,
    output: OutputMode,
    api: &mut dyn StopgapApi,
    writer: &mut dyn Write,
    project_root: &Path,
) -> std::result::Result<(), AppError> {
    match command {
        Command::Deploy { env, from_schema, label, prune } => {
            let exports =
                discover_stopgap_exports(project_root).map_err(AppError::ProjectLayout)?;
            let mut module_paths =
                exports.iter().map(|item| item.module_path.clone()).collect::<Vec<_>>();
            module_paths.sort();
            module_paths.dedup();
            let function_paths =
                exports.iter().map(|item| item.function_path.clone()).collect::<Vec<_>>();
            let deploy_exports_json = serde_json::to_string(&exports)
                .map_err(|err| AppError::ProjectLayout(err.into()))?;
            let deployment_id = api
                .deploy(
                    &env,
                    &from_schema,
                    label.as_deref(),
                    prune,
                    Some(deploy_exports_json.as_str()),
                )
                .map_err(AppError::DbQuery)?;
            let payload = json!({
                "command": "deploy",
                "env": env,
                "from_schema": from_schema,
                "source_root": "stopgap",
                "module_count": module_paths.len(),
                "module_paths": module_paths,
                "function_count": exports.len(),
                "function_paths": function_paths,
                "deployment_id": deployment_id,
                "prune": prune,
            });
            print_payload(output, payload, writer, || {
                format!(
                    "deployed env={} from_schema={} deployment_id={} prune={} module_count={} function_count={}",
                    env,
                    from_schema,
                    deployment_id,
                    prune,
                    module_paths.len(),
                    exports.len()
                )
            })
        }
        Command::Rollback { env, steps, to_id } => {
            let deployment_id = api.rollback(&env, steps, to_id).map_err(AppError::DbQuery)?;
            let payload = json!({
                "command": "rollback",
                "env": env,
                "steps": steps,
                "to_id": to_id,
                "deployment_id": deployment_id,
            });
            print_payload(output, payload, writer, || {
                format!(
                    "rolled back env={} target_deployment_id={} steps={}{}",
                    env,
                    deployment_id,
                    steps,
                    to_id.map(|value| format!(" to_id={value}")).unwrap_or_default()
                )
            })
        }
        Command::Status { env } => {
            let status = api.status(&env).map_err(AppError::DbQuery)?;
            let payload = json!({
                "command": "status",
                "env": env,
                "status": status,
            });
            print_payload(output, payload, writer, || {
                status
                    .as_ref()
                    .map(|value| format!("status env={} {}", env, compact_json(value)))
                    .unwrap_or_else(|| format!("status env={} none", env))
            })
        }
        Command::Deployments { env } => {
            let deployments = api.deployments(&env).map_err(AppError::DbQuery)?;
            let count = deployments.as_array().map(|entries| entries.len()).unwrap_or(0);
            let payload = json!({
                "command": "deployments",
                "env": env,
                "count": count,
                "deployments": deployments,
            });
            print_payload(output, payload, writer, || {
                format!("deployments env={} count={}", env, count)
            })
        }
        Command::Diff { env, from_schema } => {
            let diff = api.diff(&env, &from_schema).map_err(AppError::DbQuery)?;
            let payload = json!({
                "command": "diff",
                "env": env,
                "from_schema": from_schema,
                "diff": diff,
            });
            print_payload(output, payload, writer, || {
                format!("diff env={} from_schema={}", env, from_schema)
            })
        }
    }
}

pub fn discover_stopgap_modules(project_root: &Path) -> Result<Vec<String>> {
    let exports = discover_stopgap_exports(project_root)?;
    let mut modules = exports.into_iter().map(|item| item.module_path).collect::<Vec<_>>();
    modules.sort();
    modules.dedup();
    Ok(modules)
}

pub fn discover_stopgap_exports(project_root: &Path) -> Result<Vec<StopgapExport>> {
    let source_root = project_root.join("stopgap");
    if !source_root.is_dir() {
        anyhow::bail!(
            "project not initialized: expected `stopgap/` directory at {}",
            source_root.display()
        );
    }

    let mut exports = Vec::new();
    collect_stopgap_exports(&source_root, &source_root, &mut exports)?;
    if exports.is_empty() {
        anyhow::bail!(
            "no deployable stopgap exports found under {}; expected `export const <name> = query(...)` or `mutation(...)`",
            source_root.display()
        );
    }
    exports.sort_by(|left, right| left.function_path.cmp(&right.function_path));
    exports.dedup_by(|left, right| left.function_path == right.function_path);
    Ok(exports)
}

fn collect_stopgap_exports(
    root: &Path,
    cursor: &Path,
    exports: &mut Vec<StopgapExport>,
) -> Result<()> {
    let mut entries = Vec::new();
    for entry in fs::read_dir(cursor)
        .with_context(|| format!("failed to read stopgap source directory {}", cursor.display()))?
    {
        entries.push(entry?.path());
    }
    entries.sort();

    for path in entries {
        if path.is_dir() {
            collect_stopgap_exports(root, &path, exports)?;
            continue;
        }

        if !is_deployable_ts_module(&path) {
            continue;
        }

        let module_path = normalize_module_path(root, &path)?;
        let source = fs::read_to_string(&path)
            .with_context(|| format!("failed to read stopgap module {}", path.display()))?;
        let module_exports = parse_wrapped_exports(&source, &module_path, &path)?;
        exports.extend(module_exports);
    }

    Ok(())
}

fn parse_wrapped_exports(
    source: &str,
    module_path: &str,
    file_path: &Path,
) -> Result<Vec<StopgapExport>> {
    let wrapped_export_re = Regex::new(
        r"(?m)^\s*export\s+const\s+([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(?:[A-Za-z_][A-Za-z0-9_]*\s*\.\s*)?(query|mutation)\s*(?:<[^\n>]*>)?\s*\(",
    )
    .expect("wrapped export regex should be valid");
    let named_const_export_re =
        Regex::new(r"(?m)^\s*export\s+const\s+([A-Za-z_][A-Za-z0-9_]*)\s*=")
            .expect("named export regex should be valid");

    let mut wrapped_names = std::collections::BTreeSet::new();
    let mut exports = Vec::new();
    for capture in wrapped_export_re.captures_iter(source) {
        let export_name = capture
            .get(1)
            .map(|value| value.as_str().to_string())
            .expect("wrapped export regex always captures export name");
        let kind = capture
            .get(2)
            .map(|value| value.as_str().to_string())
            .expect("wrapped export regex always captures wrapper kind");
        let function_path = format!("{module_path}.{export_name}");
        wrapped_names.insert(export_name.clone());
        exports.push(StopgapExport {
            module_path: module_path.to_string(),
            export_name,
            function_path,
            kind,
        });
    }

    let non_wrapped_exports = named_const_export_re
        .captures_iter(source)
        .filter_map(|capture| capture.get(1).map(|value| value.as_str().to_string()))
        .filter(|name| !wrapped_names.contains(name))
        .collect::<Vec<_>>();

    if !non_wrapped_exports.is_empty() {
        anyhow::bail!(
            "module {} exports non-wrapper symbols ({}) ; wrap exported handlers with query(...) or mutation(...)",
            file_path.display(),
            non_wrapped_exports.join(", ")
        );
    }

    Ok(exports)
}

fn is_deployable_ts_module(path: &Path) -> bool {
    let Some(file_name) = path.file_name().and_then(|name| name.to_str()) else {
        return false;
    };

    file_name.ends_with(".ts") && !file_name.ends_with(".d.ts")
}

fn normalize_module_path(source_root: &Path, module_path: &Path) -> Result<String> {
    let relative = module_path.strip_prefix(source_root).with_context(|| {
        format!("module path {} is not under stopgap root", module_path.display())
    })?;

    let mut segments = Vec::new();
    for component in relative.components() {
        let raw = component.as_os_str().to_str().with_context(|| {
            format!("module path contains non-utf8 component: {}", module_path.display())
        })?;

        if raw.is_empty() {
            continue;
        }

        if raw.ends_with(".ts") {
            segments.push(raw.trim_end_matches(".ts").to_string());
        } else {
            segments.push(raw.to_string());
        }
    }

    if segments.is_empty() {
        anyhow::bail!("module path {} does not resolve to api namespace", module_path.display());
    }

    Ok(format!("api.{}", segments.join(".")))
}

fn print_payload<F>(
    output: OutputMode,
    payload: Value,
    writer: &mut dyn Write,
    human_builder: F,
) -> std::result::Result<(), AppError>
where
    F: FnOnce() -> String,
{
    let rendered = match output {
        OutputMode::Human => human_builder(),
        OutputMode::Json => {
            serde_json::to_string_pretty(&payload).map_err(|err| AppError::Print(err.into()))?
        }
    };
    writeln!(writer, "{rendered}").map_err(|err| AppError::Print(err.into()))
}

fn read_json_column(row: &Row, column: &str) -> Result<Option<Value>> {
    row.try_get(column).with_context(|| format!("column `{column}` is not valid jsonb"))
}

fn read_required_json_column(row: &Row, column: &str) -> Result<Value> {
    read_json_column(row, column)?.with_context(|| format!("column `{column}` unexpectedly null"))
}

pub fn compact_json(value: &Value) -> String {
    serde_json::to_string(value).unwrap_or_else(|_| "{\"error\":\"json-encode-failed\"}".into())
}

#[cfg(test)]
mod tests {
    use super::*;
    use clap::CommandFactory;

    #[test]
    fn cli_exposes_expected_subcommands() {
        let command = Cli::command();
        let names: Vec<_> =
            command.get_subcommands().map(|subcommand| subcommand.get_name().to_string()).collect();
        assert_eq!(names, vec!["deploy", "rollback", "status", "deployments", "diff"]);
    }

    #[test]
    fn compact_json_handles_objects() {
        let rendered = compact_json(&json!({"key": "value"}));
        assert_eq!(rendered, "{\"key\":\"value\"}");
    }

    #[test]
    fn exit_codes_are_stable() {
        assert_eq!(EXIT_DB_CONNECT, 10);
        assert_eq!(EXIT_DB_QUERY, 11);
        assert_eq!(EXIT_RESPONSE_DECODE, 12);
        assert_eq!(EXIT_OUTPUT_FORMAT, 13);
        assert_eq!(EXIT_PROJECT_LAYOUT, 14);
    }

    #[test]
    fn parse_wrapped_exports_finds_query_and_mutation_handlers() {
        let source = r#"
            export const listUsers = query(v.object({}), async () => []);
            export const createUser = mutation(v.object({}), async () => ({ ok: true }));
        "#;

        let exports = parse_wrapped_exports(source, "api.users", Path::new("stopgap/users.ts"))
            .expect("wrapper exports should parse");
        assert_eq!(exports.len(), 2);
        assert_eq!(exports[0].function_path, "api.users.listUsers");
        assert_eq!(exports[0].kind, "query");
        assert_eq!(exports[1].function_path, "api.users.createUser");
        assert_eq!(exports[1].kind, "mutation");
    }

    #[test]
    fn parse_wrapped_exports_rejects_non_wrapper_named_exports() {
        let source = r#"
            export const helper = 1;
            export const listUsers = query(v.object({}), async () => []);
        "#;

        let error = parse_wrapped_exports(source, "api.users", Path::new("stopgap/users.ts"))
            .expect_err("non-wrapper named exports should fail preflight");
        assert!(error.to_string().contains("exports non-wrapper symbols"));
        assert!(error.to_string().contains("helper"));
    }
}