feat: added perseus snoop and docs for common pitfalls

docs/next/en-US/SUMMARY.md

@@ -31,6 +31,7 @@
     -   [State Amalgamation](/docs/strategies/amalgamation)
 -   [CLI](/docs/cli)
     -   [Ejecting](/docs/ejecting)
+    -   [Snooping](/docs/snooping)
 -   [Testing](/docs/testing/intro)
     -   [Checkpoints](/docs/testing/checkpoints)
     -   [Fantoccini Basics](/docs/testing/fantoccini-basics)
@@ -52,6 +53,7 @@
     -   [Optimizing Code Size](/docs/deploying/size)
     -   [Relative Paths](/docs/deploying/relative-paths)
 -   [Migrating from v0.2.x](/docs/updating)
+-   [Common Pitfalls and Known Bugs](/docs/pitfalls-and-bugs)
 
 ---
 

docs/next/en-US/pitfalls-and-bugs.md

@@ -0,0 +1,7 @@
+# Common Pitfalls and Known Bugs
+
+This document is a list of common pitfalls and known bugs in Perseus, and will be updated regularly. If you're having an issue with Perseus, check through this list to see if your problem already has a solution.
+
+## `perseus serve` fails with no error message on Arch Linux
+
+If you're running Arch Linux or a derivative (e.g. Manjaro), you're very likely to encounter a bug in which `perseus serve` stops with no error messages whatsoever, and your app doesn't build properly. This is tracked by [issue #78](https://github.com/arctic-hen7/perseus/issues/78), and is due to an issue in OpenSSL that causes a segmentation fault in `wasm-pack` (see [this issue](https://github.com/rustwasm/wasm-pack/issues/1079)). Right now, the only solution to this is to downgrade `wasm-pack` by running `cargo install wasm-pack --version "0.9.1"`, which seems to fix the problem.

docs/next/en-US/snooping.md

@@ -0,0 +1,15 @@
+# Snooping on the CLI
+
+Most of the time, it's fine to run `perseus serve` and enjoy the results, but sometimes you'll need to delve a little deeper and see some more detailed logs. Then you need `perseus snoop`. This command will run one of the lower-level steps the Perseus CLI runs, but in such a way that you can see everything it does. The time you'll use this the most is when you have a `dbg!()` call in the static generation process (e.g. in the *build state* strategy) and you want to actually see its output, which neither `perseus build` nor `perseus serve` will let you do.
+
+## `perseus snoop build`
+
+This snoops on the static generation process, which is half of what `perseus build` does. You can use this to see the outputs of `dbg!()` calls in your build-time code.
+
+## `perseus snoop wasm-build`
+
+This snoops on the `wasm-pack` call that compiles your app to Wasm. There aren't really any use cases for this outside debugging strange errors, because Perseus calls out to this process without augmenting it in any way, so your code shouldn't impact this really at all (unless you're using some package that can't be compiled to Wasm).
+
+## `perseus snoop serve`
+
+This snoops on the server, which is useful if you're hacking on it, or if you're getting errors from it (e.g. panics in the server will only appear if you run this). Crucially though, this expects to be working with a correct build state, which means **you must run `perseus build` before running this command**, otherwise all sorts of things could happen. If such things do happen, you should run `perseus clean --dist`, and that should solve things.

packages/perseus-cli/src/bin/main.rs

@@ -1,11 +1,12 @@
 use clap::Parser;
 use fmterr::fmt_err;
-use perseus_cli::errors::*;
+use perseus_cli::parse::SnoopSubcommand;
 use perseus_cli::{
     build, check_env, delete_artifacts, delete_bad_dir, deploy, eject, export, has_ejected,
     parse::{Opts, Subcommand},
     prepare, serve, tinker,
 };
+use perseus_cli::{errors::*, snoop_build, snoop_server, snoop_wasm_build};
 use std::env;
 use std::io::Write;
 use std::path::PathBuf;
@@ -150,6 +151,11 @@ fn core(dir: PathBuf) -> Result<i32, Error> {
             }
             tinker(dir)?
         }
