electron-cli 0.2.6 → 0.3.0-alpha.0

package/src/commands/doctor.rs

@@ -0,0 +1,355 @@
+use std::process::Command;
+
+use anyhow::Result;
+use serde::Serialize;
+
+use crate::{cli::CommandArgs, output, project::ProjectSnapshot};
+
+#[derive(Debug, Serialize)]
+struct DoctorReport {
+    project: ProjectSnapshot,
+    summary: DoctorSummary,
+    checks: Vec<Check>,
+}
+
+#[derive(Debug, Serialize)]
+struct DoctorSummary {
+    pass: usize,
+    warn: usize,
+    fail: usize,
+    info: usize,
+}
+
+#[derive(Debug, Serialize)]
+struct Check {
+    id: &'static str,
+    level: CheckLevel,
+    message: String,
+    detail: Option<String>,
+    remedy: Option<String>,
+}
+
+#[derive(Debug, Serialize, PartialEq, Eq)]
+#[serde(rename_all = "lowercase")]
+enum CheckLevel {
+    Pass,
+    Warn,
+    Fail,
+    Info,
+}
+
+pub fn run(args: CommandArgs) -> Result<()> {
+    let snapshot = crate::project::inspect(&args.cwd)?;
+    let report = build_report(snapshot);
+
+    if args.json {
+        output::json(&report)
+    } else {
+        print_report(&report);
+        Ok(())
+    }
+}
+
+fn build_report(snapshot: ProjectSnapshot) -> DoctorReport {
+    let mut checks = Vec::new();
+
+    checks.push(match &snapshot.package_json {
+        Some(path) => Check::pass(
+            "package-json",
+            "Found package.json",
+            Some(format!("Using {path}")),
+        ),
+        None => Check::fail(
+            "package-json",
+            "No package.json found",
+            Some("Run this command inside an Electron or JavaScript project.".to_string()),
+            Some("Create a package.json or pass --cwd PATH to an existing project.".to_string()),
+        ),
+    });
+
+    checks.push(match &snapshot.electron_dependency {
+        Some(version) => Check::pass(
+            "electron-dependency",
+            "Electron dependency is declared",
+            Some(format!("electron {version}")),
+        ),
+        None if snapshot.package_json.is_some() => Check::warn(
+            "electron-dependency",
+            "Electron dependency is not declared",
+            Some(
+                "This may be a generic JavaScript project, or Electron may be installed elsewhere."
+                    .to_string(),
+            ),
+            Some(
+                "Install Electron with your package manager if this is an Electron app."
+                    .to_string(),
+            ),
+        ),
+        None => Check::info(
+            "electron-dependency",
+            "Electron dependency could not be checked",
+            Some("No package.json was found.".to_string()),
+        ),
+    });
+
+    checks.push(match &snapshot.main {
+        Some(main) => Check::pass(
+            "main-entry",
+            "Main process entry is declared",
+            Some(format!("package.json main: {main}")),
+        ),
+        None if snapshot.electron_dependency.is_some() => Check::warn(
+            "main-entry",
+            "No package.json main field found",
+            Some("Electron apps usually need a main process entry.".to_string()),
+            Some(
+                "Add a main field, or document why your tooling supplies it another way."
+                    .to_string(),
+            ),
+        ),
+        None => Check::info(
+            "main-entry",
+            "Main process entry is not declared",
+            Some("This only matters for Electron apps.".to_string()),
+        ),
+    });
+
+    checks.push(if snapshot.scripts.contains_key("start") || snapshot.scripts.contains_key("dev") {
+        Check::pass(
+            "dev-script",
+            "Development script is declared",
+            snapshot
+                .scripts
+                .get("start")
+                .or_else(|| snapshot.scripts.get("dev"))
+                .map(|script| format!("script: {script}")),
+        )
+    } else if snapshot.package_json.is_some() {
+        Check::warn(
+            "dev-script",
+            "No start or dev script found",
+            Some("A predictable development script makes the project easier for people and agents to run.".to_string()),
+            Some("Add a start or dev script to package.json.".to_string()),
+        )
+    } else {
+        Check::info(
+            "dev-script",
+            "Development scripts could not be checked",
+            Some("No package.json was found.".to_string()),
+        )
+    });
+
+    checks.push(if snapshot.package_manager.is_some() {
+        Check::pass(
+            "lockfile",
+            "Package manager lockfile detected",
+            snapshot.package_manager.clone(),
+        )
+    } else if snapshot.package_json.is_some() && snapshot.has_javascript_dependencies() {
+        Check::warn(
+            "lockfile",
+            "No package manager lockfile detected",
+            Some("Installs may not be reproducible without a lockfile.".to_string()),
+            Some("Run npm install, pnpm install, yarn install, or bun install.".to_string()),
+        )
+    } else if snapshot.package_json.is_some() {
+        Check::info(
+            "lockfile",
+            "No package manager lockfile detected",
+            Some("No JavaScript dependencies are declared, so a lockfile is optional.".to_string()),
+        )
+    } else {
+        Check::info(
+            "lockfile",
+            "Lockfile could not be checked",
+            Some("No package.json was found.".to_string()),
+        )
+    });
+
+    checks.push(if snapshot.forge_dependencies.is_empty() {
+        Check::info(
+            "forge",
+            "Electron Forge is not declared",
+            Some(
+                "That is fine; electron-cli can inspect projects that use other tooling."
+                    .to_string(),
+            ),
+        )
+    } else {
+        Check::pass(
+            "forge",
+            "Electron Forge dependency detected",
+            Some(
+                snapshot
+                    .forge_dependencies
+                    .keys()
+                    .cloned()
+                    .collect::<Vec<_>>()
+                    .join(", "),
+            ),
+        )
+    });
+
+    checks.push(command_check(
+        "node",
+        &["--version"],
+        "node-runtime",
+        "Node.js is available",
+    ));
+    checks.push(command_check(
+        "npm",
+        &["--version"],
+        "npm-cli",
+        "npm is available",
+    ));
+
+    let summary = DoctorSummary {
+        pass: checks
+            .iter()
+            .filter(|check| check.level == CheckLevel::Pass)
+            .count(),
+        warn: checks
+            .iter()
+            .filter(|check| check.level == CheckLevel::Warn)
+            .count(),
+        fail: checks
+            .iter()
+            .filter(|check| check.level == CheckLevel::Fail)
+            .count(),
+        info: checks
+            .iter()
+            .filter(|check| check.level == CheckLevel::Info)
+            .count(),
+    };
+
+    DoctorReport {
+        project: snapshot,
+        summary,
+        checks,
+    }
+}
+
+fn command_check(
+    command: &'static str,
+    args: &[&str],
+    id: &'static str,
+    success_message: &'static str,
+) -> Check {
+    match Command::new(command).args(args).output() {
+        Ok(output) if output.status.success() => {
+            let version = String::from_utf8_lossy(&output.stdout).trim().to_string();
+            Check::pass(id, success_message, Some(format!("{command} {version}")))
+        }
+        Ok(output) => Check::fail(
+            id,
+            format!("{command} returned a non-zero exit code"),
+            Some(format!("exit status: {}", output.status)),
+            Some(format!("Install or repair {command}.")),
+        ),
+        Err(error) => Check::fail(
+            id,
+            format!("{command} could not be executed"),
+            Some(error.to_string()),
+            Some(format!("Install {command} and make sure it is on PATH.")),
+        ),
+    }
+}
+
+fn print_report(report: &DoctorReport) {
+    println!("electron-cli doctor");
+    println!();
+    println!("Project");
+    println!("  root: {}", report.project.root);
+    match report.project.package_label() {
+        Some(label) => println!("  package: {label}"),
+        None => println!("  package: not found"),
+    }
+
+    println!();
+    println!(
+        "Summary: {} pass, {} warn, {} fail, {} info",
+        report.summary.pass, report.summary.warn, report.summary.fail, report.summary.info
+    );
+    println!();
+    println!("Checks");
+
+    for check in &report.checks {
+        println!(
+            "  {:<4} {:<20} {}",
+            check.level.as_str(),
+            check.id,
+            check.message
+        );
+
+        if let Some(detail) = &check.detail {
+            println!("       detail: {detail}");
+        }
+
+        if let Some(remedy) = &check.remedy {
+            println!("       remedy: {remedy}");
+        }
+    }
+}
+
+impl Check {
+    fn pass(id: &'static str, message: impl Into<String>, detail: Option<String>) -> Self {
+        Self {
+            id,
+            level: CheckLevel::Pass,
+            message: message.into(),
+            detail,
+            remedy: None,
+        }
+    }
+
+    fn warn(
+        id: &'static str,
+        message: impl Into<String>,
+        detail: Option<String>,
+        remedy: Option<String>,
+    ) -> Self {
+        Self {
+            id,
+            level: CheckLevel::Warn,
+            message: message.into(),
+            detail,
+            remedy,
+        }
+    }
+
+    fn fail(
+        id: &'static str,
+        message: impl Into<String>,
+        detail: Option<String>,
+        remedy: Option<String>,
+    ) -> Self {
+        Self {
+            id,
+            level: CheckLevel::Fail,
+            message: message.into(),
+            detail,
+            remedy,
+        }
+    }
+
+    fn info(id: &'static str, message: impl Into<String>, detail: Option<String>) -> Self {
+        Self {
+            id,
+            level: CheckLevel::Info,
+            message: message.into(),
+            detail,
+            remedy: None,
+        }
+    }
+}
+
+impl CheckLevel {
+    fn as_str(&self) -> &'static str {
+        match self {
+            CheckLevel::Pass => "PASS",
+            CheckLevel::Warn => "WARN",
+            CheckLevel::Fail => "FAIL",
+            CheckLevel::Info => "INFO",
+        }
+    }
+}

