v0.9.0: run-script as a clean Unix filter — ScriptArgs, Stdin, stderr separation

Closes TWO FRs that compose into one story:
- FR_runscript_script_args.md (argv channel via ScriptArgs global)
- FR_runscript_stdin_and_stderr_separation.md (Stdin global + stop
  redirecting Console.Error to the output writer)

The Args FR had been misfiled to Complete/ at some point without code
actually shipping — verified by repo-wide grep for ScriptArgs returning
zero matches. v0.9.0 ships both together because they compose: a .csx
becomes a proper stdin->stdout(data) + stderr(diag) filter with argv
in and exit code out (the exit-code FR shipped in v0.8.2). The
SWBomExcluded ScripTree provider can now retire its PowerShell
wrapper shim.

Architecture:
- New IScriptContext interface in ComBridge.Core with ScriptArgs
  (string[]) and Stdin (string) properties.
- Every shipped plugin's globals class (SwGlobals, ExcelGlobals,
  WdGlobals, PptGlobals, OlGlobals + 4 Mac variants) implements
  IScriptContext.
- RunScriptCommand populates both fields after CreateGlobals but
  before invoking the host.
- ScriptArgs = args.Skip(1).ToArray() — everything between the script
  path and the trailing output-file positional.
- Stdin = ReadStdinWithTimeoutAsync(250ms) via the underlying
  Console.OpenStandardInput() stream + CancellationToken, extended
  per chunk so slow producers aren't truncated.
- ScriptHost.RunAsync no longer calls Console.SetError — script
  stderr flows to the process's real stderr.

Hang trap caught during smoke-test:
  if (Console.IsInputRedirected) ReadToEndAsync()
hangs forever when stdin is inherited-but-empty (combridge invoked
from bash subprocesses, Task Scheduler, CI runners). IsInputRedirected
returns true for "non-terminal" — NOT "has data available." Test 1
(no pipe) sat at ReadToEndAsync >30s before being killed. Fix:
cancellation-token timeout pattern. Captured as
lesson_20260615_console_isinputredirected_inherited_handle_hang.md
in personal_rag/claude_code/.

Verified end-to-end against running SW 2026:
  Test 1 (no pipe, args only) → ScriptArgs.Length=5, exit 5, no hang
  Test 2 (real pipe)          → 66 bytes received, exit 0
  Test 3 (stderr split)       → STDOUT to <out>, STDERR to real stderr
  Test 4 (full filter)        → clean JSON on stdout, diag on stderr,
                                 args + stdin parsed, exit 0

Mirrored to D:\Dev\ScripTree\lib\combridge\ and
R:\ScripTree\lib\combridge\ per the CLAUDE.md deployment mandate.

Both FRs in Complete/ with implementation log stamps. The Args FR's
"misfiled" history captured in its own log for the next reader.

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

Author: 2 people

CHANGELOG.md

