@engramresearch/srun 0.1.0

package/README.md

@@ -0,0 +1,146 @@
+# srun
+
+`srun` is a Universal Smart Project Runner. It translates a developer intent into the concrete command for the current project.
+
+```bash
+srun dev
+srun build
+srun installer
+srun test
+srun lint
+srun format
+srun info
+```
+
+The goal is to reduce cognitive load when switching between projects, package managers, frameworks, and custom script names.
+
+## Install locally
+
+With Cargo:
+
+```bash
+cargo install --path .
+```
+
+With npm from the project directory:
+
+```bash
+npm install -g .
+```
+
+After publishing:
+
+```bash
+npm install -g @engramresearch/srun
+```
+
+Note: the npm package currently builds the Rust binary during install, so Rust/Cargo must be available on the target machine.
+
+Or run during development:
+
+```bash
+cargo run -- info
+cargo run -- dev --dry-run
+```
+
+## What it detects
+
+Package managers:
+
+- `pnpm-lock.yaml` -> `pnpm`
+- `bun.lockb` or `bun.lock` -> `bun`
+- `yarn.lock` -> `yarn`
+- `package-lock.json` -> `npm`
+- `package.json` without lockfile -> `npm` with warning
+
+If multiple lockfiles exist, priority is:
+
+```text
+pnpm > bun > yarn > npm
+```
+
+Project markers:
+
+- Electron: `electron`, `electron-builder`, `electron-vite`, `electron/`, `electron.vite.config.*`
+- Tauri: `src-tauri/`, `tauri.conf.json`, tauri scripts/dependencies
+- Next.js: `next.config.*` or `next`
+- Vite: `vite.config.*` or `vite`
+- TurboRepo: `turbo.json`
+- NX: `nx.json`
+- Monorepo: `apps/`, `packages/`, TurboRepo or NX markers
+- Cargo-only: `Cargo.toml` without `package.json`
+
+## Resolution examples
+
+Next.js:
+
+```json
+{
+  "scripts": {
+    "dev": "next dev"
+  }
+}
+```
+
+```bash
+srun dev --dry-run
+# pnpm run dev
+```
+
+Electron:
+
+```json
+{
+  "scripts": {
+    "dev": "vite",
+    "dev:electron": "electron-vite dev"
+  }
+}
+```
+
+```bash
+srun dev --dry-run
+# pnpm run dev:electron
+```
+
+Tauri:
+
+```json
+{
+  "scripts": {
+    "tauri:dev": "tauri dev"
+  }
+}
+```
+
+```bash
+srun dev --dry-run
+# pnpm run tauri:dev
+```
+
+Cargo-only:
+
+```bash
+srun dev --dry-run
+# cargo run
+```
+
+## Info and verbose mode
+
+```bash
+srun info
+```
+
+Prints project type, package manager, warnings, and resolved commands.
+
+```bash
+srun dev --verbose --dry-run
+```
+
+Shows detection and resolution phases before printing the command.
+
+## Current limitations
+
+- Monorepo scopes such as `srun dev web` are detected as a future extension but not fully implemented yet.
+- Interactive fallback for custom scripts is not implemented; `srun` reports candidates instead of guessing.
+- Colors and shell integration are intentionally omitted from the MVP.

package/npm/postinstall.js

@@ -0,0 +1,18 @@
+const { spawnSync } = require("node:child_process");
+const { resolve } = require("node:path");
+
+const root = resolve(__dirname, "..");
+
+const result = spawnSync("cargo", ["build", "--release"], {
+  cwd: root,
+  stdio: "inherit",
+  shell: process.platform === "win32",
+});
+
+if (result.error) {
+  console.error("srun: cargo is required to build the npm package binary.");
+  console.error(`srun: ${result.error.message}`);
+  process.exit(1);
+}
+
+process.exit(result.status ?? 1);

