ttsc 0.30.3 → 0.31.0

package/cmd/ttscserver/command_operation_families_test.go

@@ -0,0 +1,207 @@
+package main
+
+import (
+  "bytes"
+  "context"
+  "os"
+  "strings"
+  "testing"
+
+  "github.com/samchon/ttsc/packages/ttsc/internal/lspserver"
+)
+
+// TestTtscserverCommandOperationFamilies verifies the command's metadata and invalid invocation operations directly.
+//
+// The five original case identities retain their literal statuses and output
+// assertions while using the same run dispatcher that main calls. These cases
+// finish before native server or compiler startup and need no project fixture.
+//
+// 1. Register the five original case names as sequential subtests.
+// 2. Invoke actual run through isolated full-byte output writers.
+// 3. Assert every original alias, status and diagnostic distinction.
+//
+// @evidence contracts/testing.md#behavioral-verification The five named private scenarios directly call run and preserve default help, all help/version aliases and the two invalid invocation categories with their original literal status and stream assertions.
+// @evidence contracts/testing.md#independent-expectations Existing literal help/banner/diagnostic fragments and zero/two statuses express the supported command contract independently of captured output; release metadata remains intentionally unconstrained.
+// @evidence contracts/testing.md#distinguishing-cases Empty argv, three help aliases, three version aliases and two rejection categories remain identifiable by their original case names. Private scenario documentation states each case's exact distinctions and oracle limits.
+// @evidence contracts/testing.md#execution-ownership This public Go entry owns five sequential named scenarios calling actual run with package-owned stream capture and restoring cwd/signal/host refusal seams. No producer, process host, compiler Program or project fixture starts. The selected aggregate's truthfulness scope includes those five private inputs and assertions; their bodies are not separately selected declarations.
+func TestTtscserverCommandOperationFamilies(t *testing.T) {
+  t.Run("TestTtscserverCommandDefaultPrintsHelp", scenarioTestTtscserverCommandDefaultPrintsHelp)
+  t.Run("TestTtscserverCommandHelpAliases", scenarioTestTtscserverCommandHelpAliases)
+  t.Run("TestTtscserverCommandRejectsMissingStdio", scenarioTestTtscserverCommandRejectsMissingStdio)
+  t.Run("TestTtscserverCommandRejectsUnknownFlag", scenarioTestTtscserverCommandRejectsUnknownFlag)
+  t.Run("TestTtscserverCommandVersionAliases", scenarioTestTtscserverCommandVersionAliases)
+}
+
+// scenarioTestTtscserverCommandDefaultPrintsHelp verifies ttscserver prints help when
+// invoked with no arguments.
+//
+// Editors occasionally probe a newly installed binary by running it bare.
+// ttscserver must print the help banner and exit cleanly instead of blocking
+// stdin waiting for LSP traffic that will never arrive.
+//
+// 1. Call the actual owning run operation with no arguments.
+// 2. Assert exit 0 and that stdout contains the LSP host banner.
+//
+// Testing: behavioral-verification Bare ttscserver returns zero and the Language Server Protocol host help banner.
+// Testing: independent-expectations The native editor host contract allows project-free probing without entering stdio transport; the banner fragment and empty stderr are literal expectations while additional stdout is allowed.
+// Testing: distinguishing-cases Empty argv exercises default help separately from the three explicit help aliases.
+// Testing: Execution ownership: The aggregate owns this private empty-argv input and its literal status/banner-fragment assertions through actual run; no artifact, process, compiler Program or project fixture starts.
+func scenarioTestTtscserverCommandDefaultPrintsHelp(t *testing.T) {
+  code, out, errOut := captureTtscserverCommand(t)
+  if code != 0 {
+    t.Fatalf("zero-arg run failed: code=%d stderr=%q", code, errOut)
+  }
+  if !strings.Contains(out, "Language Server Protocol host") {
+    t.Fatalf("help banner missing:\n%s", out)
+  }
+  if errOut != "" {
+    t.Fatalf("default help stderr = %q", errOut)
+  }
+}
+
+// scenarioTestTtscserverCommandHelpAliases verifies the three authored help
+// spellings return zero and include the same usage fragment, not identical bytes.
+//
+// Help is dispatched before any LSP wiring, so the aliases must succeed
+// independently of the project layout. An alias that diverged from the main
+// help path would show the wrong usage text to users of that spelling.
+//
+// 1. Call the actual owning run operation -h, --help, and help.
+// 2. Assert each alias exits cleanly with the LSP host usage banner.
+//
+// Testing: behavioral-verification -h, --help and help return zero with ttscserver --stdio usage text.
+// Testing: independent-expectations The public help aliases must expose the LSP transport guidance; substring matching permits other help content.
+// Testing: distinguishing-cases Three named project-free alias subtests differ from empty argv and transport refusal.
+// Testing: Execution ownership: The aggregate owns these three private alias inputs and zero/usage-fragment assertions through actual run; no artifact, process, compiler Program or project fixture starts.
+func scenarioTestTtscserverCommandHelpAliases(t *testing.T) {
+  for _, flag := range []string{"-h", "--help", "help"} {
+    t.Run(flag, func(t *testing.T) {
+      code, out, errOut := captureTtscserverCommand(t, flag)
+      if code != 0 {
+        t.Fatalf("%s help alias failed: code=%d stderr=%q", flag, code, errOut)
+      }
+      if !strings.Contains(out, "ttscserver --stdio") {
+        t.Fatalf("%s output missing usage line:\n%s", flag, out)
+      }
+    })
+  }
+}
+
+// scenarioTestTtscserverCommandRejectsMissingStdio verifies the transport guard
+// rejects the authored --cwd invocation that omits --stdio. Metadata aliases
+// are handled earlier and do not require this transport flag.
+//
+// The native host only speaks stdio. Running without the flag must produce
+// a clean exit 2 with an actionable error instead of hanging indefinitely on
+// a pipe that the caller never set up.
+//
+// 1. Call the actual owning run operation with a flag but without --stdio.
+// 2. Assert exit code 2 and a message that names the --stdio transport.
+//
+// Testing: behavioral-verification A cwd flag without --stdio returns usage status two and a diagnostic mentioning --stdio.
+// Testing: independent-expectations The native host supports the stdio transport explicitly; omission must reject the invocation.
+// Testing: distinguishing-cases A recognized nontransport flag distinguishes this rejection from the unknown-flag case.
+// Testing: Execution ownership: The aggregate owns this private cwd-without-stdio input and status/diagnostic-fragment assertions through actual run; refusal seams guard accidental startup.
+func scenarioTestTtscserverCommandRejectsMissingStdio(t *testing.T) {
+  code, _, errOut := captureTtscserverCommand(t, "--cwd", ".")
+  if code != 2 {
+    t.Fatalf("expected exit 2 without --stdio, got %d (stderr=%q)", code, errOut)
+  }
+  if !strings.Contains(errOut, "--stdio") {
+    t.Fatalf("error message missing --stdio mention:\n%s", errOut)
+  }
+}
+
+// scenarioTestTtscserverCommandRejectsUnknownFlag verifies the flag parser surfaces
+// the authored --garbage-flag with exit 2 and the unknown-flag diagnostic.
+//
+// Editors that scaffold the wrong flag for ttscserver should see the failure
+// during development, not silent misbehavior in the field where a mistyped
+// flag might mask a real configuration problem.
+//
+// 1. Call the actual owning run operation with an unrecognized flag.
+// 2. Assert exit code 2 and an unknown-flag diagnostic naming the authored flag.
+//
+// Testing: behavioral-verification --garbage-flag returns usage status two and a flag-provided-but-not-defined diagnostic naming garbage-flag.
+// Testing: independent-expectations The deliberately unregistered garbage-flag independently owes flag-parser rejection; literal error category and authored flag name define the expected stderr without copying actual output.
+// Testing: distinguishing-cases Status two alone also occurs for missing stdio; the unknown-flag category and garbage-flag name reject a fallthrough to that transport guard. Recognized cwd without stdio and accepted metadata aliases retain their separate cases.
+// Testing: Execution ownership: The aggregate owns this private unregistered-flag input and literal status/category/name assertions through actual run; refusal seams guard accidental startup.
+func scenarioTestTtscserverCommandRejectsUnknownFlag(t *testing.T) {
+  code, out, errOut := captureTtscserverCommand(t, "--garbage-flag")
+  if code != 2 {
+    t.Fatalf("expected exit 2 for unknown flag, got %d", code)
+  }
+  if !strings.Contains(errOut, "flag provided but not defined") || !strings.Contains(errOut, "garbage-flag") {
+    t.Fatalf("expected unknown-flag diagnostic, got %q", errOut)
+  }
+  if out != "" {
+    t.Fatalf("unknown flag stdout = %q", out)
+  }
+}
+
+// scenarioTestTtscserverCommandVersionAliases verifies the three authored
+// version spellings return zero with the same banner prefix, not identical bytes.
+//
+// Editors frequently log this output for support reports, so all aliases
+// must resolve to the same banner. A spelling that diverged would produce
+// inconsistent diagnostic metadata across editor configurations.
+//
+// 1. Call the actual owning run operation -v, --version, and version.
+// 2. Assert each alias exits 0 and prints the ttscserver version banner.
+//
+// Testing: behavioral-verification -v, --version and version return zero with the ttscserver banner prefix.
+// Testing: independent-expectations The native host metadata contract supplies the literal prefix independently of release version values.
+// Testing: distinguishing-cases Three named metadata aliases run without stdio or a fixture project; help and transport cases are separate.
+// Testing: Execution ownership: The aggregate owns these three private version-alias inputs and zero/banner-prefix assertions through actual run; release metadata is unconstrained and no producer starts.
+func scenarioTestTtscserverCommandVersionAliases(t *testing.T) {
+  for _, flag := range []string{"-v", "--version", "version"} {
+    t.Run(flag, func(t *testing.T) {
+      code, out, errOut := captureTtscserverCommand(t, flag)
+      if code != 0 {
+        t.Fatalf("%s version alias failed: code=%d stderr=%q", flag, code, errOut)
+      }
+      if !strings.HasPrefix(strings.TrimSpace(out), "ttscserver ") {
+        t.Fatalf("%s output missing version prefix:\n%s", flag, out)
+      }
+    })
+  }
+}
+
+// captureTtscserverCommand observes actual dispatch with invocation-local stream buffers.
+//
+// Package writer seams are restored by defer on ordinary return and testing
+// failure. Existing cwd/signal/host seams reject accidental startup before
+// any native producer can run. Empty stdin has invocation-local ownership.
+// All scenarios are sequential; no case uses t.Parallel. Buffers retain
+// full bytes and do not substitute empty stderr for successful status.
+//
+// Common: Principled implementation: The actual run dispatcher writes into separate byte buffers; its returned status is preserved unchanged.
+// Common: Clear and simple design: This helper owns only stream capture and seam restoration, leaving argv and all dispatch decisions with run; existing cwd, signal and host seams enforce the documented no-start boundary.
+// Common: Prohibited implementation shortcuts: Existing package-owned writer seams are used without foreign mutation, production test branches, cached outcomes or retries.
+// Common: Meaningful documentation: Native paragraphs state full-byte capture, deferred restoration and the sequential execution requirement.
+func captureTtscserverCommand(t *testing.T, args ...string) (int, string, string) {
+  t.Helper()
+  previousOut, previousErr, previousIn := stdout, stderr, stdin
+  previousGetwd, previousNotify, previousHost := getwd, notifyContext, runLSPServer
+  defer func() {
+    stdout, stderr, stdin = previousOut, previousErr, previousIn
+    getwd, notifyContext, runLSPServer = previousGetwd, previousNotify, previousHost
+  }()
+  stdin = strings.NewReader("")
+  getwd = func() (string, error) {
+    t.Fatal("metadata or invalid invocation reached cwd resolution")
+    return "", nil
+  }
+  notifyContext = func(ctx context.Context, signals ...os.Signal) (context.Context, context.CancelFunc) {
+    t.Fatal("metadata or invalid invocation reached LSP startup")
+    return ctx, func() {}
+  }
+  runLSPServer = func(context.Context, lspserver.LSPServerOptions) error {
+    t.Fatal("metadata or invalid invocation started an LSP host")
+    return nil
+  }
+  var output, errors bytes.Buffer
+  stdout, stderr = &output, &errors
+  code := run(args)
+  return code, output.String(), errors.String()
+}