@@ -4,6 +4,181 @@ All notable changes to this project will be documented in this file.
 Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/);
 versions follow [SemVer](https://semver.org/spec/v2.0.0.html).
 
+## [0.9.0] — `run-script` becomes a clean Unix filter: `ScriptArgs` in, `Stdin` in, stderr separate
+
+Closes TWO FRs that compose into one story:
+
+- `FR_runscript_script_args.md` — argv channel via `ScriptArgs` global
+- `FR_runscript_stdin_and_stderr_separation.md` — `Stdin` global +
+  stop redirecting `Console.Error` to the output writer
+
+Both FRs had been independently filed but never implemented (the
+`Args` FR was misfiled to `Complete\` at some point without code
+shipping — verified by repo-wide grep). v0.9.0 ships both together
+because they compose: a `.csx` becomes a proper Unix-style
+`stdin → stdout(data) + stderr(diag)` filter with argv in and exit
+code out (exit-code FR shipped in v0.8.2). The SWBomExcluded
+ScripTree provider can now retire its PowerShell wrapper shim and
+become plain `combridge solidworks run-script provider.csx -`.
+
+### Added — `IScriptContext` interface
+
+New interface in `ComBridge.Core`:
+
+```csharp
+public interface IScriptContext {
+    string[] ScriptArgs { get; set; }
+    string Stdin { get; set; }
+}
+```
+
+Each plugin's globals class (`SwGlobals`, `ExcelGlobals`, `WdGlobals`,
+`PptGlobals`, `OlGlobals`, plus the four Mac variants) now implements
+this interface. The host (`RunScriptCommand`) casts and sets the
+fields after `CreateGlobals`. Plugins that DON'T implement it just
+skip silently — scripts see empty values, preserving pre-v0.9.0
+behavior.
+
+### Added — `ScriptArgs` global (FR 1)
+
+CLI tokens between the script path and the trailing output-file
+positional are now available to scripts:
+
+```
+combridge solidworks run-script audit.csx --mode quick --offline X: -
+                                          └────── ScriptArgs ──────┘
+```
+
+Inside the script (both `.csx` and `.vbs`):
+
+```csharp
+// .csx
+foreach (var arg in ScriptArgs) Console.WriteLine(arg);
+return ScriptArgs.Length;
+```
+
+```vbscript
+' .vbs
+For i = 0 To UBound(ScriptArgs)
+    WScript.Echo ScriptArgs(i)
+Next
+```
+
+Empty array when no extra tokens were passed.
+
+### Added — `Stdin` global (FR 2 item 1)
+
+If the calling process redirected stdin to combridge (a pipeline, a
+here-doc, a file redirect), the full stream is read eagerly at command
+entry and exposed to the script as `Stdin`. Empty string when stdin
+isn't redirected.
+
+```csharp
+// ScripTree provider .csx — receives request as JSON on stdin:
+var req = JsonSerializer.Deserialize<ProviderRequest>(Stdin);
+// ... build choices ...
+Console.WriteLine(JsonSerializer.Serialize(new { choices, choice_labels }));
+```
+
+**Stdin-timeout trap** (caught during smoke-test, important): the
+naive implementation `if (Console.IsInputRedirected)
+ReadToEndAsync()` **hangs forever** when stdin is inherited-but-empty
+(common when combridge is invoked from bash subprocesses, Task
+Scheduler, CI runners). `Console.IsInputRedirected` returns `true`
+for "non-terminal" — NOT "has data available." The fix:
+`ReadStdinWithTimeoutAsync` uses the underlying stream's `ReadAsync`
+with a 250 ms cancellation token, extended per chunk so slow
+producers aren't truncated. Real producers deliver the first bytes
+in microseconds; empty-inherited-handle invocations collapse to "".
+See `personal_rag/claude_code/lesson_20260615_console_isinputredirected_inherited_handle_hang.md`.
+
+### Changed — `Console.Error` no longer redirected to `<out>` (FR 2 item 2)
+
+Pre-v0.9.0 `ScriptHost.RunAsync` did:
+
+```csharp
+Console.SetOut(output);
+Console.SetError(output);   // ← merged stderr into the <out> writer
+```
+
+So a script's `Console.Error.WriteLine(...)` corrupted any structured
+data on stdout — a provider that needed to emit pure JSON had to
+forbid all diagnostics on the success path. v0.9.0 leaves
+`Console.Error` alone:
+
+```csharp
+Console.SetOut(output);
+// Console.Error flows to the process's real stderr (cleaner filter shape)
+```
+
+Host-emitted diagnostics (compile errors, `script not found`,
+`SCRIPT EXCEPTION`) already go through `output.WriteLine(...)`
+directly and are unaffected. Only the SCRIPT's `Console.Error`
+changes destination.
+
+### Verified
+
+Full SWBomExcluded provider pattern — stdin in, args in, stdout pure
+JSON, stderr diagnostics:
+
+```bash
+echo '{"target_file":"foo.SLDDRW"}' | combridge solidworks run-script \
+    full_filter.csx --x 1 --y 2 /tmp/out.json 2>/tmp/diag.txt
+```
+
+Result:
+- `/tmp/out.json` contains clean JSON (parser-safe):
+  `{ "received_target": "foo.SLDDRW", "arg_count": 4, "args": ["--x","1","--y","2"] }`
+- `/tmp/diag.txt` contains the diagnostic:
+  `[diag] received 29 bytes on stdin, 4 args`
+- combridge exits 0
+
+Plus the empty-stdin no-hang case (Test 1), real-pipe case (Test 2),
+and stderr-split case (Test 3) — all pass.
+
+### Impact on existing scripts
+
+Mostly none — both fields default to empty when unused. The one
+behavior change worth noting: any existing `.csx` that wrote
+diagnostics via `Console.Error.WriteLine(...)` expecting them to land
+in `<out>` will now write to the process's real stderr instead. This
+is the Unix-correct behavior; scripts that need the old merge can
+explicitly redirect with `Console.SetError(Console.Out)` at the top
+of the file.
+
+### Files
+
+Added:
+- `src/ComBridge.Core/IScriptContext.cs`
+
+Changed:
+- `src/ComBridge.Core/Commands/RunScriptCommand.cs` — populates
+  `ScriptArgs` + `Stdin` on globals before invoking host;
+  `ReadStdinWithTimeoutAsync` helper
+- `src/ComBridge.Core/ScriptHost.cs` — removed `Console.SetError`
+- `src/plugins/ComBridge.Plugins.SolidWorks/SolidWorksPlugin.cs` —
+  `SwGlobals` implements `IScriptContext`
+- `src/plugins/ComBridge.Plugins.Excel/ExcelPlugin.cs` —
+  `ExcelGlobals` implements `IScriptContext`
+- `src/plugins/ComBridge.Plugins.Word/WordPlugin.cs` —
+  `WdGlobals` implements `IScriptContext`
+- `src/plugins/ComBridge.Plugins.PowerPoint/PowerPointPlugin.cs` —
+  `PptGlobals` implements `IScriptContext`
+- `src/plugins/ComBridge.Plugins.Outlook/OutlookPlugin.cs` —
+  `OlGlobals` implements `IScriptContext`
+- `src/plugins/ComBridge.Plugins.Excel.Mac/XlMacApp.cs` —
+  `XlMacGlobals` implements `IScriptContext`
+- `src/plugins/ComBridge.Plugins.Word.Mac/WdMacApp.cs` —
+  `WdMacGlobals` implements `IScriptContext`
+- `src/plugins/ComBridge.Plugins.PowerPoint.Mac/PptMacApp.cs` —
+  `PptMacGlobals` implements `IScriptContext`
+- `src/plugins/ComBridge.Plugins.Outlook.Mac/OlMacApp.cs` —
+  `OlMacGlobals` implements `IScriptContext`
+
+Both FRs moved to `Complete\` with implementation log stamps.
+The `Args` FR's old "Status: PROPOSED" header was preserved with a
+note that it had been misfiled prior to actual implementation.
+
 ## [0.8.2] — `run-script` now propagates the script's `return N` as the process exit code (contract fix)
 
 Closes `FR_runscript_propagate_script_return_value.md`. A `.csx`

src/ComBridge.Core/Commands/RunScriptCommand.cs

@@ -4,13 +4,30 @@ namespace ComBridge.Core.Commands;
 /// Built-in <c>run-script</c> command. Every plugin gets this for free —
 /// the host registers it before any plugin-specific commands.
 /// </summary>
+/// <remarks>
+/// <para>
+/// CLI shape: <c>combridge &lt;plugin&gt; run-script &lt;script&gt; [args...] &lt;out&gt;</c>.
+/// The host strips the trailing output-file positional before calling
+/// here, so <c>args[0]</c> is the script path and any further tokens
+/// (<c>args[1..]</c>) form the script's <see cref="IScriptContext.ScriptArgs"/>.
+/// </para>
+/// <para>
+/// Stdin behavior: when the calling process redirected stdin to
+/// combridge (a pipeline or a here-doc), the full stream is read
+/// eagerly at command entry and exposed to the script as
+/// <see cref="IScriptContext.Stdin"/>. ScripTree's
+/// <c>choices_provider</c> contract (which delivers its input as a
+/// JSON object on stdin) is the primary motivator — see
+/// <c>FR_runscript_stdin_and_stderr_separation.md</c>.
+/// </para>
+/// </remarks>
 public sealed class RunScriptCommand : IBridgeCommand
 {
     private readonly IComBridgePlugin _plugin;
     public RunScriptCommand(IComBridgePlugin plugin) => _plugin = plugin;
 
     public string Name => "run-script";
-    public string Usage => "run-script <scriptFile.csx>   (output file passed as last CLI arg)";
+    public string Usage => "run-script <scriptFile.{csx|vbs}> [args...]   (output file passed as last CLI arg)";
 
     public async Task<int> RunAsync(object comRoot, string[] args, TextWriter output)
     {
@@ -19,7 +36,89 @@ public async Task<int> RunAsync(object comRoot, string[] args, TextWriter output
             output.WriteLine($"USAGE: {Usage}");
             return 64;
         }
+
         var globals = _plugin.CreateGlobals(comRoot);
+
+        // Populate the host-side I/O channels on globals if the plugin's
+        // globals class implements IScriptContext (every shipped plugin
+        // does). Plugins that don't implement it just skip silently —
+        // their scripts won't see ScriptArgs/Stdin, which matches the
+        // pre-v0.9.0 behavior.
+        if (globals is IScriptContext ctx)
+        {
+            // Everything between the script path and the trailing output
+            // file goes to the script as ScriptArgs. Empty array if no
+            // extra tokens were passed.
+            ctx.ScriptArgs = args.Length > 1
+                ? args.Skip(1).ToArray()
+                : Array.Empty<string>();
+
+            // Read stdin eagerly if it's redirected, so a script can
+            // JsonSerializer.Deserialize(Stdin) without stream timing
+            // concerns. With a short timeout to avoid hangs when stdin
+            // is "redirected" only because a parent shell inherited a
+            // non-terminal handle but no producer is actually writing —
+            // common when combridge is launched from bash subprocesses
+            // or scheduled tasks. Real producers (ScripTree provider
+            // pipes, here-docs, file redirects) deliver data within
+            // microseconds; 250 ms is generous for them, instant
+            // enough to not hang an empty invocation.
+            ctx.Stdin = Console.IsInputRedirected
+                ? await ReadStdinWithTimeoutAsync(TimeSpan.FromMilliseconds(250))
+                : "";
+        }
+
         return await ScriptHost.RunAsync(_plugin, globals, args[0], output);
     }
+
+    /// <summary>
+    /// Read the whole of stdin into a string, but give up if no data
+    /// arrives within <paramref name="initialWait"/>. After the first
+    /// chunk has been read the timer is extended per chunk so a slow
+    /// producer can still deliver a large payload; only the INITIAL
+    /// wait is bounded.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// <see cref="Console.IsInputRedirected"/> returns true whenever
+    /// stdin is anything other than a terminal — including when a
+    /// parent shell (bash, Task Scheduler, a CI runner) inherits a
+    /// non-terminal handle to combridge without writing anything.
+    /// A naive <c>Console.In.ReadToEndAsync()</c> blocks forever in
+    /// that case because the pipe stays open but empty. This method
+    /// uses the underlying stream's
+    /// <see cref="System.IO.Stream.ReadAsync(byte[],int,int,System.Threading.CancellationToken)"/>
+    /// with a cancellation token so the wait collapses to the timeout
+    /// when no producer is on the other end.
+    /// </para>
+    /// <para>
+    /// Real producers (ScripTree provider pipes, Bash here-docs, file
+    /// redirects) deliver the first bytes within microseconds — they
+    /// never hit the timeout. The 250 ms default is generous; bumping
+    /// it further has no upside.
+    /// </para>
+    /// </remarks>
+    private static async Task<string> ReadStdinWithTimeoutAsync(TimeSpan initialWait)
+    {
+        try
+        {
+            using var cts = new CancellationTokenSource(initialWait);
+            var stream = Console.OpenStandardInput();
+            using var ms = new MemoryStream();
+            var buf = new byte[8192];
+            while (true)
+            {
+                int read = await stream.ReadAsync(buf.AsMemory(), cts.Token);
+                if (read == 0) break;
+                ms.Write(buf, 0, read);
+                // Producer is actively writing — extend the timer so a
+                // multi-chunk payload doesn't get truncated by the
+                // initial-wait clock.
+                cts.CancelAfter(initialWait);
+            }
+            return System.Text.Encoding.UTF8.GetString(ms.ToArray());
+        }
+        catch (OperationCanceledException) { return ""; }
+        catch                              { return ""; }
+    }
 }

src/ComBridge.Core/IScriptContext.cs

@@ -0,0 +1,60 @@
+namespace ComBridge.Core;
+
+/// <summary>
+/// Host-injected fields available to <c>run-script</c> scripts on top of
+/// the plugin-specific globals. Each plugin's globals class implements
+/// this interface so the host can set the fields after construction —
+/// the plugin owns the COM-binding properties (e.g. <c>swApp</c>,
+/// <c>xlBook</c>); the host owns the I/O channels (<c>ScriptArgs</c>,
+/// <c>Stdin</c>).
+/// </summary>
+/// <remarks>
+/// <para>
+/// Why an interface rather than a base class: each plugin's globals
+/// class is already final-state with init-only COM properties set by
+/// its constructor. Switching to a base class would force every
+/// plugin's globals constructor to chain through, and any future
+/// host-added field becomes a versioning concern across the plugin
+/// tree. The interface lets the host blindly cast and set without
+/// any plugin contract change.
+/// </para>
+/// <para>
+/// Both fields are populated by <see cref="Commands.RunScriptCommand"/>
+/// before the script runs. <c>ScriptArgs</c> comes from the CLI tokens
+/// between the script path and the output-file positional;
+/// <c>Stdin</c> comes from the process's stdin if redirected (empty
+/// string otherwise). Scripts that ignore them are unaffected; callers
+/// that pass nothing get empty values.
+/// </para>
+/// <para>
+/// See FR <c>FR_runscript_script_args.md</c> (the argv channel) and
+/// FR <c>FR_runscript_stdin_and_stderr_separation.md</c> (the stdin
+/// channel + stderr separation). Both shipped in v0.9.0.
+/// </para>
+/// </remarks>
+public interface IScriptContext
+{
+    /// <summary>
+    /// CLI tokens passed between the script path and the trailing
+    /// output-file positional. Empty array when no tokens were passed.
+    /// </summary>
+    /// <example>
+    /// <c>combridge solidworks run-script audit.csx --mode quick --offline X: -</c>
+    /// produces <c>ScriptArgs = ["--mode", "quick", "--offline", "X:"]</c>.
+    /// </example>
+    string[] ScriptArgs { get; set; }
+
+    /// <summary>
+    /// The full stdin the process received, as a single string. Empty
+    /// when stdin was not redirected. Read eagerly at script-start so
+    /// the script can <c>JsonSerializer.Deserialize</c> it without
+    /// worrying about stream timing.
+    /// </summary>
+    /// <example>
+    /// A ScripTree <c>choices_provider</c> hands the .csx its request
+    /// as a JSON blob on stdin; the script does
+    /// <c>var req = JsonSerializer.Deserialize&lt;Request&gt;(Stdin);</c>
+    /// and prints the choices JSON on stdout.
+    /// </example>
+    string Stdin { get; set; }
+}

src/ComBridge.Core/ScriptHost.cs

@@ -148,11 +148,17 @@ public static async Task<int> RunAsync(
             .WithFilePath(Path.GetFullPath(scriptPath))
             .WithEmitDebugInformation(true);
 
-        // Redirect script Console.* into our output writer.
+        // Redirect script Console.Out into our output writer. Console.Error
+        // is left alone (v0.9.0 change): the script's stderr flows to the
+        // process's real stderr, so a .csx becomes a proper Unix-style
+        // stdin->stdout(data) + stderr(diag) filter — composable in
+        // pipelines and usable as a ScripTree provider that emits clean
+        // JSON on stdout while still logging diagnostics. Host diagnostics
+        // (compile errors, "script not found", SCRIPT EXCEPTION) go
+        // through `output.WriteLine(...)` directly and are unaffected.
+        // See FR_runscript_stdin_and_stderr_separation.md item 2.
         var originalOut = Console.Out;
-        var originalErr = Console.Error;
         Console.SetOut(output);
-        Console.SetError(output);
         try
         {
             // Roslyn's internal scripting host creates its own AssemblyLoadContext
@@ -217,7 +223,6 @@ public static async Task<int> RunAsync(
         finally
         {
             Console.SetOut(originalOut);
-            Console.SetError(originalErr);
         }
     }