feat(php-shim): model $_ENV/$_SERVER as OsString snapshots

Rework the environment shim around getenv/putenv on the real environment
and $_ENV/$_SERVER as startup snapshots, all over OsString. Migrate every
caller off the old server()/server_argv() helpers and force the snapshots
in main() before any putenv() runs. Document the porting rules in
docs/dev/env-vars-porting.md.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

9 files changed, 88 insertions, 21 deletions

diff --git a/crates/shirabe-external-packages/src/symfony/console/color.rs b/crates/shirabe-external-packages/src/symfony/console/color.rs
index 3d5a7c4..fb7cc9f 100644
--- a/crates/shirabe-external-packages/src/symfony/console/color.rs
+++ b/crates/shirabe-external-packages/src/symfony/console/color.rs
@@ -196,7 +196,9 @@ impl Color {
         let b = color & 255;
 
         // see https://github.com/termstandard/colors/ for more information about true color support
-        if shirabe_php_shim::getenv("COLORTERM").as_deref() != Some("truecolor") {
+        if shirabe_php_shim::getenv("COLORTERM").as_deref()
+            != Some(std::ffi::OsStr::new("truecolor"))
+        {
             return Self::degrade_hex_color_to_ansi(r, g, b).to_string();
         }
 
diff --git a/crates/shirabe-external-packages/src/symfony/console/command/command.rs b/crates/shirabe-external-packages/src/symfony/console/command/command.rs
index 840f11a..89f4ae2 100644
--- a/crates/shirabe-external-packages/src/symfony/console/command/command.rs
+++ b/crates/shirabe-external-packages/src/symfony/console/command/command.rs
@@ -731,7 +731,13 @@ impl Command for CommandData {
             "%command.name%".to_string(),
             "%command.full_name%".to_string(),
         ];
-        let php_self = shirabe_php_shim::server("PHP_SELF");
+        let php_self = shirabe_php_shim::PHP_SERVER
+            .lock()
+            .unwrap()
+            .php_self()
+            .unwrap_or_default()
+            .to_string_lossy()
+            .into_owned();
         let replacements = [
             name.clone().unwrap_or_default(),
             if is_single_command {
diff --git a/crates/shirabe-external-packages/src/symfony/console/command/complete_command.rs b/crates/shirabe-external-packages/src/symfony/console/command/complete_command.rs
index cc700dc..da59a75 100644
--- a/crates/shirabe-external-packages/src/symfony/console/command/complete_command.rs
+++ b/crates/shirabe-external-packages/src/symfony/console/command/complete_command.rs
@@ -125,7 +125,15 @@ impl CompleteCommand {
             return;
         }
 
-        let command_name = shirabe_php_shim::basename(&shirabe_php_shim::server_argv()[0]);
+        let command_name = shirabe_php_shim::basename(
+            &shirabe_php_shim::PHP_SERVER
+                .lock()
+                .unwrap()
+                .argv()
+                .next()
+                .unwrap_or_default()
+                .to_string_lossy(),
+        );
         shirabe_php_shim::file_put_contents3(
             &format!(
                 "{}/sf_{}.log",
@@ -206,7 +214,9 @@ impl Command for CompleteCommand {
     ) -> anyhow::Result<()> {
         let _ = (input, output);
         self.is_debug.set(shirabe_php_shim::filter_var_boolean(
-            &shirabe_php_shim::getenv("SYMFONY_COMPLETION_DEBUG").unwrap_or_default(),
+            &shirabe_php_shim::getenv("SYMFONY_COMPLETION_DEBUG")
+                .unwrap_or_default()
+                .to_string_lossy(),
         ));
 
         Ok(())
@@ -268,7 +278,16 @@ impl Command for CompleteCommand {
                 "<info>Input:</> <comment>(\"|\" indicates the cursor position)</>".to_string(),
                 format!("  {}", completion_input.to_string()),
                 "<info>Command:</>".to_string(),
-                format!("  {}", shirabe_php_shim::server_argv().join(" ")),
+                format!(
+                    "  {}",
+                    shirabe_php_shim::PHP_SERVER
+                        .lock()
+                        .unwrap()
+                        .argv()
+                        .map(|a| a.to_string_lossy().into_owned())
+                        .collect::<Vec<_>>()
+                        .join(" ")
+                ),
                 "<info>Messages:</>".to_string(),
             ]);
 
diff --git a/crates/shirabe-external-packages/src/symfony/console/command/dump_completion_command.rs b/crates/shirabe-external-packages/src/symfony/console/command/dump_completion_command.rs
index 306bd59..588b868 100644
--- a/crates/shirabe-external-packages/src/symfony/console/command/dump_completion_command.rs
+++ b/crates/shirabe-external-packages/src/symfony/console/command/dump_completion_command.rs
@@ -73,7 +73,14 @@ impl DumpCompletionCommand {
     }
 
     fn guess_shell() -> String {
-        shirabe_php_shim::basename(&shirabe_php_shim::server_shell().unwrap_or_default())
+        shirabe_php_shim::basename(
+            &shirabe_php_shim::PHP_SERVER
+                .lock()
+                .unwrap()
+                .get("SHELL")
+                .unwrap_or_default()
+                .to_string_lossy(),
+        )
     }
 
     fn tail_debug_log(&self, command_name: &str, _output: &dyn OutputInterface) {
@@ -112,7 +119,13 @@ impl DumpCompletionCommand {
 
 impl Command for DumpCompletionCommand {
     fn configure(&self) -> anyhow::Result<()> {
-        let full_command = shirabe_php_shim::server_php_self();
+        let full_command = shirabe_php_shim::PHP_SERVER
+            .lock()
+            .unwrap()
+            .php_self()
+            .unwrap_or_default()
+            .to_string_lossy()
+            .into_owned();
         let command_name = shirabe_php_shim::basename(&full_command);
         // @realpath($fullCommand) ?: $fullCommand
         let full_command = match shirabe_php_shim::realpath(&full_command) {
@@ -170,7 +183,15 @@ impl Command for DumpCompletionCommand {
         input: Rc<RefCell<dyn InputInterface>>,
         output: Rc<RefCell<dyn OutputInterface>>,
     ) -> anyhow::Result<i64> {
-        let command_name = shirabe_php_shim::basename(&shirabe_php_shim::server_argv()[0]);
+        let command_name = shirabe_php_shim::basename(
+            &shirabe_php_shim::PHP_SERVER
+                .lock()
+                .unwrap()
+                .argv()
+                .next()
+                .unwrap_or_default()
+                .to_string_lossy(),
+        );
 
         if input.borrow().get_option("debug")?.to_bool() {
             self.tail_debug_log(&command_name, &*output.borrow());
diff --git a/crates/shirabe-external-packages/src/symfony/console/formatter/output_formatter_style.rs b/crates/shirabe-external-packages/src/symfony/console/formatter/output_formatter_style.rs
index 39d694d..c421edf 100644
--- a/crates/shirabe-external-packages/src/symfony/console/formatter/output_formatter_style.rs
+++ b/crates/shirabe-external-packages/src/symfony/console/formatter/output_formatter_style.rs
@@ -77,13 +77,17 @@ impl OutputFormatterStyleInterface for OutputFormatterStyle {
         if self.handles_href_gracefully.is_none() {
             self.handles_href_gracefully = Some(
                 shirabe_php_shim::getenv("TERMINAL_EMULATOR").as_deref()
-                    != Some("JetBrains-JediTerm")
+                    != Some(std::ffi::OsStr::new("JetBrains-JediTerm"))
                     && (shirabe_php_shim::getenv("KONSOLE_VERSION").is_none_or(|v| v.is_empty())
                         || shirabe_php_shim::getenv("KONSOLE_VERSION")
-                            .map(|v| v.parse::<i64>().unwrap_or(0))
+                            .map(|v| v.to_string_lossy().parse::<i64>().unwrap_or(0))
                             .unwrap_or(0)
                             > 201100)
-                    && !shirabe_php_shim::server_contains_key("IDEA_INITIAL_DIRECTORY"),
+                    && shirabe_php_shim::PHP_SERVER
+                        .lock()
+                        .unwrap()
+                        .get("IDEA_INITIAL_DIRECTORY")
+                        .is_none(),
             );
         }
 
diff --git a/crates/shirabe-external-packages/src/symfony/console/output/console_output.rs b/crates/shirabe-external-packages/src/symfony/console/output/console_output.rs
index dd6840d..254ec2c 100644
--- a/crates/shirabe-external-packages/src/symfony/console/output/console_output.rs
+++ b/crates/shirabe-external-packages/src/symfony/console/output/console_output.rs
@@ -103,7 +103,10 @@ impl ConsoleOutput {
             } else {
                 String::new()
             },
-            shirabe_php_shim::getenv("OSTYPE").unwrap_or_default(),
+            shirabe_php_shim::getenv("OSTYPE")
+                .unwrap_or_default()
+                .to_string_lossy()
+                .into_owned(),
             shirabe_php_shim::PHP_OS.to_string(),
         ];
 
diff --git a/crates/shirabe-external-packages/src/symfony/console/output/stream_output.rs b/crates/shirabe-external-packages/src/symfony/console/output/stream_output.rs
index f517cbe..ac85f3a 100644
--- a/crates/shirabe-external-packages/src/symfony/console/output/stream_output.rs
+++ b/crates/shirabe-external-packages/src/symfony/console/output/stream_output.rs
@@ -91,7 +91,9 @@ impl StreamOutput {
         if !shirabe_php_shim::stream_isatty_resource(stream)
             && !["MINGW32", "MINGW64"].contains(
                 &shirabe_php_shim::strtoupper(
-                    &shirabe_php_shim::getenv("MSYSTEM").unwrap_or_default(),
+                    &shirabe_php_shim::getenv("MSYSTEM")
+                        .unwrap_or_default()
+                        .to_string_lossy(),
                 )
                 .as_str(),
             )
@@ -105,15 +107,19 @@ impl StreamOutput {
             return true;
         }
 
-        if Some("Hyper".to_string()) == shirabe_php_shim::getenv("TERM_PROGRAM")
+        if shirabe_php_shim::getenv("TERM_PROGRAM").as_deref()
+            == Some(std::ffi::OsStr::new("Hyper"))
             || shirabe_php_shim::getenv("COLORTERM").is_some()
             || shirabe_php_shim::getenv("ANSICON").is_some()
-            || Some("ON".to_string()) == shirabe_php_shim::getenv("ConEmuANSI")
+            || shirabe_php_shim::getenv("ConEmuANSI").as_deref() == Some(std::ffi::OsStr::new("ON"))
         {
             return true;
         }
 
-        let term = shirabe_php_shim::getenv("TERM").unwrap_or_default();
+        let term = shirabe_php_shim::getenv("TERM")
+            .unwrap_or_default()
+            .to_string_lossy()
+            .into_owned();
         if "dumb" == term {
             return false;
         }
@@ -130,7 +136,10 @@ impl StreamOutput {
 
 /// PHP: `(($_SERVER['NO_COLOR'] ?? getenv('NO_COLOR'))[0] ?? '')`.
 fn no_color_first_char() -> String {
-    let value = shirabe_php_shim::getenv("NO_COLOR").unwrap_or_default();
+    let value = shirabe_php_shim::getenv("NO_COLOR")
+        .unwrap_or_default()
+        .to_string_lossy()
+        .into_owned();
     value
         .chars()
         .next()
diff --git a/crates/shirabe-external-packages/src/symfony/console/style/symfony_style.rs b/crates/shirabe-external-packages/src/symfony/console/style/symfony_style.rs
index 92e80b2..d7b2ef6 100644
--- a/crates/shirabe-external-packages/src/symfony/console/style/symfony_style.rs
+++ b/crates/shirabe-external-packages/src/symfony/console/style/symfony_style.rs
@@ -277,7 +277,8 @@ impl SymfonyStyle {
         let mut progress_bar = self.inner.create_progress_bar(max);
 
         if std::path::MAIN_SEPARATOR != '\\'
-            || shirabe_php_shim::getenv("TERM_PROGRAM").as_deref() == Some("Hyper")
+            || shirabe_php_shim::getenv("TERM_PROGRAM").as_deref()
+                == Some(std::ffi::OsStr::new("Hyper"))
         {
             progress_bar.set_empty_bar_character("░"); // light shade character ░
             progress_bar.set_progress_character("");
diff --git a/crates/shirabe-external-packages/src/symfony/console/terminal.rs b/crates/shirabe-external-packages/src/symfony/console/terminal.rs
index c02b87f..cc8f812 100644
--- a/crates/shirabe-external-packages/src/symfony/console/terminal.rs
+++ b/crates/shirabe-external-packages/src/symfony/console/terminal.rs
@@ -28,7 +28,8 @@ impl Terminal {
         let width = shirabe_php_shim::getenv("COLUMNS");
         if let Some(width) = width {
             return shirabe_php_shim::intval(&PhpMixed::String(shirabe_php_shim::trim(
-                &width, None,
+                &width.to_string_lossy(),
+                None,
             )));
         }
 
@@ -44,7 +45,8 @@ impl Terminal {
         let height = shirabe_php_shim::getenv("LINES");
         if let Some(height) = height {
             return shirabe_php_shim::intval(&PhpMixed::String(shirabe_php_shim::trim(
-                &height, None,
+                &height.to_string_lossy(),
+                None,
             )));
         }
 
@@ -85,7 +87,7 @@ impl Terminal {
             if let Some(ansicon) = &ansicon
                 && shirabe_php_shim::preg_match(
                     "/^(\\d+)x(\\d+)(?: \\((\\d+)x(\\d+)\\))?$/",
-                    &shirabe_php_shim::trim(ansicon, None),
+                    &shirabe_php_shim::trim(&ansicon.to_string_lossy(), None),
                     &mut matches,
                 )
             {