+        Subcommand::Snoop(snoop_subcmd) => match snoop_subcmd {
+            SnoopSubcommand::Build => snoop_build(dir)?,
+            SnoopSubcommand::WasmBuild => snoop_wasm_build(dir)?,
+            SnoopSubcommand::Serve => snoop_server(dir)?,
+        },
         Subcommand::Prep => {
             // The `.perseus/` directory has already been set up in the preliminaries, so we don't need to do anything here
             0

packages/perseus-cli/src/lib.rs

@@ -36,6 +36,7 @@ mod export;
 pub mod parse;
 mod prepare;
 mod serve;
+mod snoop;
 mod thread;
 mod tinker;
 
@@ -54,6 +55,7 @@ pub use eject::{eject, has_ejected};
 pub use export::export;
 pub use prepare::{check_env, prepare};
 pub use serve::serve;
+pub use snoop::{snoop_build, snoop_server, snoop_wasm_build};
 pub use tinker::tinker;
 
 /// Deletes a corrupted '.perseus/' directory. This will be called on certain error types that would leave the user with a half-finished

packages/perseus-cli/src/parse.rs

@@ -28,6 +28,9 @@ pub enum Subcommand {
     /// Prepares the `.perseus/` directory (done automatically by `build` and `serve`)
     Prep,
     Tinker(TinkerOpts),
+    /// Runs one of the underlying commands that builds your app, allowing you to see more detailed logs
+    #[clap(subcommand)]
+    Snoop(SnoopSubcommand),
 }
 /// Builds your app
 #[derive(Parser)]
@@ -86,3 +89,13 @@ pub struct TinkerOpts {
     #[clap(long)]
     pub force: bool,
 }
+
+#[derive(Parser)]
+pub enum SnoopSubcommand {
+    /// Snoops on the static generation process (this will let you see `dbg!` calls and the like)
+    Build,
+    /// Snoops on the Wasm building process (mostly for debugging errors)
+    WasmBuild,
+    /// Snoops on the server process (run `perseus build` before this)
+    Serve,
+}

packages/perseus-cli/src/snoop.rs

@@ -0,0 +1,71 @@
+use crate::errors::*;
+use std::env;
+use std::path::{Path, PathBuf};
+use std::process::{Command, Stdio};
+
+/// Runs a command directly, piping its output and errors to the streams of this program. This allows the user to investigate the innards of
+/// Perseus, or just see their own `dbg!` calls. This will return the exit code of the command, which should be passed through to this program.
+fn run_cmd_directly(cmd: String, dir: &Path) -> Result<i32, ExecutionError> {
+    // The shell configurations for Windows and Unix
+    #[cfg(unix)]
+    let shell_exec = "sh";
+    #[cfg(windows)]
+    let shell_exec = "powershell";
+    #[cfg(unix)]
+    let shell_param = "-c";
+    #[cfg(windows)]
+    let shell_param = "-command";
+
+    let output = Command::new(shell_exec)
+        .args([shell_param, &cmd])
+        .current_dir(dir)
+        .stdout(Stdio::inherit())
+        .stderr(Stdio::inherit())
+        .output()
+        .map_err(|err| ExecutionError::CmdExecFailed { cmd, source: err })?;
+
+    let exit_code = match output.status.code() {
+        Some(exit_code) => exit_code,         // If we have an exit code, use it
+        None if output.status.success() => 0, // If we don't, but we know the command succeeded, return 0 (success code)
+        None => 1, // If we don't know an exit code but we know that the command failed, return 1 (general error code)
+    };
+
+    Ok(exit_code)
+}
+
+/// Runs static generation processes directly so the user can see detailed logs. This is commonly used for allowing users to see `dbg!` and
+/// the like in their builder functions.
+pub fn snoop_build(dir: PathBuf) -> Result<i32, ExecutionError> {
+    let target = dir.join(".perseus/builder");
+    run_cmd_directly(
+        format!(
+            "{} run",
+            env::var("PERSEUS_CARGO_PATH").unwrap_or_else(|_| "cargo".to_string())
+        ),
+        &target,
+    )
+}
+
+/// Runs the commands to build the user's app to Wasm directly so they can see detailed logs.
+pub fn snoop_wasm_build(dir: PathBuf) -> Result<i32, ExecutionError> {
+    let target = dir.join(".perseus");
+    run_cmd_directly(
+        format!(
+            "{} build --target web",
+            env::var("PERSEUS_WASM_PACK_PATH").unwrap_or_else(|_| "wasm-pack".to_string())
+        ),
+        &target,
+    )
+}
+
+/// Runs the commands to run the server directly so the user can see detailed logs.
+pub fn snoop_server(dir: PathBuf) -> Result<i32, ExecutionError> {
+    let target = dir.join(".perseus/server");
+    run_cmd_directly(
+        format!(
+            "{} run",
+            env::var("PERSEUS_CARGO_PATH").unwrap_or_else(|_| "cargo".to_string())
+        ),
+        &target,
+    )
+}