package/npm/srun.js

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+const { spawnSync } = require("node:child_process");
+const { existsSync } = require("node:fs");
+const { join, resolve } = require("node:path");
+
+const root = resolve(__dirname, "..");
+const binary = join(root, "target", "release", process.platform === "win32" ? "srun.exe" : "srun");
+
+if (!existsSync(binary)) {
+  const result = spawnSync("cargo", ["build", "--release"], {
+    cwd: root,
+    stdio: "inherit",
+    shell: process.platform === "win32",
+  });
+
+  if (result.error) {
+    console.error(`srun: failed to build Rust binary: ${result.error.message}`);
+    process.exit(1);
+  }
+
+  if (result.status !== 0) {
+    process.exit(result.status ?? 1);
+  }
+}
+
+const result = spawnSync(binary, process.argv.slice(2), {
+  cwd: process.cwd(),
+  stdio: "inherit",
+});
+
+if (result.error) {
+  console.error(`srun: failed to execute binary: ${result.error.message}`);
+  process.exit(1);
+}
+
+process.exit(result.status ?? 1);

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@engramresearch/srun",
+  "version": "0.1.0",
+  "description": "Universal Smart Project Runner",
+  "license": "MIT",
+  "bin": {
+    "srun": "npm/srun.js"
+  },
+  "scripts": {
+    "postinstall": "node npm/postinstall.js",
+    "build:binary": "cargo build --release",
+    "dev": "cargo run",
+    "build": "cargo build",
+    "test": "cargo test",
+    "lint": "cargo clippy",
+    "format": "cargo fmt"
+  },
+  "files": [
+    "Cargo.toml",
+    "Cargo.lock",
+    "src",
+    "npm",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "cli",
+    "runner",
+    "devtools",
+    "rust",
+    "npm",
+    "pnpm",
+    "electron",
+    "tauri"
+  ],
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/cli.rs

@@ -0,0 +1,135 @@
+use crate::detect::detect_project;
+use crate::exec::run_command;
+use crate::model::{Intent, ProjectInfo, ResolvedCommand, SrunError};
+use crate::resolve::resolve_intent;
+use clap::{Args, Parser, Subcommand};
+use std::path::PathBuf;
+
+#[derive(Debug, Parser)]
+#[command(name = "srun", about = "Universal Smart Project Runner")]
+pub struct Cli {
+    #[arg(long, global = true, default_value = ".")]
+    pub root: PathBuf,
+
+    #[command(subcommand)]
+    pub command: Command,
+}
+
+#[derive(Debug, Subcommand)]
+pub enum Command {
+    Dev(RunArgs),
+    Build(RunArgs),
+    Installer(RunArgs),
+    Test(RunArgs),
+    Lint(RunArgs),
+    Format(RunArgs),
+    Info,
+}
+
+#[derive(Debug, Args, Clone, Copy)]
+pub struct RunArgs {
+    #[arg(long)]
+    pub dry_run: bool,
+
+    #[arg(long)]
+    pub verbose: bool,
+}
+
+pub fn run(cli: Cli) -> Result<i32, SrunError> {
+    let project = detect_project(&cli.root)?;
+
+    match cli.command {
+        Command::Info => {
+            print_info(&project);
+            Ok(0)
+        }
+        Command::Dev(args) => run_intent(&project, Intent::Dev, args),
+        Command::Build(args) => run_intent(&project, Intent::Build, args),
+        Command::Installer(args) => run_intent(&project, Intent::Installer, args),
+        Command::Test(args) => run_intent(&project, Intent::Test, args),
+        Command::Lint(args) => run_intent(&project, Intent::Lint, args),
+        Command::Format(args) => run_intent(&project, Intent::Format, args),
+    }
+}
+
+fn run_intent(project: &ProjectInfo, intent: Intent, args: RunArgs) -> Result<i32, SrunError> {
+    if args.verbose {
+        print_detect(project);
+    }
+
+    let resolved = resolve_intent(project, intent)?;
+
+    if args.verbose {
+        println!("[resolve]");
+        println!("selected: {}", resolved.command.display());
+        println!("reason: {}", resolved.reason);
+        println!();
+    }
+
+    if args.dry_run {
+        println!("{}", resolved.command.display());
+        return Ok(0);
+    }
+
+    if args.verbose {
+        println!("[exec]");
+        println!("{}", resolved.command.display());
+        println!();
+    }
+
+    let status = run_command(&resolved.command, &project.root)?;
+    Ok(status.code().unwrap_or(1))
+}
+
+pub fn print_info(project: &ProjectInfo) {
+    println!("Project Type: {}", project.project_type());
+    println!(
+        "Package Manager: {}",
+        project
+            .package_manager
+            .map(|package_manager| package_manager.label())
+            .unwrap_or("none")
+    );
+
+    if !project.warnings.is_empty() {
+        println!();
+        println!("Warnings:");
+        for warning in &project.warnings {
+            println!("  - {}", warning);
+        }
+    }
+
+    println!();
+    println!("Resolved Commands:");
+    for intent in Intent::EXECUTABLE {
+        print_resolved_line(project, intent);
+    }
+}
+
+fn print_resolved_line(project: &ProjectInfo, intent: Intent) {
+    match resolve_intent(project, intent) {
+        Ok(resolved) => println!("{}:\n  {}", intent.label(), resolved.command.display()),
+        Err(error) => println!("{}:\n  unavailable ({})", intent.label(), error),
+    }
+}
+
+fn print_detect(project: &ProjectInfo) {
+    println!("[detect]");
+    for trace in &project.traces {
+        println!("{}", trace);
+    }
+    for warning in &project.warnings {
+        println!("warning: {}", warning);
+    }
+    println!("project type: {}", project.project_type());
+    println!();
+}
+
+#[allow(dead_code)]
+fn _format_resolved(resolved: &ResolvedCommand) -> String {
+    format!(
+        "{} -> {}",
+        resolved.intent.label(),
+        resolved.command.display()
+    )
+}

