ttsc 0.30.4 → 0.31.1

package/cmd/graphbench/main.go

@@ -89,9 +89,8 @@ func run() int {
 // node that an edge connects to a node in another file).
 func summarize(g *graph.Graph, sourceFiles int) metrics {
   // Seeded with every kind Build can produce, so a family that happened not to
-  // occur reports 0 rather than vanishing from the object. Three of the seven
-  // used to be seeded and the map grew the rest on first sight, which meant the
-  // reported shape depended on the project measured.
+  // occur reports 0 rather than vanishing from the object; a map grown on first
+  // sight would make the reported shape depend on the project measured.
   edges := map[string]int{}
   for _, kind := range graph.EdgeKinds() {
     edges[string(kind)] = 0

package/cmd/graphdump/main.go

@@ -1,8 +1,8 @@
 // Command graphdump builds the @ttsc/graph code graph for a project and prints
 // the entire graph (every node and every edge, with none of the MCP response
 // caps) as one JSON document. It is the repo-internal one-shot used by the
-// benchmark graph viewer pipeline; the shipped equivalent is `ttscgraph dump`. Both
-// serialize through graph.MarshalDump.
+// benchmark graph viewer pipeline; the shipped equivalent is `ttscgraph dump`.
+// Both use the shared buffered dump encoder and report output failures.
 package main
 
 import (
@@ -21,8 +21,7 @@ import (
 
 // Package-level streams so command tests can capture I/O without patching the
 // os globals, and argv arrives as a parameter for the same reason. Both mirror
-// the shipped sibling in cmd/ttscgraph, whose capability claim is tested the
-// same way; this command's claim went undefended because it had neither seam.
+// the shipped sibling in cmd/ttscgraph.
 var (
   stdout io.Writer = os.Stdout
   stderr io.Writer = os.Stderr
@@ -32,7 +31,32 @@ func main() {
   os.Exit(run(os.Args[1:]))
 }
 
+// preparedCommand owns one loaded Program and the sibling command's deliberately
+// limited producer claims. Ignore acquisition remains at the default adapter.
+type preparedCommand struct {
+  program  *driver.Program
+  built    *graph.Graph
+  root     string
+  tsconfig string
+  texts    map[string]string
+  origin   graph.DumpOrigin
+  pretty   bool
+}
+
+// run joins actual Git membership with this command's prepared graph and owns
+// its Program until streaming serialization has completed or failed.
 func run(args []string) int {
+  prepared, code := prepareCommand(args)
+  if prepared == nil {
+    return code
+  }
+  defer func() { _ = prepared.program.Close() }()
+  return prepared.encode(graph.GitIgnoredFiles(prepared.root, prepared.built))
+}
+
+// prepareCommand parses the real grammar and constructs the capability origin
+// from this actual compiler consumer. Successful callers own the Program close.
+func prepareCommand(args []string) (*preparedCommand, int) {
   fs := flag.NewFlagSet("graphdump", flag.ContinueOnError)
   fs.SetOutput(stderr)
   cwd := fs.String("cwd", ".", "project root")
@@ -40,12 +64,11 @@ func run(args []string) int {
   pretty := fs.Bool("pretty", false, "indent the JSON output")
   if err := fs.Parse(args); err != nil {
     // `-h` asks for the usage this just printed, so it is a request that
-    // succeeded rather than an argument that failed. Under the global flag set
-    // this command used to read, `ExitOnError` already exited 0 for it.
+    // succeeded rather than an argument that failed.
     if errors.Is(err, flag.ErrHelp) {
-      return 0
+      return nil, 0
     }
-    return 2
+    return nil, 2
   }
 
   // Resolve the project root the same way LoadProgram does (absolute, then
@@ -60,16 +83,14 @@ func run(args []string) int {
   prog, _, err := driver.LoadProgram(root, *tsconfig, driver.LoadProgramOptions{})
   if err != nil {
     fmt.Fprintf(stderr, "graphdump: could not load %s/%s: %v\n", root, *tsconfig, err)
-    return 1
+    return nil, 1
   }
   if prog == nil {
     fmt.Fprintf(stderr, "graphdump: could not load %s/%s\n", root, *tsconfig)
-    return 1
+    return nil, 1
   }
-  defer func() { _ = prog.Close() }()
 
   g := graph.Build(prog)
-  ignored := graph.GitIgnoredFiles(root, g)
   texts := graph.SourceTexts(prog)
   // The viewer pipeline reduces nodes and edges and never asks whether the build
   // universe moved or whether the disk still matches, so this tool pays for
@@ -78,7 +99,7 @@ func run(args []string) int {
   // digests are absent, rather than reading an empty universe as "nothing
   // changed" or an empty diskDigest as "the file could not be read". The shipped
   // `ttscgraph dump` is the one that proves the whole contract.
-  data, err := graph.MarshalDump(g, root, *tsconfig, ignored, texts, graph.DumpOrigin{
+  origin := graph.DumpOrigin{
     Provenance: graph.NewProvenance(
       // No version: this tool is built from the tree on demand and never
       // stamped, and an invented one would be worse than an absent one.
@@ -93,11 +114,16 @@ func run(args []string) int {
       texts,
       nil,
     ),
-  }, *pretty)
-  if err != nil {
+  }
+  return &preparedCommand{program: prog, built: g, root: root, tsconfig: *tsconfig, texts: texts, origin: origin, pretty: *pretty}, 0
+}
+
+// encode consumes evaluated membership while preserving this command's actual
+// producer capability authority and streaming serialization diagnostics.
+func (prepared *preparedCommand) encode(ignored map[string]bool) int {
+  if err := graph.EncodeDump(stdout, prepared.built, prepared.root, prepared.tsconfig, ignored, prepared.texts, prepared.origin, prepared.pretty); err != nil {
     fmt.Fprintf(stderr, "graphdump: %v\n", err)
     return 1
   }
-  fmt.Fprintln(stdout, string(data))
   return 0
 }

package/cmd/graphdump/run_declares_the_capability_its_output_carries_test.go

@@ -12,26 +12,30 @@ import (
   "github.com/samchon/ttsc/packages/ttsc/internal/graph"
 )
 
-// TestRunDeclaresTheCapabilityItsOutputCarries verifies that every capability
-// this command declares is paired with the output that backs it, and that a
-// project carrying no documentation tag emits that field nowhere.
+// TestRunDeclaresTheCapabilityItsOutputCarries pins this producer's two
+// capability declarations and checks representative output for each: tag text
+// and at least one non-empty checker digest. An untagged project emits no docTags
+// key. Digest contents and complete source coverage are not checked here.
 //
-// The claim is a separate literal from the shipped `ttscgraph dump`'s, so the
-// test that guards that one guards nothing here: deleting graph.CapabilityDocTags
-// from this command's list used to break nothing at all, in a package that had
-// never had a test file. The claim matters because the two states a consumer must
+// This producer assembles its own capability list, separately from the shipped
+// `ttscgraph dump`. The claim matters because the two states a consumer must
 // distinguish — "this declaration cites nothing" and "this producer never
 // looked" — are the same absent field, so a dump that carries tags and forgets to
 // say so is read as a repository where nothing cites anything.
 //
-// The declared set is compared whole rather than member by member, so a
-// capability added to the list arrives with the evidence for it or fails here.
+// The fixed expected set rejects added or missing capability declarations; it
+// does not derive expectations from the producer's assembled list.
 //
-//  1. Run the command over a project with a tag, capturing stdout.
-//  2. Assert the declared set is exactly what this command claims, and that each
-//     claim is backed: a tag in the output, and a digested source.
-//  3. Run it over a project with no tag and assert the field appears nowhere,
+//  1. Prepare and encode a project with a tag, capturing stdout.
+//  2. Assert the fixed two-capability set, literal tag text and key, and at least
+//     one non-empty checker digest.
+//  3. Encode a project with no tag and assert the field appears nowhere,
 //     while both claims still do.
+//
+// @evidence contracts/testing.md#behavioral-verification Exercises actual preparation and encoding with empty ignore membership, checking the fixed two-capability declarations, representative tag and checker-digest output, and absence of the docTags key for an untagged project. It does not exercise Git-filtered command execution or certify all source digests.
+// @evidence contracts/testing.md#independent-expectations The fixed expected set chooses graph.CapabilityDocTags and graph.CapabilitySourceDigests from the supported wire contract, independently of the producer's assembled list. Literal tag text, docTags key presence or absence, and at least one non-empty checker digest provide separate output expectations. A wrong non-empty digest or omitted additional source can remain indistinguishable here; neither digest contents nor complete coverage is asserted.
+// @evidence contracts/testing.md#distinguishing-cases Tagged and untagged projects both require the exact two-capability set and at least one non-empty checker digest. Only the tagged project requires the literal documentation tag and docTags key; the untagged project rejects that key anywhere in the dump.
+// @evidence contracts/testing.md#execution-ownership TestRunDeclaresTheCapabilityItsOutputCarries is a Go source-unit entry. runSourceProjection exercises the real sibling prepareCommand and encode operations with explicit empty ignore membership. The owning operations stay in this test process, without installing a consumer or building or starting a native product binary.
 func TestRunDeclaresTheCapabilityItsOutputCarries(t *testing.T) {
   tagged := runGraphdump(t, `/** @evidence docs/a.md#x Cited. */
 export function subject(): void {}
@@ -95,10 +99,9 @@ export function subject(): void {}
 
 // runGraphdump runs the command over a one-file project and returns its stdout.
 //
-// It goes through run(args) and the package streams rather than through os.Args,
-// flag.CommandLine, and an os.Stdout pipe. Those seams exist on the shipped
-// sibling for this reason, and this command grew them so its own claim could be
-// asserted against its own output without patching process globals.
+// It consumes this command's actual preparation and encoder with explicit empty
+// ignore membership. The package streams preserve its producer claim without
+// routing portable capability assertions through a Git child process.
 func runGraphdump(t *testing.T, source string) string {
   t.Helper()
   root := t.TempDir()
@@ -120,7 +123,7 @@ func runGraphdump(t *testing.T, source string) string {
   stdout, stderr = &out, &errOut
   defer func() { stdout, stderr = restoreStdout, restoreStderr }()
 
-  if code := run([]string{"--cwd", root, "--tsconfig", "tsconfig.json"}); code != 0 {
+  if code := runSourceProjection([]string{"--cwd", root, "--tsconfig", "tsconfig.json"}); code != 0 {
     t.Fatalf("graphdump exited %d: %s", code, errOut.String())
   }
   return out.String()
@@ -135,3 +138,14 @@ func writeGraphdumpFile(t *testing.T, path, content string) {
     t.Fatal(err)
   }
 }
+
+// runSourceProjection consumes the same real command preparation and encoder
+// over the fixture's explicit empty ignore membership, without acquiring Git.
+func runSourceProjection(args []string) int {
+  prepared, code := prepareCommand(args)
+  if prepared == nil {
+    return code
+  }
+  defer func() { _ = prepared.program.Close() }()
+  return prepared.encode(nil)
+}

package/cmd/graphdump/run_reports_an_unknown_flag_without_exiting_the_process_test.go

@@ -10,16 +10,19 @@ import (
 // argument returns an exit code and writes usage to the command's own stream,
 // instead of terminating the process.
 //
-// This is the negative twin of the capability case and the reason the seams
-// exist. The command used to parse flag.CommandLine, whose default error
-// handling is flag.ExitOnError: a malformed argument called os.Exit(2) from
-// inside run, which no test can observe and which would take a test binary down
-// with it. Nothing else about the command is reachable while that is true.
+// The package-controlled streams and ContinueOnError parser let the caller
+// observe rejection without terminating the test process. Help is distinguished
+// from an unknown flag even though both paths return a parser error.
 //
 //  1. Run the command with an unknown flag, capturing both streams.
 //  2. Assert it returns 2 rather than exiting, and that nothing reached stdout.
 //  3. Assert the usage text went to the command's stderr stream.
 //  4. Assert `-h` still succeeds, because asking for usage is not an error.
+//
+// @evidence contracts/testing.md#behavioral-verification Verifies that a bad argument returns an exit code and writes usage to the command's own stream, instead of terminating the process.
+// @evidence contracts/testing.md#independent-expectations Literal status 2 for an unknown flag follows the command's rejection policy; status 0 for -h follows its successful-help policy around flag.ErrHelp. Unknown-flag stderr must name the rejected flag and show -tsconfig usage, with empty stdout. Help must show usage and return 0; this case does not separately assert help stdout. These expectations are not computed from run.
+// @evidence contracts/testing.md#distinguishing-cases Run the command with an unknown flag, capturing both streams; Assert it returns 2 rather than exiting, and that nothing reached stdout; Assert the usage text went to the command's stderr stream. 4. Assert `-h` still succeeds, because asking for usage is not an error.
+// @evidence contracts/testing.md#execution-ownership TestRunReportsAnUnknownFlagWithoutExitingTheProcess is a Go source-unit entry. It calls the package's run function in-process with stdout and stderr swapped for buffers; both argument paths return before any project is loaded, so no consumer is installed and no binary is built or launched.
 func TestRunReportsAnUnknownFlagWithoutExitingTheProcess(t *testing.T) {
   var out, errOut bytes.Buffer
   restoreStdout, restoreStderr := stdout, stderr
@@ -41,10 +44,8 @@ func TestRunReportsAnUnknownFlagWithoutExitingTheProcess(t *testing.T) {
     t.Fatalf("stderr carried no usage text: %q", errOut.String())
   }
 
-  // The negative twin of the rejection: `flag.ContinueOnError` reports `-h` as
-  // an error too, and mapping every parse failure to 2 would turn the help flag
-  // into a failed invocation. The global flag set this command used to read
-  // exited 0 for it.
+  // ContinueOnError reports -h as ErrHelp; mapping every parse error to status 2
+  // would turn this successful usage request into a failed invocation.
   out.Reset()
   errOut.Reset()
   if code := run([]string{"-h"}); code != 0 {

package/cmd/graphdump/run_reports_an_unloadable_project_without_printing_a_dump_test.go

@@ -10,17 +10,18 @@ import (
 // the command cannot load exits non-zero, prints nothing to stdout, and names
 // what it could not load.
 //
-// The benchmark viewer pipeline runs this command through `execFileSync`, which
-// raises only on a non-zero exit and otherwise parses stdout as JSON. Every
-// failure path here therefore has to be a non-zero exit: turning one into 0
-// hands the pipeline an empty string, and the caller dies inside its JSON parse
-// with an opaque error instead of reading the diagnostic this command already
-// wrote. All three failure paths used to be unpinned, so replacing every
-// `return 1` with `return 0` broke no test.
+// A missing config must return status 1 without a JSON dump, leaving the failure
+// description on stderr. This case observes that one load-failure path, not every
+// command failure or an external viewer's process and JSON handling.
 //
 //  1. Run the command against a tsconfig that does not exist.
 //  2. Assert it returns 1 and wrote nothing to stdout.
 //  3. Assert stderr names the command and the path it could not load.
+//
+// @evidence contracts/testing.md#behavioral-verification Verifies that a project the command cannot load exits non-zero, prints nothing to stdout, and names what it could not load.
+// @evidence contracts/testing.md#independent-expectations Literal status 1, empty stdout and stderr containing graphdump: and absent.json follow the command's missing-config failure policy and stdout-is-JSON rule. They are not computed from run; a successful status or partial dump on this path fails these assertions. Other load-failure paths and external process exit handling are outside this case.
+// @evidence contracts/testing.md#distinguishing-cases Run the command against a tsconfig that does not exist; Assert it returns 1 and wrote nothing to stdout; Assert stderr names the command and the path it could not load.
+// @evidence contracts/testing.md#execution-ownership TestRunReportsAnUnloadableProjectWithoutPrintingADump is a Go source-unit entry. It calls run in-process against an empty temporary directory with a tsconfig name that does not exist, so driver.LoadProgram fails inside the test process; no consumer is installed and no binary is built or launched.
 func TestRunReportsAnUnloadableProjectWithoutPrintingADump(t *testing.T) {
   root := t.TempDir()
 

package/cmd/platform/command_operation_families_test.go

@@ -0,0 +1,192 @@
+package main
+
+import (
+  "bytes"
+  "strings"
+  "testing"
+)
+
+// TestPlatformCommandOperationFamilies 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 default Go entry owns five sequential named scenarios in its implementation package. Each calls actual run without a producer, process host, compiler Program or project fixture. The Go adapter selects this aggregate; its claims include the actual private scenario inputs and assertions below, not additional independently selected entries.
+func TestPlatformCommandOperationFamilies(t *testing.T) {
+  t.Run("TestCommandPrintsHelpAliases", scenarioTestCommandPrintsHelpAliases)
+  t.Run("TestCommandPrintsHelpWithoutArgs", scenarioTestCommandPrintsHelpWithoutArgs)
+  t.Run("TestCommandPrintsVersion", scenarioTestCommandPrintsVersion)
+  t.Run("TestCommandRefusesCompilerCommands", scenarioTestCommandRefusesCompilerCommands)
+  t.Run("TestCommandRejectsUnknown", scenarioTestCommandRejectsUnknown)
+}
+
+// scenarioTestCommandPrintsHelpAliases verifies explicit help commands share usage output.
+//
+// The helper exposes help aliases so users and package smoke scripts can ask
+// for metadata without depending on the JavaScript launcher. Each alias must
+// return before any compiler command is considered.
+//
+// This scenario protects the switch branch that handles -h, --help, and help.
+// The assertions focus on the helper-specific usage text because compiler
+// guidance belongs to the JavaScript ttsc and ttsx commands.
+//
+// 1. Invoke each documented help alias through the direct run helper.
+// 2. Capture stdout and stderr for every alias.
+// 3. Assert success, empty stderr, the version usage fragment and no demo text.
+//
+// Testing: behavioral-verification -h, --help and help return zero, empty stderr and ttsc --version text without demo.
+// Testing: independent-expectations The platform helper metadata surface defines its usage line independently of full compiler commands.
+// Testing: distinguishing-cases All three explicit aliases differ from the empty-argv usage case and the rejected build/check branches.
+// Testing: Execution ownership: The aggregate registers this original case name and calls actual private run in the owning command package, with no native artifact, Node process, compiler Program or project fixture. This private scenario is reviewed through its public aggregate because Go Evidence cannot select it.
+func scenarioTestCommandPrintsHelpAliases(t *testing.T) {
+  for _, argument := range []string{"-h", "--help", "help"} {
+    t.Run(argument, func(t *testing.T) {
+      code, stdout, stderr := capturePlatformCommand(t, argument)
+      if code != 0 || stderr != "" || !strings.Contains(stdout, "ttsc --version") || strings.Contains(stdout, "demo") {
+        t.Fatalf("help alias %q mismatch: code=%d stdout=%q stderr=%q", argument, code, stdout, stderr)
+      }
+    })
+  }
+}
+
+// scenarioTestCommandPrintsHelpWithoutArgs verifies the empty platform command prints usage.
+//
+// The per-platform helper is not the compiler front door. When a package smoke
+// check starts it without arguments, the binary should explain the helper role
+// instead of attempting project discovery or delegating to the JavaScript CLI.
+//
+// This scenario covers the no-args dispatch branch directly. It keeps the
+// compatibility helper's default behavior stable for package managers that run
+// installed binaries as a quick health check.
+//
+// 1. Invoke run with an empty argument slice.
+// 2. Capture the helper stdout and stderr writers.
+// 3. Assert a successful status and platform helper usage text.
+//
+// Testing: behavioral-verification Empty argv returns zero, empty stderr and the ttsc platform helper. usage fragment.
+// Testing: independent-expectations The metadata-only platform helper documents its role instead of attempting compiler project discovery.
+// Testing: distinguishing-cases The no-argument branch differs from explicit help aliases and unsupported commands.
+// Testing: Execution ownership: The aggregate registers this original case name and calls actual private run in the owning command package, with no native artifact, Node process, compiler Program or project fixture. This private scenario is reviewed through its public aggregate because Go Evidence cannot select it.
+func scenarioTestCommandPrintsHelpWithoutArgs(t *testing.T) {
+  code, stdout, stderr := capturePlatformCommand(t)
+  if code != 0 || stderr != "" || !strings.Contains(stdout, "ttsc platform helper.") {
+    t.Fatalf("empty command mismatch: code=%d stdout=%q stderr=%q", code, stdout, stderr)
+  }
+}
+
+// scenarioTestCommandPrintsVersion verifies the platform helper reports build metadata.
+//
+// Version output is a metadata path owned by the platform package. It
+// must stay project-free so package installation checks can identify the helper
+// binary even when no TypeScript project exists.
+//
+// This scenario covers the version dispatch branch and its alias forms. The
+// assertion checks helper branding, commit metadata, and Go runtime metadata
+// without depending on a release build's ldflags.
+//
+// 1. Invoke each documented version alias through the direct run helper.
+// 2. Capture stdout and stderr for every alias.
+// 3. Assert successful status and version metadata text.
+//
+// Testing: behavioral-verification -v, --version and version return zero, empty stderr and platform helper, commit and go metadata.
+// Testing: independent-expectations Metadata field presence follows the helper contract without assuming release ldflags or exact versions.
+// Testing: distinguishing-cases Three aliases exercise project-free version dispatch; help and command refusal have separate entries.
+// Testing: Execution ownership: The aggregate registers this original case name and calls actual private run in the owning command package, with no native artifact, Node process, compiler Program or project fixture. This private scenario is reviewed through its public aggregate because Go Evidence cannot select it.
+func scenarioTestCommandPrintsVersion(t *testing.T) {
+  for _, argument := range []string{"-v", "--version", "version"} {
+    t.Run(argument, func(t *testing.T) {
+      code, stdout, stderr := capturePlatformCommand(t, argument)
+      if code != 0 || stderr != "" ||
+        !strings.Contains(stdout, "ttsc platform helper") ||
+        !strings.Contains(stdout, "commit") ||
+        !strings.Contains(stdout, "go ") {
+        t.Fatalf("version alias %q mismatch: code=%d stdout=%q stderr=%q", argument, code, stdout, stderr)
+      }
+    })
+  }
+}
+
+// scenarioTestCommandRefusesCompilerCommands verifies build and check stay outside the helper.
+//
+// The platform package is a metadata and smoke-test binary, not the compiler
+// host. Build and check must tell callers to use the JavaScript ttsc CLI or a
+// plugin-selected sidecar instead of trying to inspect a consumer project here.
+//
+// This scenario covers both labels in the shared build/check refusal branch.
+// The diagnostic mentions typescript because that boundary is the reason these
+// commands are owned by the JavaScript launcher.
+//
+// 1. Invoke build and check through the direct run helper.
+// 2. Capture stdout and stderr for each command.
+// 3. Assert command-error status and the JavaScript CLI refusal message.
+//
+// Testing: behavioral-verification build and check each return status two, empty stdout and JavaScript-CLI guidance mentioning the command and typescript.
+// Testing: independent-expectations The platform helper owns metadata rather than compiler execution; both compiler labels must be refused.
+// Testing: distinguishing-cases Two rejected compiler command labels differ from a wholly unknown label and accepted metadata commands.
+// Testing: Execution ownership: The aggregate registers this original case name and calls actual private run in the owning command package, with no native artifact, Node process, compiler Program or project fixture. This private scenario is reviewed through its public aggregate because Go Evidence cannot select it.
+func scenarioTestCommandRefusesCompilerCommands(t *testing.T) {
+  for _, command := range []string{"build", "check"} {
+    t.Run(command, func(t *testing.T) {
+      code, stdout, stderr := capturePlatformCommand(t, command)
+      if code != 2 || stdout != "" ||
+        !strings.Contains(stderr, command+" is provided by the JavaScript ttsc CLI") ||
+        !strings.Contains(stderr, "typescript") {
+        t.Fatalf("%s refusal mismatch: code=%d stdout=%q stderr=%q", command, code, stdout, stderr)
+      }
+    })
+  }
+}
+
+// scenarioTestCommandRejectsUnknown verifies unsupported platform commands fail clearly.
+//
+// Unknown commands must stop in the platform helper wrapper. Falling through to
+// compiler behavior would blur the package boundary and make this binary look
+// like the full JavaScript ttsc command.
+//
+// This scenario covers the default dispatch branch. The error text includes the
+// unsupported command and points callers back to the JavaScript CLI help path.
+//
+// 1. Invoke a deliberately unsupported command name.
+// 2. Capture the helper stdout and stderr writers.
+// 3. Assert command-error status and the unknown-command diagnostic.
+//
+// Testing: behavioral-verification demo returns status two, empty stdout and an unknown-command diagnostic pointing to JavaScript CLI help.
+// Testing: independent-expectations The helper command contract rejects unsupported labels with an actionable usage error.
+// Testing: distinguishing-cases An unknown command differs from the explicit build/check refusal branches and accepted help/version.
+// Testing: Execution ownership: The aggregate registers this original case name and calls actual private run in the owning command package, with no native artifact, Node process, compiler Program or project fixture. This private scenario is reviewed through its public aggregate because Go Evidence cannot select it.
+func scenarioTestCommandRejectsUnknown(t *testing.T) {
+  code, stdout, stderr := capturePlatformCommand(t, "demo")
+  if code != 2 || stdout != "" ||
+    !strings.Contains(stderr, `unknown command "demo"`) ||
+    !strings.Contains(stderr, `run "ttsc --help" through the JavaScript CLI`) {
+    t.Fatalf("unknown command mismatch: code=%d stdout=%q stderr=%q", code, stdout, stderr)
+  }
+}
+
+// capturePlatformCommand observes actual dispatch with invocation-local stream buffers.
+//
+// Package writer seams are restored by defer on ordinary return and testing
+// failure. 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.
+// 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 capturePlatformCommand(t *testing.T, args ...string) (int, string, string) {
+  t.Helper()
+  previousOut, previousErr := stdout, stderr
+  defer func() { stdout, stderr = previousOut, previousErr }()
+  var output, errors bytes.Buffer
+  stdout, stderr = &output, &errors
+  code := run(args)
+  return code, output.String(), errors.String()
+}

package/cmd/platform/main.go

@@ -2,7 +2,9 @@
 //
 // The real compiler and runner commands live in the JavaScript launchers so
 // they can resolve the consuming project's `typescript` and
-// plugin descriptors. This binary only supplies version/platform metadata.
+// plugin descriptors. This binary supplies version/platform metadata, and the
+// hidden `__watch` command: the native Linux and Windows directory notification
+// helper the unplugin adapter runs.
 package main
 
 import (
@@ -11,6 +13,9 @@ import (
   "os"
   "runtime"
   "strings"
+
+  "github.com/samchon/ttsc/packages/ttsc/internal/sourceprocess"
+  "github.com/samchon/ttsc/packages/ttsc/internal/watchhelper"
 )
 
 var (
@@ -48,6 +53,11 @@ func run(args []string) int {
   case "-v", "--version", "version":
     printVersion(stdout)
     return 0
+  case "__watch":
+    // Hidden: it speaks a JSON protocol over stdio, not a CLI.
+    return watchhelper.Run(os.Stdin, stdout, stderr)
+  case "__source-process":
+    return sourceprocess.Run(args[1:], os.Stdin, stdout, stderr)
   case "build", "check":
     fmt.Fprintf(
       stderr,