package/cmd/ttscserver/main.go

@@ -15,6 +15,7 @@ package main
 
 import (
   "context"
+  "encoding/json"
   "errors"
   "flag"
   "fmt"
@@ -68,25 +69,84 @@ func main() {
 // Called by main with os.Args[1:] and overridden in tests with a synthetic
 // argument slice to avoid spawning a real tsgo process.
 func run(args []string) int {
-  if len(args) == 0 {
-    printHelp(stdout)
-    return 0
+  if len(args) != 0 && args[0] == "--ttsc-resolve-launch" {
+    return resolveLaunch(args[1:])
   }
-  switch args[0] {
-  case "-h", "--help", "help":
+  switch metaCommand(args) {
+  case "help":
     printHelp(stdout)
     return 0
-  case "-v", "--version", "version":
+  case "version":
     printVersion(stdout)
     return 0
   }
   return runLSP(args)
 }
 
+// metaCommand is shared by normal dispatch and the launcher's private query so
+// even a metadata invocation with trailing LSP flags never prepares a project.
+func metaCommand(args []string) string {
+  if len(args) == 0 {
+    return "help"
+  }
+  switch args[0] {
+  case "-h", "--help", "help":
+    return "help"
+  case "-v", "--version", "version":
+    return "version"
+  }
+  return ""
+}
+
+// lspLaunchOptions carries the Go-owned interpretation to Node before package
+// resolution. Remaining fields stay private to the native host's startup.
+type lspLaunchOptions struct {
+  LSP                            bool          `json:"lsp"`
+  Cwd                            string        `json:"cwd"`
+  Tsconfig                       string        `json:"tsconfig"`
+  TsconfigExplicit               bool          `json:"tsconfigExplicit"`
+  TsgoBinary                     string        `json:"tsgo"`
+  PluginsFile                    string        `json:"-"`
+  ProgressDelay                  time.Duration `json:"-"`
+  SuppressExecuteCommandProvider bool          `json:"-"`
+  SuppressedExecuteCommandIDs     string        `json:"-"`
+  ExecuteCommandIDPrefix          string        `json:"-"`
+}
+
+// resolveLaunch is a private launcher/native protocol. It uses the same parser
+// as runLSP without reading a manifest, creating a plugin source, or starting
+// signal handling. The original argv is still used by the eventual host.
+func resolveLaunch(args []string) int {
+  options := &lspLaunchOptions{}
+  if metaCommand(args) == "" {
+    var code int
+    options, code = parseLSPLaunch(args)
+    if code != 0 {
+      return code
+    }
+  }
+  if err := json.NewEncoder(stdout).Encode(options); err != nil {
+    fmt.Fprintf(stderr, "ttscserver: write launch options: %v\n", err)
+    return 1
+  }
+  return 0
+}
+
 // runLSP parses LSP-mode flags and starts the proxy. It returns 0 on clean
 // shutdown, 1 on a runtime error from the LSP host, and 2 on invalid
 // invocation (missing --stdio, unresolvable cwd, unknown flags).
 func runLSP(args []string) int {
+  options, code := parseLSPLaunch(args)
+  if code != 0 {
+    return code
+  }
+  return startLSP(options)
+}
+
+// parseLSPLaunch owns all native flag definitions, spelling, ordering and
+// termination rules for both launcher preparation and actual server startup.
+// It resolves only process defaults, leaving project-dependent work to callers.
+func parseLSPLaunch(args []string) (*lspLaunchOptions, int) {
   fs := flag.NewFlagSet("ttscserver", flag.ContinueOnError)
   fs.SetOutput(stderr)
   stdioFlag := fs.Bool("stdio", false, "communicate with the editor over stdin/stdout")
@@ -97,19 +157,17 @@ func runLSP(args []string) int {
   suppressExecuteCommandProviderFlag := fs.Bool("suppress-execute-command-provider", false, "do not advertise ttsc executeCommand ids during initialize")
   suppressExecuteCommandIDsFlag := fs.String("suppress-execute-command-ids", "", "comma-separated ttsc executeCommand ids to omit during initialize")
   executeCommandIDPrefixFlag := fs.String("execute-command-id-prefix", "", "prefix to apply to advertised executeCommand ids")
-  // The launcher passes this flag only when it actually resolved LSP-capable
-  // plugins, so a host too old to know it refuses to start instead of running
-  // silently without every plugin the project declared. Version skew between
-  // the launcher and a TTSCSERVER_BINARY override is therefore visible at the
-  // first request rather than diagnosed from missing diagnostics.
+  // Only an invocation with plugins or tracked selection inputs needs this
+  // transport. The private launch query establishes parser compatibility before
+  // the JavaScript launcher resolves either input population.
   lspPluginsFileFlag := fs.String("lsp-plugins-file", "", "path to the private LSP plugin manifest written by the ttsc launcher")
   _ = fs.String("clientProcessId", "", "ignored VSCode language-client compatibility flag")
   if err := fs.Parse(args); err != nil {
-    return 2
+    return nil, 2
   }
   if !*stdioFlag {
     fmt.Fprintln(stderr, "ttscserver: only --stdio transport is supported")
-    return 2
+    return nil, 2
   }
 
   cwd := strings.TrimSpace(*cwdFlag)
@@ -117,29 +175,52 @@ func runLSP(args []string) int {
     resolved, err := getwd()
     if err != nil {
       fmt.Fprintf(stderr, "ttscserver: could not resolve working directory: %v\n", err)
-      return 2
+      return nil, 2
     }
     cwd = resolved
   }
 
-  ctx, stop := notifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
-  defer stop()
-
   tsgoBinary := strings.TrimSpace(*tsgoFlag)
   if tsgoBinary == "" {
     tsgoBinary = strings.TrimSpace(os.Getenv("TTSC_TSGO_BINARY"))
   }
 
-  manifestJSON, err := lspPluginManifestJSON(strings.TrimSpace(*lspPluginsFileFlag))
+  explicitTsconfig := false
+  fs.Visit(func(value *flag.Flag) {
+    if value.Name == "tsconfig" {
+      explicitTsconfig = true
+    }
+  })
+  return &lspLaunchOptions{
+    LSP:                            true,
+    Cwd:                            cwd,
+    Tsconfig:                       strings.TrimSpace(*tsconfigFlag),
+    TsconfigExplicit:               explicitTsconfig,
+    TsgoBinary:                     tsgoBinary,
+    PluginsFile:                    strings.TrimSpace(*lspPluginsFileFlag),
+    ProgressDelay:                  *progressDelayFlag,
+    SuppressExecuteCommandProvider: *suppressExecuteCommandProviderFlag,
+    SuppressedExecuteCommandIDs:    *suppressExecuteCommandIDsFlag,
+    ExecuteCommandIDPrefix:         strings.TrimSpace(*executeCommandIDPrefixFlag),
+  }, 0
+}
+
+// startLSP owns manifest consumption and the actual signal-aware server
+// lifetime after the native argument parser accepted the invocation.
+func startLSP(options *lspLaunchOptions) int {
+  ctx, stop := notifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
+  defer stop()
+
+  manifestJSON, err := lspPluginManifestJSON(options.PluginsFile)
   if err != nil {
     fmt.Fprintf(stderr, "ttscserver: %v\n", err)
     return 2
   }
   source, err := lspserver.NewNativePluginSource(lspserver.NativePluginSourceOptions{
-    Cwd:          cwd,
+    Cwd:          options.Cwd,
     Err:          stderr,
     ManifestJSON: manifestJSON,
-    Tsconfig:     strings.TrimSpace(*tsconfigFlag),
+    Tsconfig:     options.Tsconfig,
   })
   if err != nil {
     fmt.Fprintf(stderr, "ttscserver: %v\n", err)
@@ -152,20 +233,20 @@ func runLSP(args []string) int {
   // advertises the capability and consults this provider only as a fallback
   // (tsgo did not advertise). It loads the program lazily on the first such
   // request, so wiring it here adds no startup cost.
-  symbolProvider := graphsymbols.NewProvider(cwd, strings.TrimSpace(*tsconfigFlag))
+  symbolProvider := graphsymbols.NewProvider(options.Cwd, options.Tsconfig)
 
   err = runLSPServer(ctx, lspserver.LSPServerOptions{
     In:                             stdin,
     Out:                            stdout,
     Err:                            stderr,
-    Cwd:                            cwd,
-    TsgoBinary:                     tsgoBinary,
+    Cwd:                            options.Cwd,
+    TsgoBinary:                     options.TsgoBinary,
     Source:                         source,
     SymbolProvider:                 symbolProvider,
-    SuppressExecuteCommandProvider: *suppressExecuteCommandProviderFlag,
-    SuppressedExecuteCommandIDs:    splitCSV(*suppressExecuteCommandIDsFlag),
-    ExecuteCommandIDPrefix:         strings.TrimSpace(*executeCommandIDPrefixFlag),
-    ProgressDelay:                  *progressDelayFlag,
+    SuppressExecuteCommandProvider: options.SuppressExecuteCommandProvider,
+    SuppressedExecuteCommandIDs:    splitCSV(options.SuppressedExecuteCommandIDs),
+    ExecuteCommandIDPrefix:         options.ExecuteCommandIDPrefix,
+    ProgressDelay:                  options.ProgressDelay,
   })
   if err != nil && !errors.Is(err, context.Canceled) {
     fmt.Fprintf(stderr, "ttscserver: %v\n", err)
@@ -179,13 +260,14 @@ func runLSP(args []string) int {
 //
 // The manifest names every resolved project plugin and its launch context, so
 // the copy this process was given to own is consumed exactly once: the file the
-// launcher named with the flag is removed as soon as it has been read, which
-// means a forcibly terminated launcher cannot leave the payload on disk. Both
-// transport variables are cleared from this process either way, so no plugin
-// sidecar spawned later inherits the payload or a path to it. The environment
-// forms remain accepted because an editor pointed straight at a native binary
-// has no launcher to pass the flag, and a manifest supplied that way is read
-// without being removed, because it belongs to whoever wrote it.
+// launcher named with the flag must be removed after a successful read before
+// startup continues. A removal failure is reported; deletion cannot be promised
+// if the process is killed before consumption or the filesystem denies it.
+//
+// Both transport variables are cleared from this process either way, so later
+// plugin sidecars inherit neither the payload nor its path. Environment forms
+// support editors that invoke a native binary directly. Those files remain
+// caller-owned and are read without removal.
 func lspPluginManifestJSON(flagLocation string) (string, error) {
   defer func() {
     os.Unsetenv("TTSC_LSP_PLUGINS_FILE")
@@ -197,11 +279,11 @@ func lspPluginManifestJSON(flagLocation string) (string, error) {
       return "", err
     }
     // Only the flag names a file the launcher created for this process, so
-    // only that one is consumed here. Removing it is what keeps a forcibly
-    // terminated launcher from leaving the payload on disk. A path supplied
-    // out of band belongs to whoever wrote it and must survive the read, or
-    // the next session would start without the plugins it declared.
-    os.Remove(flagLocation)
+    // only that one is consumed here. An out-of-band file remains caller-owned.
+    // Another cleanup owner may already have removed it after the read.
+    if err := os.Remove(flagLocation); err != nil && !errors.Is(err, os.ErrNotExist) {
+      return "", fmt.Errorf("consume --lsp-plugins-file: %w", err)
+    }
     return body, nil
   }
   location := strings.TrimSpace(os.Getenv("TTSC_LSP_PLUGINS_FILE"))

package/cmd/ttscserver/resolve_launch_uses_native_flag_authority_test.go

@@ -0,0 +1,147 @@
+package main
+
+import (
+  "bytes"
+  "context"
+  "encoding/json"
+  "errors"
+  "os"
+  "strings"
+  "testing"
+
+  "github.com/samchon/ttsc/packages/ttsc/internal/lspserver"
+)
+
+// TestResolveLaunchUsesNativeFlagAuthority verifies preparation queries use the
+// host's full native argument contract before project-dependent work.
+//
+// The literal expectations follow flag.FlagSet's documented one/two-dash forms,
+// replacement assignments and stop rules, plus this command's metadata/default
+// contract. Opaque paths and deliberately unreadable manifest transports ensure
+// these queries never prepare plugins, consume manifests or start an LSP host.
+//
+// 1. Query valid replacement, spelling, termination, default and metadata cases.
+// 2. Require exact effective project/binary values and explicit-config meaning.
+// 3. Query malformed/unknown/transport refusals and a failed cwd default.
+// 4. Require native status/diagnostic categories and untouched manifest state.
+//
+// @evidence contracts/testing.md#behavioral-verification Actual run enters the private query and returns parsed launch JSON or native invocation refusal; host and signal refusal seams guard accidental server startup, and inherited private manifest transports remain untouched.
+// @evidence contracts/testing.md#independent-expectations Literal final assignments, documented FlagSet stop/spelling/value rules, native tsconfig default, environment binary fallback and zero/two statuses prescribe the expected values without deriving them from another invocation of the parser.
+// @evidence contracts/testing.md#distinguishing-cases Repeated mixed equals/space and one/two-dash assignments, equal duplicates, terminator, first positional, dash-only positional, flag-looking string value, trimmed/blank values, default cwd/config/binary, all metadata aliases and invalid string/bool/duration/unknown/triple-dash/missing-stdio cases remain named subtests. A failed getwd has its own native refusal.
+// @evidence contracts/testing.md#execution-ownership This Go unit runs the actual command parser/JSON writer in-process with restoring package writer/getwd/host/signal seams and t.Setenv. Paths are opaque data and no artifact build, filesystem project preparation, compiler or real server executes; dynamic subtests are owned by this selected Test declaration.
+func TestResolveLaunchUsesNativeFlagAuthority(t *testing.T) {
+  t.Setenv("TTSC_TSGO_BINARY", " /environment-tsgo ")
+  t.Setenv("TTSC_LSP_PLUGINS_FILE", "must-not-be-read")
+  t.Setenv("TTSC_LSP_PLUGINS_JSON", "must-not-be-decoded")
+  previousGetwd, previousHost, previousNotify := getwd, runLSPServer, notifyContext
+  getwd = func() (string, error) { return "/process-cwd", nil }
+  runLSPServer = func(context.Context, lspserver.LSPServerOptions) error {
+    t.Fatal("preparation query started an LSP host")
+    return nil
+  }
+  notifyContext = func(context.Context, ...os.Signal) (context.Context, context.CancelFunc) {
+    t.Fatal("preparation query installed signal handling")
+    return context.Background(), func() {}
+  }
+  defer func() { getwd, runLSPServer, notifyContext = previousGetwd, previousHost, previousNotify }()
+
+  for _, test := range []struct {
+    name string
+    args []string
+    cwd string
+    config string
+    explicit bool
+    tsgo string
+  }{
+    {"last assignments", []string{"--stdio", "--cwd", "/a", "-cwd=/b", "--tsconfig=first.json", "-tsconfig", "last.json", "--tsgo=/first", "-tsgo", "/last"}, "/b", "last.json", true, "/last"},
+    {"equal duplicates", []string{"-stdio", "-cwd=/b", "--cwd", "/b", "-tsconfig=last.json", "--tsconfig=last.json"}, "/b", "last.json", true, "/environment-tsgo"},
+    {"terminator", []string{"--stdio", "--cwd=/a", "--", "--cwd=/b", "--tsconfig=ignored.json", "--unknown"}, "/a", "tsconfig.json", false, "/environment-tsgo"},
+    {"positional", []string{"--stdio", "--cwd=/a", "position", "--cwd=/b"}, "/a", "tsconfig.json", false, "/environment-tsgo"},
+    {"dash positional", []string{"--stdio", "-", "--cwd=/b"}, "/process-cwd", "tsconfig.json", false, "/environment-tsgo"},
+    {"flag-looking value", []string{"--stdio", "--cwd", "--literal-value"}, "--literal-value", "tsconfig.json", false, "/environment-tsgo"},
+    {"trimmed values", []string{"--stdio", "--cwd= /b ", "--tsconfig= last.json ", "--tsgo= /last "}, "/b", "last.json", true, "/last"},
+    {"blank replacements", []string{"--stdio", "--cwd=/a", "--cwd= ", "--tsconfig=first.json", "--tsconfig= ", "--tsgo=/first", "--tsgo= "}, "/process-cwd", "", true, "/environment-tsgo"},
+    {"defaults", []string{"--stdio"}, "/process-cwd", "tsconfig.json", false, "/environment-tsgo"},
+    {"later boolean override", []string{"--stdio=false", "-stdio=true", "--progress-delay=1s", "--clientProcessId=42"}, "/process-cwd", "tsconfig.json", false, "/environment-tsgo"},
+  } {
+    t.Run(test.name, func(t *testing.T) {
+      var out, errOut bytes.Buffer
+      withIO(t, &out, &errOut, nil, func() {
+        if code := run(append([]string{"--ttsc-resolve-launch"}, test.args...)); code != 0 {
+          t.Fatalf("query status %d: %s", code, errOut.String())
+        }
+      })
+      var actual lspLaunchOptions
+      if err := json.Unmarshal(out.Bytes(), &actual); err != nil {
+        t.Fatal(err)
+      }
+      if !actual.LSP || actual.Cwd != test.cwd || actual.Tsconfig != test.config || actual.TsconfigExplicit != test.explicit || actual.TsgoBinary != test.tsgo {
+        t.Fatalf("unexpected launch selection: %s", out.String())
+      }
+      if errOut.Len() != 0 {
+        t.Fatalf("unexpected stderr: %s", errOut.String())
+      }
+    })
+  }
+
+  for _, head := range []string{"", "help", "-h", "--help", "version", "-v", "--version"} {
+    t.Run("metadata "+head, func(t *testing.T) {
+      args := []string{"--ttsc-resolve-launch"}
+      if head != "" {
+        args = append(args, head, "--stdio", "--unknown")
+      }
+      var out, errOut bytes.Buffer
+      withIO(t, &out, &errOut, nil, func() {
+        if code := run(args); code != 0 {
+          t.Fatalf("metadata status %d: %s", code, errOut.String())
+        }
+      })
+      var actual lspLaunchOptions
+      if err := json.Unmarshal(out.Bytes(), &actual); err != nil {
+        t.Fatal(err)
+      }
+      if actual.LSP || errOut.Len() != 0 {
+        t.Fatalf("metadata prepared LSP: %s %s", out.String(), errOut.String())
+      }
+    })
+  }
+
+  for _, test := range []struct {
+    name string
+    args []string
+    diagnostic string
+  }{
+    {"unknown", []string{"--stdio", "--cwd=/missing", "--unknown"}, "flag provided but not defined: -unknown"},
+    {"missing string", []string{"--stdio", "--tsconfig"}, "flag needs an argument: -tsconfig"},
+    {"invalid bool", []string{"--stdio=maybe"}, "invalid boolean value \"maybe\" for -stdio"},
+    {"invalid duration", []string{"--stdio", "--progress-delay=invalid"}, "invalid value \"invalid\" for flag -progress-delay"},
+    {"triple dash", []string{"--stdio", "---cwd=/a"}, "bad flag syntax"},
+    {"missing stdio", []string{"--cwd=/a"}, "only --stdio transport is supported"},
+    {"final false", []string{"--stdio", "-stdio=false"}, "only --stdio transport is supported"},
+  } {
+    t.Run(test.name, func(t *testing.T) {
+      var out, errOut bytes.Buffer
+      withIO(t, &out, &errOut, nil, func() {
+        if code := run(append([]string{"--ttsc-resolve-launch"}, test.args...)); code != 2 {
+          t.Fatalf("refusal status %d", code)
+        }
+      })
+      if out.Len() != 0 || !strings.Contains(errOut.String(), test.diagnostic) {
+        t.Fatalf("unexpected refusal stdout=%q stderr=%q", out.String(), errOut.String())
+      }
+    })
+  }
+  getwd = func() (string, error) { return "", errors.New("unavailable-cwd") }
+  var out, errOut bytes.Buffer
+  withIO(t, &out, &errOut, nil, func() {
+    if code := run([]string{"--ttsc-resolve-launch", "--stdio"}); code != 2 {
+      t.Fatalf("getwd refusal status %d", code)
+    }
+  })
+  if out.Len() != 0 || !strings.Contains(errOut.String(), "could not resolve working directory: unavailable-cwd") {
+    t.Fatalf("unexpected cwd refusal: %q %q", out.String(), errOut.String())
+  }
+  if os.Getenv("TTSC_LSP_PLUGINS_FILE") != "must-not-be-read" || os.Getenv("TTSC_LSP_PLUGINS_JSON") != "must-not-be-decoded" {
+    t.Fatal("query consumed inherited manifest state")
+  }
+}

package/cmd/ttscserver/run_lsp_forwards_execute_command_advertisement_flags_test.go

@@ -19,7 +19,14 @@ import (
 // 1. Substitute the runLSPServer seam and capture its options.
 // 2. Run runLSP with suppression and prefix flags.
 // 3. Assert the captured LSPServerOptions carry the parsed values.
+//
+// @evidence contracts/testing.md#behavioral-verification runLSP passes the suppress-execute-command-provider and command-prefix flags into the LSPServerOptions given to the LSP host.
+// @evidence contracts/testing.md#independent-expectations The expected option values are the literal flag values supplied on the command line.
+// @evidence contracts/testing.md#distinguishing-cases Both a suppression flag and a prefix flag are supplied so a handoff that drops either is detected.
+// @evidence contracts/testing.md#execution-ownership This Go unit calls runLSP in-process with its owning runLSPServer seam replaced and package-owned writers captured; it does not replace getwd or foreign process streams. Both ambient plugin-manifest transports are cleared with restoring test environment controls, so native source construction has no selected plugin child and the host is not started.
 func TestRunLSPForwardsExecuteCommandAdvertisementFlags(t *testing.T) {
+  t.Setenv("TTSC_LSP_PLUGINS_FILE", "")
+  t.Setenv("TTSC_LSP_PLUGINS_JSON", "")
   prev := runLSPServer
   var captured lspserver.LSPServerOptions
   runLSPServer = func(_ context.Context, opts lspserver.LSPServerOptions) error {