package/src/commands/inspect.rs

@@ -0,0 +1,63 @@
+use anyhow::Result;
+
+use crate::{cli::CommandArgs, output, project};
+
+pub fn run(args: CommandArgs) -> Result<()> {
+    let snapshot = project::inspect(&args.cwd)?;
+
+    if args.json {
+        output::json(&snapshot)
+    } else {
+        println!("electron-cli inspect");
+        println!();
+        println!("Project");
+        println!("  root: {}", snapshot.root);
+
+        match &snapshot.package_json {
+            Some(path) => println!("  package.json: {path}"),
+            None => println!("  package.json: not found"),
+        }
+
+        if let Some(package) = snapshot.package_label() {
+            println!("  package: {package}");
+        }
+
+        if let Some(package_manager) = &snapshot.package_manager {
+            println!("  package manager: {package_manager}");
+        }
+
+        println!();
+        println!("Electron");
+        match &snapshot.electron_dependency {
+            Some(version) => println!("  electron: {version}"),
+            None => println!("  electron: not declared"),
+        }
+
+        if snapshot.forge_dependencies.is_empty() {
+            println!("  forge: not declared");
+        } else {
+            println!("  forge:");
+            for (name, version) in &snapshot.forge_dependencies {
+                println!("    {name}: {version}");
+            }
+        }
+
+        if !snapshot.scripts.is_empty() {
+            println!();
+            println!("Scripts");
+            for (name, script) in &snapshot.scripts {
+                println!("  {name}: {script}");
+            }
+        }
+
+        if !snapshot.signals.is_empty() {
+            println!();
+            println!("Signals");
+            for signal in &snapshot.signals {
+                println!("  {signal}");
+            }
+        }
+
+        Ok(())
+    }
+}