package/src/detect.rs

@@ -0,0 +1,232 @@
+use crate::manifest::read_package_json;
+use crate::model::{Framework, PackageManager, ProjectInfo, SrunError};
+use std::collections::BTreeSet;
+use std::path::Path;
+
+pub fn detect_project(root: &Path) -> Result<ProjectInfo, SrunError> {
+    let package_json = read_package_json(root)?;
+    let has_package_json = package_json.is_some();
+    let has_cargo_toml = root.join("Cargo.toml").exists();
+    let (package_manager, mut warnings, mut traces) =
+        detect_package_manager(root, has_package_json);
+    let mut frameworks = BTreeSet::new();
+
+    if let Some(package_json) = &package_json {
+        let deps = &package_json.dependencies;
+        let scripts = package_json
+            .scripts
+            .keys()
+            .map(String::as_str)
+            .collect::<BTreeSet<_>>();
+
+        if deps.contains("electron")
+            || deps.contains("electron-builder")
+            || deps.contains("electron-vite")
+            || root.join("electron").is_dir()
+            || has_file_prefix(root, "electron.vite.config.")
+        {
+            frameworks.insert(Framework::Electron);
+            traces.push("found electron markers".to_string());
+        }
+
+        if root.join("src-tauri").is_dir()
+            || root.join("tauri.conf.json").exists()
+            || deps.iter().any(|dep| dep.contains("tauri"))
+            || scripts.iter().any(|script| script.contains("tauri"))
+        {
+            frameworks.insert(Framework::Tauri);
+            traces.push("found tauri markers".to_string());
+        }
+
+        if deps.contains("next") || has_file_prefix(root, "next.config.") {
+            frameworks.insert(Framework::Next);
+            traces.push("found next markers".to_string());
+        }
+
+        if deps.contains("vite") || has_file_prefix(root, "vite.config.") {
+            frameworks.insert(Framework::Vite);
+            traces.push("found vite markers".to_string());
+        }
+    } else {
+        if root.join("src-tauri").is_dir() || root.join("tauri.conf.json").exists() {
+            frameworks.insert(Framework::Tauri);
+            traces.push("found tauri markers".to_string());
+        }
+    }
+
+    if root.join("turbo.json").exists() {
+        frameworks.insert(Framework::Turbo);
+        traces.push("found turbo.json".to_string());
+    }
+
+    if root.join("nx.json").exists() {
+        frameworks.insert(Framework::Nx);
+        traces.push("found nx.json".to_string());
+    }
+
+    let is_monorepo = root.join("apps").is_dir()
+        || root.join("packages").is_dir()
+        || frameworks.contains(&Framework::Turbo)
+        || frameworks.contains(&Framework::Nx);
+
+    if is_monorepo {
+        traces.push("found monorepo markers".to_string());
+    }
+
+    warnings.retain(|warning| !warning.is_empty());
+
+    Ok(ProjectInfo {
+        root: root.to_path_buf(),
+        package_manager,
+        package_json,
+        frameworks,
+        has_cargo_toml,
+        has_package_json,
+        is_monorepo,
+        warnings,
+        traces,
+    })
+}
+
+fn detect_package_manager(
+    root: &Path,
+    has_package_json: bool,
+) -> (Option<PackageManager>, Vec<String>, Vec<String>) {
+    let mut found = Vec::new();
+    let mut traces = Vec::new();
+
+    if root.join("pnpm-lock.yaml").exists() {
+        found.push(PackageManager::Pnpm);
+        traces.push("found pnpm-lock.yaml".to_string());
+    }
+    if root.join("bun.lockb").exists() || root.join("bun.lock").exists() {
+        found.push(PackageManager::Bun);
+        traces.push("found bun lockfile".to_string());
+    }
+    if root.join("yarn.lock").exists() {
+        found.push(PackageManager::Yarn);
+        traces.push("found yarn.lock".to_string());
+    }
+    if root.join("package-lock.json").exists() {
+        found.push(PackageManager::Npm);
+        traces.push("found package-lock.json".to_string());
+    }
+
+    let selected = [
+        PackageManager::Pnpm,
+        PackageManager::Bun,
+        PackageManager::Yarn,
+        PackageManager::Npm,
+    ]
+    .into_iter()
+    .find(|package_manager| found.contains(package_manager))
+    .or_else(|| has_package_json.then_some(PackageManager::Npm));
+
+    let mut warnings = Vec::new();
+    if found.len() > 1 {
+        if let Some(selected) = selected {
+            warnings.push(format!(
+                "Multiple package managers detected. Using {}.",
+                selected.label()
+            ));
+        }
+    } else if found.is_empty() && has_package_json {
+        warnings.push("No lockfile found. Using npm.".to_string());
+    }
+
+    (selected, warnings, traces)
+}
+
+fn has_file_prefix(root: &Path, prefix: &str) -> bool {
+    let Ok(entries) = std::fs::read_dir(root) else {
+        return false;
+    };
+
+    entries.filter_map(Result::ok).any(|entry| {
+        entry
+            .file_name()
+            .to_str()
+            .map(|file_name| file_name.starts_with(prefix))
+            .unwrap_or(false)
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::detect_project;
+    use crate::model::{Framework, PackageManager};
+    use std::fs;
+    use tempfile::tempdir;
+
+    #[test]
+    fn selects_pnpm_over_other_lockfiles() {
+        let dir = tempdir().expect("tempdir");
+        fs::write(dir.path().join("package.json"), "{}").expect("package");
+        fs::write(dir.path().join("pnpm-lock.yaml"), "").expect("pnpm");
+        fs::write(dir.path().join("package-lock.json"), "").expect("npm");
+
+        let project = detect_project(dir.path()).expect("project");
+
+        assert_eq!(project.package_manager, Some(PackageManager::Pnpm));
+        assert!(project
+            .warnings
+            .iter()
+            .any(|warning| warning.contains("Multiple")));
+    }
+
+    #[test]
+    fn falls_back_to_npm_for_package_json_without_lock() {
+        let dir = tempdir().expect("tempdir");
+        fs::write(dir.path().join("package.json"), "{}").expect("package");
+
+        let project = detect_project(dir.path()).expect("project");
+
+        assert_eq!(project.package_manager, Some(PackageManager::Npm));
+        assert!(project
+            .warnings
+            .iter()
+            .any(|warning| warning.contains("No lockfile")));
+    }
+
+    #[test]
+    fn detects_electron_and_vite() {
+        let dir = tempdir().expect("tempdir");
+        fs::write(
+            dir.path().join("package.json"),
+            r#"{"dependencies":{"electron":"latest","vite":"latest"}}"#,
+        )
+        .expect("package");
+
+        let project = detect_project(dir.path()).expect("project");
+
+        assert!(project.frameworks.contains(&Framework::Electron));
+        assert!(project.frameworks.contains(&Framework::Vite));
+    }
+
+    #[test]
+    fn detects_tauri_next_and_monorepo() {
+        let dir = tempdir().expect("tempdir");
+        fs::write(
+            dir.path().join("package.json"),
+            r#"{"dependencies":{"next":"latest"},"scripts":{"tauri:dev":"tauri dev"}}"#,
+        )
+        .expect("package");
+        fs::create_dir(dir.path().join("apps")).expect("apps");
+
+        let project = detect_project(dir.path()).expect("project");
+
+        assert!(project.frameworks.contains(&Framework::Tauri));
+        assert!(project.frameworks.contains(&Framework::Next));
+        assert!(project.is_monorepo);
+    }
+
+    #[test]
+    fn detects_cargo_only() {
+        let dir = tempdir().expect("tempdir");
+        fs::write(dir.path().join("Cargo.toml"), "[package]\nname='x'").expect("cargo");
+
+        let project = detect_project(dir.path()).expect("project");
+
+        assert!(project.is_cargo_only());
+    }
+}

package/src/exec.rs

@@ -0,0 +1,80 @@
+use crate::model::{CommandSpec, SrunError};
+use std::io;
+use std::path::Path;
+use std::process::{Command, ExitStatus, Stdio};
+
+pub fn run_command(command: &CommandSpec, cwd: &Path) -> Result<ExitStatus, SrunError> {
+    spawn_command(command, cwd).map_err(|source| SrunError::ProcessSpawn {
+        command: command.display(),
+        source,
+    })
+}
+
+fn spawn_command(command: &CommandSpec, cwd: &Path) -> io::Result<ExitStatus> {
+    match spawn_program(&command.program, &command.args, cwd) {
+        Ok(status) => Ok(status),
+        Err(error) if should_try_windows_cmd_shim(&command.program, &error) => {
+            spawn_program(&format!("{}.cmd", command.program), &command.args, cwd)
+        }
+        Err(error) => Err(error),
+    }
+}
+
+fn spawn_program(program: &str, args: &[String], cwd: &Path) -> io::Result<ExitStatus> {
+    Command::new(program)
+        .args(args)
+        .current_dir(cwd)
+        .stdin(Stdio::inherit())
+        .stdout(Stdio::inherit())
+        .stderr(Stdio::inherit())
+        .status()
+}
+
+fn should_try_windows_cmd_shim(program: &str, error: &io::Error) -> bool {
+    cfg!(windows)
+        && error.kind() == io::ErrorKind::NotFound
+        && matches!(program, "npm" | "pnpm" | "yarn" | "bun" | "npx")
+}
+
+#[cfg(test)]
+mod tests {
+    use super::should_try_windows_cmd_shim;
+    use crate::model::{CommandSpec, PackageManager};
+    use std::io;
+
+    #[test]
+    fn builds_package_manager_commands_without_shell() {
+        assert_eq!(
+            PackageManager::Pnpm.script_command("dev").display(),
+            "pnpm run dev"
+        );
+        assert_eq!(
+            PackageManager::Npm.script_command("dev").display(),
+            "npm run dev"
+        );
+        assert_eq!(
+            PackageManager::Bun.script_command("dev").display(),
+            "bun run dev"
+        );
+        assert_eq!(
+            PackageManager::Yarn.script_command("dev").display(),
+            "yarn dev"
+        );
+    }
+
+    #[test]
+    fn displays_program_without_args() {
+        assert_eq!(
+            CommandSpec::new("srun", std::iter::empty::<&str>()).display(),
+            "srun"
+        );
+    }
+
+    #[test]
+    fn windows_shim_fallback_only_applies_to_package_managers() {
+        let error = io::Error::new(io::ErrorKind::NotFound, "missing");
+
+        assert_eq!(should_try_windows_cmd_shim("npm", &error), cfg!(windows));
+        assert!(!should_try_windows_cmd_shim("cargo", &error));
+    }
+}

package/src/lib.rs

@@ -0,0 +1,10 @@
+pub mod cli;
+pub mod detect;
+pub mod exec;
+pub mod manifest;
+pub mod model;
+pub mod resolve;
+
+pub use detect::detect_project;
+pub use model::{Intent, ProjectInfo, ResolvedCommand, SrunError};
+pub use resolve::resolve_intent;