electron-cli 0.3.0-alpha.0 → 0.3.0-alpha.2

package/Cargo.lock

@@ -115,7 +115,7 @@ checksum = "1d07550c9036bf2ae0c684c4297d503f838287c83c53686d05370d0e139ae570"
 
 [[package]]
 name = "electron-cli"
-version = "0.3.0-alpha.0"
+version = "0.3.0-alpha.2"
 dependencies = [
  "anyhow",
  "camino",

package/Cargo.toml

@@ -1,10 +1,10 @@
 [package]
 name = "electron-cli"
-version = "0.3.0-alpha.0"
+version = "0.3.0-alpha.2"
 edition = "2021"
 description = "Experimental Rust CLI for Electron project diagnostics and workflow automation"
 license = "MIT"
-repository = "https://github.com/roderik/electron-cli"
+repository = "https://github.com/Ikana/electron-cli"
 
 [dependencies]
 anyhow = "1.0"

package/README.md

@@ -14,17 +14,18 @@ Current commands:
 electron-cli inspect
 electron-cli doctor
 electron-cli plan
+electron-cli init my-app --dry-run
 electron-cli inspect --json
 electron-cli doctor --json
 electron-cli plan --json
+electron-cli init my-app --dry-run --json
 ```
 
 Planned commands:
 
 ```sh
-electron-cli dev
-electron-cli init
 electron-cli package
+electron-cli dev
 electron-cli make
 ```
 
@@ -32,13 +33,19 @@ The planned workflow commands may start by wrapping Electron Forge or other esta
 
 ## Install
 
-During the experimental phase, the npm package runs from Rust source when a prebuilt binary is not available. You need Node.js and Rust installed.
+During the experimental phase, the npm package downloads a prebuilt binary from GitHub Releases when one is available. If a prebuilt binary is not available for your platform, it falls back to running from Rust source.
 
 ```sh
-npm install -g electron-cli
+npm install -g electron-cli@alpha
 electron-cli doctor
 ```
 
+To skip binary download and use the Cargo fallback:
+
+```sh
+ELECTRON_CLI_SKIP_DOWNLOAD=1 npm install -g electron-cli@alpha
+```
+
 For local development:
 
 ```sh
@@ -53,6 +60,7 @@ Or use Cargo directly:
 ```sh
 cargo run -- doctor
 cargo run -- inspect --json
+cargo run -- init my-app --dry-run
 ```
 
 ## Design Goals
@@ -71,8 +79,9 @@ cargo run -- inspect --json
 
 ## JSON Output
 
-Both initial commands support `--json` so agents and scripts can consume project state without scraping terminal output.
+The inspection and planning commands support `--json` so agents and scripts can consume project state without scraping terminal output.
 `plan` is designed around that workflow: it recommends stable commands and reports missing project conventions as structured data.
+`init --dry-run --json` shows the exact create command before running any networked tooling.
 
 ```sh
 electron-cli plan --json

package/bin/electron-cli.js

@@ -7,11 +7,14 @@ const path = require("node:path");
 const root = path.resolve(__dirname, "..");
 const exe = process.platform === "win32" ? "electron-cli.exe" : "electron-cli";
 const args = process.argv.slice(2);
+const envBinary = process.env.ELECTRON_CLI_BINARY;
 
 const candidates = [
+  envBinary,
+  path.join(root, "bin", "downloaded", exe),
   path.join(root, "target", "release", exe),
   path.join(root, "target", "debug", exe),
-];
+].filter(Boolean);
 
 const binary = candidates.find((candidate) => fs.existsSync(candidate));
 
@@ -28,8 +31,8 @@ if (!fs.existsSync(manifest)) {
   process.exit(1);
 }
 
-console.error("electron-cli is experimental and needs Rust to run from npm source packages.");
-console.error("Building/running through cargo; install Rust from https://rustup.rs if this fails.");
+console.error("electron-cli could not find a prebuilt binary for this install.");
+console.error("Building/running through Cargo fallback; install Rust from https://rustup.rs if this fails.");
 
 exitWith(
   spawnSync(cargo, ["run", "--quiet", "--manifest-path", manifest, "--", ...args], {

package/package.json

@@ -1,21 +1,22 @@
 {
   "name": "electron-cli",
-  "version": "0.3.0-alpha.0",
+  "version": "0.3.0-alpha.2",
   "description": "Experimental Rust CLI for Electron project diagnostics and workflow automation",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/roderik/electron-cli.git"
+    "url": "git+https://github.com/Ikana/electron-cli.git"
   },
-  "homepage": "https://github.com/roderik/electron-cli#readme",
+  "homepage": "https://github.com/Ikana/electron-cli#readme",
   "bugs": {
-    "url": "https://github.com/roderik/electron-cli/issues"
+    "url": "https://github.com/Ikana/electron-cli/issues"
   },
   "bin": {
     "electron-cli": "bin/electron-cli.js"
   },
   "files": [
-    "bin",
+    "bin/electron-cli.js",
+    "scripts",
     "src",
     "tests",
     "Cargo.toml",
@@ -30,6 +31,7 @@
     "format": "cargo fmt",
     "lint": "cargo fmt --check && cargo clippy --all-targets -- -D warnings",
     "test": "cargo test",
+    "postinstall": "node scripts/install.js",
     "prepack": "cargo build --release"
   },
   "engines": {

package/scripts/install.js

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+
+const fs = require("node:fs");
+const https = require("node:https");
+const os = require("node:os");
+const path = require("node:path");
+const { spawnSync } = require("node:child_process");
+
+const root = path.resolve(__dirname, "..");
+const packageJson = require(path.join(root, "package.json"));
+const version = packageJson.version;
+const installDir = path.join(root, "bin", "downloaded");
+const exe = process.platform === "win32" ? "electron-cli.exe" : "electron-cli";
+const destination = path.join(installDir, exe);
+const target = resolveTarget();
+
+if (process.env.ELECTRON_CLI_SKIP_DOWNLOAD === "1") {
+  process.exit(0);
+}
+
+if (!target) {
+  warn(`No prebuilt binary is available for ${process.platform}/${process.arch}; Cargo fallback remains available.`);
+  process.exit(0);
+}
+
+const assetName = `electron-cli-v${version}-${target}${process.platform === "win32" ? ".exe" : ""}`;
+const baseUrl = process.env.ELECTRON_CLI_DOWNLOAD_BASE_URL || "https://github.com/Ikana/electron-cli/releases/download";
+const url = `${baseUrl}/v${version}/${assetName}`;
+const tempFile = path.join(os.tmpdir(), `${assetName}.${process.pid}.tmp`);
+
+main().catch((error) => {
+  warn(`Could not install prebuilt binary: ${error.message}`);
+
+  if (process.env.ELECTRON_CLI_STRICT_INSTALL === "1") {
+    process.exit(1);
+  }
+
+  warn("Install completed with Cargo fallback enabled.");
+});
+
+async function main() {
+  fs.mkdirSync(installDir, { recursive: true });
+
+  await download(url, tempFile);
+  fs.renameSync(tempFile, destination);
+
+  if (process.platform !== "win32") {
+    fs.chmodSync(destination, 0o755);
+  }
+
+  const result = spawnSync(destination, ["--version"], { encoding: "utf8" });
+  if (result.error || result.status !== 0) {
+    fs.rmSync(destination, { force: true });
+    throw new Error(result.error ? result.error.message : result.stderr.trim() || "downloaded binary failed verification");
+  }
+
+  console.error(`electron-cli installed prebuilt binary ${assetName}`);
+}
+
+function resolveTarget() {
+  const key = `${process.platform}-${process.arch}`;
+
+  return {
+    "darwin-arm64": "darwin-arm64",
+    "darwin-x64": "darwin-x64",
+    "linux-x64": "linux-x64",
+    "win32-x64": "win32-x64",
+  }[key];
+}
+
+function download(url, destinationPath) {
+  return new Promise((resolve, reject) => {
+    const request = https.get(url, (response) => {
+      if ([301, 302, 303, 307, 308].includes(response.statusCode)) {
+        response.resume();
+        download(response.headers.location, destinationPath).then(resolve, reject);
+        return;
+      }
+
+      if (response.statusCode !== 200) {
+        response.resume();
+        reject(new Error(`download failed with HTTP ${response.statusCode}: ${url}`));
+        return;
+      }
+
+      const file = fs.createWriteStream(destinationPath, { mode: 0o755 });
+      response.pipe(file);
+      file.on("finish", () => file.close(resolve));
+      file.on("error", reject);
+    });
+
+    request.on("error", reject);
+    request.setTimeout(30_000, () => {
+      request.destroy(new Error("download timed out"));
+    });
+  });
+}
+
+function warn(message) {
+  console.error(`electron-cli postinstall: ${message}`);
+}

package/src/cli.rs

@@ -1,6 +1,6 @@
 use std::path::PathBuf;
 
-use clap::{Args, Parser, Subcommand};
+use clap::{Args, Parser, Subcommand, ValueEnum};
 
 #[derive(Debug, Parser)]
 #[command(
@@ -18,6 +18,8 @@ pub struct Cli {
 pub enum Commands {
     /// Check whether the current project looks ready for Electron development.
     Doctor(CommandArgs),
+    /// Bootstrap a new Electron app through the Electron Forge create tooling.
+    Init(InitArgs),
     /// Print a structured snapshot of the current JavaScript/Electron project.
     Inspect(CommandArgs),
     /// Recommend next commands and risks from the project snapshot.
@@ -34,3 +36,66 @@ pub struct CommandArgs {
     #[arg(long)]
     pub json: bool,
 }
+
+#[derive(Debug, Clone, Args)]
+pub struct InitArgs {
+    /// Directory to initialize. Defaults to the current directory.
+    #[arg(default_value = ".", value_name = "DIR")]
+    pub dir: PathBuf,
+
+    /// Directory to run the create command from.
+    #[arg(long, default_value = ".", value_name = "PATH")]
+    pub cwd: PathBuf,
+
+    /// Forge template to use.
+    #[arg(long, short = 't', default_value = "vite-typescript")]
+    pub template: String,
+
+    /// Package manager command strategy to use.
+    #[arg(long, value_enum)]
+    pub package_manager: Option<PackageManager>,
+
+    /// Set a specific Electron version, or use latest/beta/nightly.
+    #[arg(long, value_name = "VERSION")]
+    pub electron_version: Option<String>,
+
+    /// Copy template CI files when the Forge template supports them.
+    #[arg(long)]
+    pub copy_ci_files: bool,
+
+    /// Overwrite an existing target directory.
+    #[arg(long)]
+    pub force: bool,
+
+    /// Skip initializing a git repository in the created project.
+    #[arg(long)]
+    pub skip_git: bool,
+
+    /// Print the command and metadata without creating files.
+    #[arg(long)]
+    pub dry_run: bool,
+
+    /// Emit machine-readable JSON.
+    #[arg(long)]
+    pub json: bool,
+}
+
+#[derive(Debug, Clone, Copy, ValueEnum)]
+#[value(rename_all = "lower")]
+pub enum PackageManager {
+    Npm,
+    Pnpm,
+    Yarn,
+    Bun,
+}
+
+impl PackageManager {
+    pub fn as_str(self) -> &'static str {
+        match self {
+            PackageManager::Npm => "npm",
+            PackageManager::Pnpm => "pnpm",
+            PackageManager::Yarn => "yarn",
+            PackageManager::Bun => "bun",
+        }
+    }
+}

package/src/commands/init.rs

@@ -0,0 +1,398 @@
+use std::{
+    fs,
+    path::{Path, PathBuf},
+    process::Command,
+};
+
+use anyhow::{bail, Context, Result};
+use camino::Utf8PathBuf;
+use serde::Serialize;
+
+use crate::{
+    cli::{InitArgs, PackageManager},
+    output,
+};
+
+#[derive(Debug, Serialize)]
+struct InitReport {
+    cwd: Utf8PathBuf,
+    target_dir: Utf8PathBuf,
+    target_arg: String,
+    template: String,
+    package_manager: String,
+    dry_run: bool,
+    command: Vec<String>,
+    command_display: String,
+    post_create_files: Vec<String>,
+    next_steps: Vec<String>,
+    warnings: Vec<String>,
+    status: InitStatus,
+}
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "kebab-case")]
+enum InitStatus {
+    Planned,
+    Created,
+}
+
+#[derive(Debug, Serialize)]
+struct ElectronCliConfig {
+    version: &'static str,
+    generator: &'static str,
+    template: String,
+    package_manager: String,
+}
+
+pub fn run(args: InitArgs) -> Result<()> {
+    let plan = build_plan(&args)?;
+
+    if args.dry_run {
+        return print_report(&plan, args.json);
+    }
+
+    ensure_target_can_be_created(&plan, args.force)?;
+    execute_plan(&plan)?;
+    write_project_config(&plan)?;
+
+    let report = InitReport {
+        status: InitStatus::Created,
+        ..plan
+    };
+
+    print_report(&report, args.json)
+}
+
+fn build_plan(args: &InitArgs) -> Result<InitReport> {
+    let cwd = args
+        .cwd
+        .canonicalize()
+        .with_context(|| format!("Could not resolve {}", args.cwd.display()))?;
+
+    let target_dir = if args.dir.is_absolute() {
+        args.dir.clone()
+    } else {
+        cwd.join(&args.dir)
+    };
+
+    let target_arg = path_arg(&args.dir);
+    let package_manager = args
+        .package_manager
+        .unwrap_or_else(|| detect_package_manager(&cwd));
+    let command = create_command(package_manager, &target_arg, args);
+    let command_display = display_command(&command);
+    let target_label = target_arg.clone();
+
+    let mut warnings = Vec::new();
+    if target_dir.exists() {
+        warnings.push(format!(
+            "Target directory already exists: {}",
+            target_dir.display()
+        ));
+    }
+
+    if target_dir.exists() && !args.force {
+        warnings
+            .push("Use --force to allow create-electron-app to overwrite the target.".to_string());
+    }
+
+    Ok(InitReport {
+        cwd: utf8_path(cwd)?,
+        target_dir: utf8_path(target_dir)?,
+        target_arg,
+        template: args.template.clone(),
+        package_manager: package_manager.as_str().to_string(),
+        dry_run: args.dry_run,
+        command,
+        command_display,
+        post_create_files: vec![".electron-cli.json".to_string()],
+        next_steps: vec![
+            format!("cd {target_label}"),
+            start_command(package_manager),
+            "electron-cli doctor --json".to_string(),
+        ],
+        warnings,
+        status: InitStatus::Planned,
+    })
+}
+
+fn create_command(
+    package_manager: PackageManager,
+    target_arg: &str,
+    args: &InitArgs,
+) -> Vec<String> {
+    let mut command = match package_manager {
+        PackageManager::Npm => vec![
+            "npx".to_string(),
+            "-y".to_string(),
+            "create-electron-app@latest".to_string(),
+            target_arg.to_string(),
+        ],
+        PackageManager::Pnpm => vec![
+            "pnpm".to_string(),
+            "dlx".to_string(),
+            "create-electron-app@latest".to_string(),
+            target_arg.to_string(),
+        ],
+        PackageManager::Yarn => vec![
+            "yarn".to_string(),
+            "dlx".to_string(),
+            "create-electron-app@latest".to_string(),
+            target_arg.to_string(),
+        ],
+        PackageManager::Bun => vec![
+            "bunx".to_string(),
+            "create-electron-app@latest".to_string(),
+            target_arg.to_string(),
+        ],
+    };
+
+    command.push("--template".to_string());
+    command.push(args.template.clone());
+
+    if args.copy_ci_files {
+        command.push("--copy-ci-files".to_string());
+    }
+
+    if args.force {
+        command.push("--force".to_string());
+    }
+
+    if args.skip_git {
+        command.push("--skip-git".to_string());
+    }
+
+    if let Some(electron_version) = &args.electron_version {
+        command.push("--electron-version".to_string());
+        command.push(electron_version.clone());
+    }
+
+    command
+}
+
+fn execute_plan(plan: &InitReport) -> Result<()> {
+    let (program, args) = plan
+        .command
+        .split_first()
+        .context("Init command could not be constructed")?;
+
+    let status = Command::new(program)
+        .args(args)
+        .current_dir(&plan.cwd)
+        .status()
+        .with_context(|| format!("Could not execute {}", plan.command_display))?;
+
+    if !status.success() {
+        bail!(
+            "Init command failed with {status}: {}",
+            plan.command_display
+        );
+    }
+
+    Ok(())
+}
+
+fn ensure_target_can_be_created(plan: &InitReport, force: bool) -> Result<()> {
+    let target = Path::new(plan.target_dir.as_str());
+
+    if target.exists() && !force {
+        bail!(
+            "Target directory already exists: {}. Use --force to overwrite it.",
+            plan.target_dir
+        );
+    }
+
+    Ok(())
+}
+
+fn write_project_config(plan: &InitReport) -> Result<()> {
+    let config = ElectronCliConfig {
+        version: env!("CARGO_PKG_VERSION"),
+        generator: "create-electron-app@latest",
+        template: plan.template.clone(),
+        package_manager: plan.package_manager.clone(),
+    };
+    let config_path = Path::new(plan.target_dir.as_str()).join(".electron-cli.json");
+    let json = serde_json::to_string_pretty(&config)?;
+
+    fs::write(&config_path, format!("{json}\n"))
+        .with_context(|| format!("Could not write {}", config_path.display()))?;
+
+    Ok(())
+}
+
+fn print_report(report: &InitReport, json: bool) -> Result<()> {
+    if json {
+        return output::json(report);
+    }
+
+    println!("electron-cli init");
+    println!();
+    println!("Project");
+    println!("  cwd: {}", report.cwd);
+    println!("  target: {}", report.target_dir);
+    println!("  template: {}", report.template);
+    println!("  package manager: {}", report.package_manager);
+    println!("  status: {}", report.status.as_str());
+
+    println!();
+    println!("Command");
+    println!("  {}", report.command_display);
+
+    if !report.post_create_files.is_empty() {
+        println!();
+        println!("Post-Create Files");
+        for file in &report.post_create_files {
+            println!("  {file}");
+        }
+    }
+
+    if !report.next_steps.is_empty() {
+        println!();
+        println!("Next Steps");
+        for step in &report.next_steps {
+            println!("  {step}");
+        }
+    }
+
+    if !report.warnings.is_empty() {
+        println!();
+        println!("Warnings");
+        for warning in &report.warnings {
+            println!("  {warning}");
+        }
+    }
+
+    Ok(())
+}
+
+fn detect_package_manager(cwd: &Path) -> PackageManager {
+    if cwd.join("pnpm-lock.yaml").exists() {
+        PackageManager::Pnpm
+    } else if cwd.join("yarn.lock").exists() {
+        PackageManager::Yarn
+    } else if cwd.join("bun.lock").exists() || cwd.join("bun.lockb").exists() {
+        PackageManager::Bun
+    } else {
+        PackageManager::Npm
+    }
+}
+
+fn start_command(package_manager: PackageManager) -> String {
+    match package_manager {
+        PackageManager::Npm => "npm start".to_string(),
+        PackageManager::Pnpm => "pnpm start".to_string(),
+        PackageManager::Yarn => "yarn start".to_string(),
+        PackageManager::Bun => "bun run start".to_string(),
+    }
+}
+
+fn display_command(command: &[String]) -> String {
+    command
+        .iter()
+        .map(|arg| shell_quote(arg))
+        .collect::<Vec<_>>()
+        .join(" ")
+}
+
+fn shell_quote(value: &str) -> String {
+    if value
+        .chars()
+        .all(|char| char.is_ascii_alphanumeric() || matches!(char, '.' | '/' | '-' | '_' | '@'))
+    {
+        value.to_string()
+    } else {
+        format!("'{}'", value.replace('\'', "'\\''"))
+    }
+}
+
+fn path_arg(path: &Path) -> String {
+    path.to_string_lossy().to_string()
+}
+
+fn utf8_path(path: PathBuf) -> Result<Utf8PathBuf> {
+    Utf8PathBuf::from_path_buf(path).map_err(|path| {
+        anyhow::anyhow!(
+            "Path contains invalid UTF-8 and cannot be represented in JSON: {}",
+            path.display()
+        )
+    })
+}
+
+impl InitStatus {
+    fn as_str(&self) -> &'static str {
+        match self {
+            InitStatus::Planned => "planned",
+            InitStatus::Created => "created",
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn builds_default_npm_init_plan() {
+        let args = InitArgs {
+            dir: PathBuf::from("my-app"),
+            cwd: PathBuf::from(env!("CARGO_MANIFEST_DIR")),
+            template: "vite-typescript".to_string(),
+            package_manager: Some(PackageManager::Npm),
+            electron_version: None,
+            copy_ci_files: false,
+            force: false,
+            skip_git: true,
+            dry_run: true,
+            json: true,
+        };
+
+        let plan = build_plan(&args).expect("plan should build");
+
+        assert_eq!(
+            plan.command,
+            vec![
+                "npx",
+                "-y",
+                "create-electron-app@latest",
+                "my-app",
+                "--template",
+                "vite-typescript",
+                "--skip-git",
+            ]
+        );
+        assert_eq!(plan.package_manager, "npm");
+        assert_eq!(
+            plan.next_steps.first().map(String::as_str),
+            Some("cd my-app")
+        );
+    }
+
+    #[test]
+    fn includes_optional_create_flags() {
+        let args = InitArgs {
+            dir: PathBuf::from("desktop app"),
+            cwd: PathBuf::from(env!("CARGO_MANIFEST_DIR")),
+            template: "webpack".to_string(),
+            package_manager: Some(PackageManager::Pnpm),
+            electron_version: Some("latest".to_string()),
+            copy_ci_files: true,
+            force: true,
+            skip_git: true,
+            dry_run: true,
+            json: false,
+        };
+
+        let plan = build_plan(&args).expect("plan should build");
+
+        assert_eq!(plan.command[0], "pnpm");
+        assert!(plan.command.contains(&"--copy-ci-files".to_string()));
+        assert!(plan.command.contains(&"--force".to_string()));
+        assert!(plan.command.contains(&"--electron-version".to_string()));
+        assert!(plan.command_display.contains("'desktop app'"));
+        assert_eq!(
+            plan.next_steps.get(1).map(String::as_str),
+            Some("pnpm start")
+        );
+    }
+}

package/src/commands/mod.rs

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

package/src/main.rs

@@ -19,6 +19,7 @@ fn run() -> Result<()> {
 
     match cli.command {
         Commands::Doctor(args) => commands::doctor::run(args),
+        Commands::Init(args) => commands::init::run(args),
         Commands::Inspect(args) => commands::inspect::run(args),
         Commands::Plan(args) => commands::plan::run(args),
     }