package/src/commands/mod.rs

@@ -0,0 +1,3 @@
+pub mod doctor;
+pub mod inspect;
+pub mod plan;

package/src/commands/plan.rs

@@ -0,0 +1,235 @@
+use std::collections::BTreeMap;
+
+use anyhow::Result;
+use serde::Serialize;
+
+use crate::{cli::CommandArgs, output, project};
+
+#[derive(Debug, Serialize)]
+struct PlanReport {
+    project_type: ProjectType,
+    recommended_commands: BTreeMap<String, String>,
+    missing: Vec<String>,
+    risks: Vec<String>,
+    notes: Vec<String>,
+}
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "kebab-case")]
+enum ProjectType {
+    ElectronForge,
+    Electron,
+    JavaScript,
+    Unknown,
+}
+
+pub fn run(args: CommandArgs) -> Result<()> {
+    let snapshot = project::inspect(&args.cwd)?;
+    let report = build_report(&snapshot);
+
+    if args.json {
+        output::json(&report)
+    } else {
+        println!("electron-cli plan");
+        println!();
+        println!("Project");
+        println!("  root: {}", snapshot.root);
+        match snapshot.package_label() {
+            Some(label) => println!("  package: {label}"),
+            None => println!("  package: not found"),
+        }
+        println!("  type: {}", report.project_type.as_str());
+
+        if !report.recommended_commands.is_empty() {
+            println!();
+            println!("Recommended Commands");
+            for (name, command) in &report.recommended_commands {
+                println!("  {name}: {command}");
+            }
+        }
+
+        if !report.missing.is_empty() {
+            println!();
+            println!("Missing");
+            for item in &report.missing {
+                println!("  {item}");
+            }
+        }
+
+        if !report.risks.is_empty() {
+            println!();
+            println!("Risks");
+            for risk in &report.risks {
+                println!("  {risk}");
+            }
+        }
+
+        if !report.notes.is_empty() {
+            println!();
+            println!("Notes");
+            for note in &report.notes {
+                println!("  {note}");
+            }
+        }
+
+        Ok(())
+    }
+}
+
+fn build_report(snapshot: &project::ProjectSnapshot) -> PlanReport {
+    let project_type = detect_project_type(snapshot);
+    let mut recommended_commands = BTreeMap::new();
+    let mut missing = Vec::new();
+    let mut risks = Vec::new();
+    let mut notes = Vec::new();
+
+    if let Some(script) = first_script(snapshot, &["start", "dev"]) {
+        recommended_commands.insert("dev".to_string(), run_script(snapshot, script));
+    } else if snapshot.electron_dependency.is_some() && snapshot.main.is_some() {
+        recommended_commands.insert("dev".to_string(), package_exec(snapshot, "electron ."));
+        missing.push(
+            "Add a start or dev script so humans and agents have a stable entrypoint.".to_string(),
+        );
+    } else {
+        missing.push("No start or dev script was found.".to_string());
+    }
+
+    if let Some(script) = first_script(snapshot, &["package", "pack"]) {
+        recommended_commands.insert("package".to_string(), run_script(snapshot, script));
+    } else if matches!(project_type, ProjectType::ElectronForge) {
+        missing.push(
+            "No package script was found even though Electron Forge is declared.".to_string(),
+        );
+    }
+
+    if let Some(script) = first_script(snapshot, &["make", "dist"]) {
+        recommended_commands.insert("make".to_string(), run_script(snapshot, script));
+    }
+
+    recommended_commands.insert(
+        "diagnostics".to_string(),
+        "electron-cli doctor --json".to_string(),
+    );
+    recommended_commands.insert(
+        "inspect".to_string(),
+        "electron-cli inspect --json".to_string(),
+    );
+
+    if snapshot.package_json.is_none() {
+        risks.push(
+            "No package.json was found, so Electron project detection is limited.".to_string(),
+        );
+    }
+
+    if snapshot.electron_dependency.is_none() {
+        risks.push("Electron is not declared in package dependencies.".to_string());
+    }
+
+    if snapshot.electron_dependency.is_some() && snapshot.main.is_none() {
+        risks.push("Electron is declared, but package.json has no main process entry.".to_string());
+    }
+
+    if snapshot.has_javascript_dependencies() && snapshot.package_manager.is_none() {
+        risks.push("JavaScript dependencies are declared, but no lockfile was found.".to_string());
+    }
+
+    if matches!(project_type, ProjectType::ElectronForge) {
+        notes.push("Electron Forge was detected; wrapping Forge commands is the safest workflow path today.".to_string());
+    } else if snapshot.electron_dependency.is_some() {
+        notes.push("Electron was detected without Forge; prefer inspection before choosing a packaging path.".to_string());
+    } else {
+        notes.push("This does not currently look like an Electron app.".to_string());
+    }
+
+    PlanReport {
+        project_type,
+        recommended_commands,
+        missing,
+        risks,
+        notes,
+    }
+}
+
+fn detect_project_type(snapshot: &project::ProjectSnapshot) -> ProjectType {
+    if !snapshot.forge_dependencies.is_empty()
+        || snapshot
+            .scripts
+            .values()
+            .any(|script| script.contains("electron-forge"))
+    {
+        ProjectType::ElectronForge
+    } else if snapshot.electron_dependency.is_some() {
+        ProjectType::Electron
+    } else if snapshot.package_json.is_some() {
+        ProjectType::JavaScript
+    } else {
+        ProjectType::Unknown
+    }
+}
+
+fn first_script<'a>(snapshot: &project::ProjectSnapshot, names: &'a [&'a str]) -> Option<&'a str> {
+    names
+        .iter()
+        .copied()
+        .find(|name| snapshot.scripts.contains_key(*name))
+}
+
+fn run_script(snapshot: &project::ProjectSnapshot, script: &str) -> String {
+    match snapshot.package_manager.as_deref() {
+        Some("bun") => format!("bun run {script}"),
+        Some("pnpm") => format!("pnpm run {script}"),
+        Some("yarn") => format!("yarn run {script}"),
+        Some("npm") | None => format!("npm run {script}"),
+        Some(package_manager) => format!("{package_manager} run {script}"),
+    }
+}
+
+fn package_exec(snapshot: &project::ProjectSnapshot, command: &str) -> String {
+    match snapshot.package_manager.as_deref() {
+        Some("bun") => format!("bunx {command}"),
+        Some("pnpm") => format!("pnpm exec {command}"),
+        Some("yarn") => format!("yarn {command}"),
+        Some("npm") | None => format!("npx {command}"),
+        Some(package_manager) => format!("{package_manager} exec {command}"),
+    }
+}
+
+impl ProjectType {
+    fn as_str(&self) -> &'static str {
+        match self {
+            ProjectType::ElectronForge => "electron-forge",
+            ProjectType::Electron => "electron",
+            ProjectType::JavaScript => "javascript",
+            ProjectType::Unknown => "unknown",
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use std::path::Path;
+
+    use super::*;
+
+    #[test]
+    fn plans_for_electron_forge_fixture() {
+        let fixture = Path::new(env!("CARGO_MANIFEST_DIR")).join("tests/fixtures/electron-forge");
+        let snapshot = project::inspect(&fixture).expect("fixture should inspect");
+
+        let report = build_report(&snapshot);
+
+        assert!(matches!(report.project_type, ProjectType::ElectronForge));
+        assert_eq!(
+            report.recommended_commands.get("dev").map(String::as_str),
+            Some("npm run start")
+        );
+        assert_eq!(
+            report
+                .recommended_commands
+                .get("package")
+                .map(String::as_str),
+            Some("npm run package")
+        );
+        assert!(report.risks.is_empty());
+    }
+}

package/src/main.rs

@@ -0,0 +1,25 @@
+mod cli;
+mod commands;
+mod output;
+mod project;
+
+use anyhow::Result;
+use clap::Parser;
+use cli::{Cli, Commands};
+
+fn main() {
+    if let Err(error) = run() {
+        eprintln!("error: {error:#}");
+        std::process::exit(1);
+    }
+}
+
+fn run() -> Result<()> {
+    let cli = Cli::parse();
+
+    match cli.command {
+        Commands::Doctor(args) => commands::doctor::run(args),
+        Commands::Inspect(args) => commands::inspect::run(args),
+        Commands::Plan(args) => commands::plan::run(args),
+    }
+}

package/src/output.rs

@@ -0,0 +1,7 @@
+use anyhow::Result;
+use serde::Serialize;
+
+pub fn json(value: &impl Serialize) -> Result<()> {
+    println!("{}", serde_json::to_string_pretty(value)?);
+    Ok(())
+}