ttsc 0.30.4 → 0.31.0

package/src/internal/spawnSyncWithLowDescriptors.ts

@@ -0,0 +1,227 @@
+import { type SpawnSyncOptions, spawnSync } from "node:child_process";
+import fs from "node:fs";
+
+import { E2ETrace } from "./E2ETrace";
+import { OwnedSynchronousProcess } from "./OwnedSynchronousProcess";
+import type { SpawnSyncOutputFiles } from "./SpawnSyncOutputFiles";
+
+/**
+ * Launch through a fresh shell-free child broker with inherited stdio 0..2.
+ *
+ * The caller owns stdout/stderr capture files and reconstructs their contents;
+ * this operation returns command status and errors through a private report.
+ * Its supported broker mode ignores stdin and uses no shell. It does not
+ * reproduce arbitrary spawn input or stdio modes. Native initialization or
+ * inherited preloads can still allocate descriptors; low numeric descriptor
+ * values and successful target launch are not guaranteed. Parsed JSON report
+ * fields are trusted after syntax parsing rather than structurally validated.
+ * Enabled private tracing observes the broker and target as separate actual
+ * primitives, loading the same private observer in the broker. Its root travels
+ * in private broker arguments without altering the target environment. Trace
+ * loading/write failures leave missing evidence while target results remain
+ * unchanged; optional observation adds native IO and metadata/output work.
+ *
+ * @evidence contracts/common.md#principled-implementation A fresh Node child inherits only descriptors zero through two, opens owned capture files itself and launches the actual argv; its private status report preserves target exit and native error information rather than broker status alone.
+ * @evidence contracts/common.md#clear-and-simple-design One broker boundary separates descriptor acquisition from the already loaded parent; caller-owned capture remains external and the private result file carries only status/error metadata.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The isolated broker addresses actual POSIX source-descriptor limits without patching spawn or inventing compiler output; unreadable or syntactically invalid JSON reports become protocol errors, while parsed field shapes are trusted; no shell quoting workaround is introduced.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs distinguish command results from file-backed output and state no-input/no-shell support, with separate acknowledgment tags.
+ * @evidence contracts/portability.md#os-neutral-implementation Supported POSIX fallback passes executable and argv without shell syntax; Node opens captures inside the broker. cwd/env configure that broker; argv0, uid/gid, killSignal and timeout are forwarded to its target. Other arbitrary spawn modes are not reconstructed.
+ * @evidence contracts/performance.md#efficient-algorithms One broker is attempted and, if its initialization succeeds, it attempts one target. Option/argv/report serialization, report UTF-8 read/JSON parsing and native/env/path work scale with their inputs. Target output remains in caller capture files; temporary report/metadata text and native work have no adapter quota.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Command spawning and file output have external effects; this owner cannot share them solely because command and argv match.
+ *
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Child descriptor closure and parent report removal are attempted in finally; failures are suppressed and capture-owner directory cleanup is also best effort. Omitted timeout leaves the broker unbounded; a supplied timeout adds five seconds to its broker option, including timeout zero becoming five seconds here. A timeout signal need not end the process immediately, and forced broker termination does not join every target descendant.
+ */
+export function spawnSyncWithLowDescriptors(
+  command: string,
+  args: readonly string[],
+  options: SpawnSyncOptions,
+  output: SpawnSyncOutputFiles,
+): ReturnType<typeof spawnSync> {
+  const report = `${output.stdout}.ttsc-result-${process.pid}-${nextBrokerResult++}`;
+  const targetOptions = JSON.stringify({
+    ...(options.argv0 === undefined ? {} : { argv0: options.argv0 }),
+    ...(options.gid === undefined ? {} : { gid: options.gid }),
+    ...(options.killSignal === undefined
+      ? {}
+      : { killSignal: options.killSignal }),
+    ...(options.timeout === undefined ? {} : { timeout: options.timeout }),
+    ...(options.uid === undefined ? {} : { uid: options.uid }),
+  });
+  const brokerTimeout =
+    options.timeout === undefined ? undefined : options.timeout + 5_000;
+  // Only an enabled observer needs the private compiled helper path. Failure
+  // to load the observer leaves missing evidence, not a different command.
+  let traceModule = "";
+  if (process.env.TTSC_E2E_TRACE) {
+    try {
+      traceModule = require.resolve("./E2ETrace");
+    } catch {}
+  }
+  try {
+    const brokerArgs = [
+      "-e",
+      LOW_DESCRIPTOR_BROKER_SOURCE,
+      "--",
+      report,
+      output.stdout,
+      output.stderr,
+      targetOptions,
+      traceModule,
+      process.env.TTSC_E2E_TRACE ?? "",
+      command,
+      ...args,
+    ];
+    const brokerOptions: SpawnSyncOptions = {
+      cwd: options.cwd,
+      encoding: undefined,
+      env: options.env,
+      input: undefined,
+      killSignal: options.killSignal,
+      shell: false,
+      stdio: [0, 1, 2],
+      timeout: brokerTimeout,
+      windowsHide: true,
+    };
+    const trace = E2ETrace.begin(
+      process.execPath,
+      brokerArgs,
+      brokerOptions,
+      "low-descriptor-broker",
+    );
+    // The target ignores stdin. An owned relay uses that same no-input mode;
+    // ordinary broker initialization retains its inherited stdin contract.
+    const broker =
+      OwnedSynchronousProcess.launch(process.execPath, brokerArgs, {
+        ...brokerOptions,
+        stdio: ["ignore", 1, 2],
+      }) ?? spawnSync(process.execPath, brokerArgs, brokerOptions);
+    E2ETrace.result(trace, broker);
+    if (broker.error !== undefined) return broker;
+    if (broker.status !== 0) {
+      return brokerProtocolFailure(
+        broker,
+        `exited with status ${String(broker.status)}`,
+      );
+    }
+    let parsed: SerializedSpawnResult;
+    try {
+      parsed = JSON.parse(fs.readFileSync(report, "utf8"));
+    } catch (error) {
+      return brokerProtocolFailure(
+        broker,
+        error instanceof Error ? error.message : String(error),
+      );
+    }
+    return {
+      ...broker,
+      ...(parsed.error === undefined
+        ? { error: undefined }
+        : { error: deserializeSpawnError(parsed.error) }),
+      pid: parsed.pid,
+      signal: parsed.signal,
+      status: parsed.status,
+    };
+  } finally {
+    try {
+      fs.rmSync(report, { force: true });
+    } catch {
+      // The capture owner removes the containing directory after reading it.
+    }
+  }
+}
+
+interface SerializedSpawnError {
+  code?: string;
+  errno?: number;
+  message: string;
+  name?: string;
+  path?: string;
+  spawnargs?: string[];
+  syscall?: string;
+}
+
+interface SerializedSpawnResult {
+  error?: SerializedSpawnError;
+  pid: number;
+  signal: NodeJS.Signals | null;
+  status: number | null;
+}
+
+let nextBrokerResult = 0;
+
+function deserializeSpawnError(serialized: SerializedSpawnError): Error {
+  const error = new Error(serialized.message) as NodeJS.ErrnoException & {
+    path?: string;
+    spawnargs?: string[];
+  };
+  if (serialized.name !== undefined) error.name = serialized.name;
+  if (serialized.code !== undefined) error.code = serialized.code;
+  if (serialized.errno !== undefined) error.errno = serialized.errno;
+  if (serialized.path !== undefined) error.path = serialized.path;
+  if (serialized.spawnargs !== undefined)
+    error.spawnargs = serialized.spawnargs;
+  if (serialized.syscall !== undefined) error.syscall = serialized.syscall;
+  return error;
+}
+
+function brokerProtocolFailure(
+  broker: ReturnType<typeof spawnSync>,
+  reason: string,
+): ReturnType<typeof spawnSync> {
+  const error = new Error(
+    `ttsc: low-descriptor spawn broker failed: ${reason}`,
+  ) as NodeJS.ErrnoException;
+  error.code = "EIO";
+  return { ...broker, error, signal: null, status: null };
+}
+
+const LOW_DESCRIPTOR_BROKER_SOURCE = String.raw`
+const childProcess = require("node:child_process");
+const fs = require("node:fs");
+const [report, stdout, stderr, encodedOptions, traceModule, traceRoot, command, ...args] = process.argv.slice(1);
+const options = JSON.parse(encodedOptions);
+let traceObserver;
+if (traceRoot && traceModule) {
+  try { traceObserver = require(traceModule).E2ETrace; } catch {}
+}
+let stdoutFd;
+let stderrFd;
+let result;
+try {
+  stdoutFd = fs.openSync(stdout, "w");
+  stderrFd = stderr === stdout ? stdoutFd : fs.openSync(stderr, "w");
+  const trace = traceObserver?.begin(command, args, options, "low-descriptor-target", traceRoot);
+  result = childProcess.spawnSync(command, args, {
+    ...options,
+    shell: false,
+    stdio: ["ignore", stdoutFd, stderrFd],
+  });
+  traceObserver?.result(trace, result);
+} catch (error) {
+  result = { error, pid: 0, signal: null, status: null };
+} finally {
+  if (stderrFd !== undefined && stderrFd !== stdoutFd) {
+    try { fs.closeSync(stderrFd); } catch {}
+  }
+  if (stdoutFd !== undefined) {
+    try { fs.closeSync(stdoutFd); } catch {}
+  }
+}
+const sourceError = result.error;
+const error = sourceError === undefined ? undefined : {
+  code: sourceError.code,
+  errno: sourceError.errno,
+  message: sourceError.message,
+  name: sourceError.name,
+  path: sourceError.path,
+  spawnargs: sourceError.spawnargs,
+  syscall: sourceError.syscall,
+};
+fs.writeFileSync(report, JSON.stringify({
+  ...(error === undefined ? {} : { error }),
+  pid: result.pid,
+  signal: result.signal,
+  status: result.status,
+}));
+`;

package/src/internal/tsconfig.ts

@@ -0,0 +1,16 @@
+/**
+ * Public entry of `ttsc/tsconfig`.
+ *
+ * How a `tsconfig.json` is read is decided once, in ttsc: the JSONC grammar,
+ * the resolution of an `extends` specifier by TypeScript-Go's rule, and whether
+ * a plugin entry's path is relative, as ttsc's plugin loader reads it.
+ * `@ttsc/unplugin` reads the same configs to build its membership policy, its
+ * alias overlay, and the snapshot of the config chain, so it imports these
+ * rules rather than copying them. This barrel is the one module path such a
+ * reader imports, so the implementation keeps one declaration per file.
+ */
+export * from "../compiler/internal/project/compilerUsesCaseSensitiveFileNames";
+export * from "../compiler/internal/project/parseJsonc";
+export * from "../compiler/internal/project/resolveTsconfigExtends";
+export * from "../compiler/internal/project/tsconfigExtendsFileCandidates";
+export * from "../plugin/internal/load/isRelativePluginSpecifier";

package/src/launcher/internal/PendingResidentCheckWatchChanges.ts

@@ -0,0 +1,94 @@
+import { type ResidentCheckWatchChange } from "../../compiler/internal/build/ResidentCheckWatchChange";
+import { type WatchInputChange } from "./watch/WatchInputChange";
+
+/**
+ * Coalesces filesystem events until the next resident check-watch cycle.
+ *
+ * A full reload dominates every narrower signal. Program invalidation remains
+ * distinct so a project-input module creation/deletion can cold-load the
+ * Program without discarding the selected execution or restarting the sidecar.
+ *
+ * @evidence contracts/common.md#principled-implementation Two path sets preserve changed versus declared external inputs, while reload dominates and clears narrower state; program invalidation remains a separate supported signal.
+ * @evidence contracts/common.md#clear-and-simple-design push folds event precedence and take transfers one deterministic batch then resets; callers own the scheduling and native path identity supplied here.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The reload/compiler/config distinctions come from watcher protocol semantics rather than an event-count threshold or fixture-specific path.
+ * @evidence contracts/common.md#meaningful-documentation Native class and method paragraphs explain signal dominance, external membership and reset ownership; members receive no checklist tags.
+ * @evidence contracts/performance.md#efficient-algorithms At most two Set insertions retain each event path, including string hashing/equality work. Draining sorts each distinct population with string comparisons and allocates returned references; retained path bytes grow with unique spellings until take or escalation.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This accumulator merges delivery data, not completed or in-flight producer work; the caller owns scheduling checks and the session owns process reuse.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources The pending cycle owns distinct path strings and releases them on take or escalation; population is bounded by distinct events between cycles, without a separate numeric cap if the caller stops draining.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation Coalesces event paths held as opaque strings; it resolves no path and touches no filesystem.
+ */
+export class PendingResidentCheckWatchChanges {
+  private readonly changed = new Set<string>();
+  private readonly external = new Set<string>();
+  private invalidate = false;
+  private reload = false;
+
+  /**
+   * Fold one filesystem event into the pending cycle.
+   *
+   * A config or plugin change, a compiler-topology change without a path, or an
+   * explicit `reload` escalates to a full reload and discards narrower signals.
+   * Otherwise the path is recorded as changed, and additionally as external
+   * when it is a declared project-rule input.
+   *
+   * @evidence contracts/common.md#principled-implementation Reload precedence is checked before incremental folding, and project events are included in both changed and external sets as required by resident checks.
+   * @evidence contracts/common.md#clear-and-simple-design One method updates the three signal forms and path sets, preserving the take boundary as the sole batch transfer.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Compiler events without a path conservatively select the supported full-reload operation instead of inventing a path or retrying a failed assumption.
+   * @evidence contracts/common.md#meaningful-documentation Native paragraphs identify escalation triggers and distinguish changed from external inputs, with prose separated from tags.
+   * @evidence contracts/performance.md#efficient-algorithms Normal events use at most two Set insertions, including path-string hashing and equality; escalation releases both populations rather than rebuilding an event history.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work Folding duplicate delivery paths establishes no shared computation result; actual check scheduling and resident reuse belong to consumers.
+   * @evidence contracts/performance.md#bound-retention-and-release-resources This accumulator retains unique paths until take or full reload; no bound independent of the caller's drain rate is imposed.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation Records event paths as opaque strings in sets and compares only event kinds; it resolves no path and touches no filesystem.
+   */
+  public push(change?: WatchInputChange, reload = false): void {
+    if (reload || change?.kind === "config" || change?.kind === "plugin") {
+      this.reload = true;
+      this.invalidate = false;
+      this.changed.clear();
+      this.external.clear();
+      return;
+    }
+    if (this.reload) return;
+    if (change?.invalidate === true) this.invalidate = true;
+    if (change?.path === undefined) {
+      if (change?.kind === "compiler") {
+        this.reload = true;
+        this.invalidate = false;
+        this.changed.clear();
+        this.external.clear();
+      }
+      return;
+    }
+    this.changed.add(change.path);
+    if (change.kind === "project") this.external.add(change.path);
+  }
+
+  /**
+   * Return everything accumulated since the last call, with paths sorted, and
+   * reset to empty.
+   *
+   * @evidence contracts/common.md#principled-implementation Optional fields encode only present signals, sorted arrays transfer set contents, and resetting every flag/set makes the next batch independent.
+   * @evidence contracts/common.md#clear-and-simple-design Batch construction and complete state reset stay in the same synchronous operation, without exposing mutable sets to consumers.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Absent fields remain omitted in this watch batch instead of using consumer-specific sentinels; the wire adapter separately selects protocol fields and handles coordinator-only reload.
+   * @evidence contracts/common.md#meaningful-documentation The method documents deterministic path order and destructive drain semantics needed by callers.
+   * @evidence contracts/performance.md#efficient-algorithms Each distinct path population is copied and sorted once, including path-string comparison costs; returned arrays scale with unique references and reset releases the accumulator's ownership.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work Draining transfers delivery ownership and resets state; reusing an earlier batch would replay effects rather than share equivalent producer work.
+   * @evidence contracts/performance.md#bound-retention-and-release-resources Ownership of arrays transfers to the caller while the accumulator clears its sets and flags; retaining returned batches is the consumer's responsibility.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation Draining reads and clears this instance's flags and opaque path sets without resolving filesystem identity or calling a native process API.
+   */
+  public take(): ResidentCheckWatchChange {
+    const change: ResidentCheckWatchChange = {
+      ...(this.reload ? { reload: true } : {}),
+      ...(this.invalidate ? { invalidate: true } : {}),
+      ...(this.changed.size === 0 ? {} : { changed: [...this.changed].sort() }),
+      ...(this.external.size === 0
+        ? {}
+        : { external: [...this.external].sort() }),
+    };
+    this.reload = false;
+    this.invalidate = false;
+    this.changed.clear();
+    this.external.clear();
+    return change;
+  }
+}

package/src/launcher/internal/TtscBuildMode.ts

@@ -0,0 +1,14 @@
+/**
+ * Supported compiler commands sharing the launcher build adapter. Mutation
+ * commands reject watch and single-file modes; check suppresses one-shot emit.
+ *
+ * @evidence contracts/common.md#principled-implementation Four literal commands represent exactly the compiler commands that share the launcher build adapter.
+ * @evidence contracts/common.md#clear-and-simple-design A closed union lets the same command decision serve CLI execution and direct unit verification.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Unsupported command strings cannot enter the adapter through this maintained type.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states the supported command distinction and its mutation/check consequences.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources A type declaration acquires and holds no runtime resource.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms A type declaration chooses no processing strategy.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work A type declaration computes nothing, so there is no work to share.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation This type declaration describes a data shape only; it opens no file, builds no path and branches on no platform.
+ */
+export type TtscBuildMode = "build" | "check" | "fix" | "format";

package/src/launcher/internal/TtsxEntryOptions.ts

@@ -0,0 +1,92 @@
+import path from "node:path";
+
+import { readCompilerOptionOccurrence } from "../../flags/readCompilerOptionOccurrence";
+import type { parseTtsxCLI } from "./parseTtsxCLI";
+
+/**
+ * Prepares Node entry options without invoking the compiler or host.
+ *
+ * @evidence contracts/common.md#principled-implementation Separate JavaScript build-option applicability from preload path classification; public launcher callers consume these exact results before starting native execution.
+ * @evidence contracts/common.md#clear-and-simple-design One namespace groups two pure entry-boundary projections with one private lexical relative-path predicate.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Only supported launcher fields and native path APIs decide behavior; no consumer-specific preload, private Node method or fixture answer is substituted.
+ * @evidence contracts/common.md#meaningful-documentation Native purpose and operation prose explain launcher/Node ownership and optional-value meaning, separated from acknowledgment tags.
+ * @evidence contracts/portability.md#os-neutral-implementation Native path.isAbsolute/path.resolve own filesystem spelling; bare and scoped package specifiers retain Node module-resolution ownership without manual case or slash rewriting.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms The namespace groups two concrete operations; their methods describe their own input processing.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This invocation-local projection coordinates no shared computation and retains no historical answer cache.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Only call-local arrays or a returned path string exist; no process, directory, handle or task is acquired.
+ */
+export namespace TtsxEntryOptions {
+  /**
+   * Lists the options JavaScript entries cannot apply to an up-front TypeScript
+   * build.
+   *
+   * Values and program arguments are not options; their spelling remains
+   * intact.
+   *
+   * @evidence contracts/common.md#principled-implementation The parsed launcher fields name up-front build policy; native occurrence widths distinguish compiler and response-file requests from their scalar operands before JavaScript entry applicability is reported.
+   * @evidence contracts/common.md#clear-and-simple-design A fixed field projection followed by one native-frame traversal preserves original request spellings and deterministic diagnostic order.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The result is the actual caller diagnostic input, not a second CLI parser or a test-only whitelist.
+   * @evidence contracts/common.md#meaningful-documentation Native purpose and operation prose explain launcher/Node ownership and optional-value meaning, separated from acknowledgment tags.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation This pure option record and token classification resolves no filesystem path and starts no process.
+   * @evidence contracts/performance.md#efficient-algorithms Traversing T forwarded tokens advances by each native occurrence width in O(T+B) time for their B inspected token/list bytes and retains at most O(T) returned request references; the fixed launcher fields require bounded additional work.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work This invocation-local projection coordinates no shared computation and retains no historical answer cache.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Only call-local arrays or a returned path string exist; no process, directory, handle or task is acquired.
+   */
+  export function unsupportedJavaScriptBuildOptions(
+    parsed: Exclude<ReturnType<typeof parseTtsxCLI>, "help" | "version">,
+  ): string[] {
+    const forwarded: string[] = [];
+    for (let index = 0; index < parsed.tsgoFlags.length; ) {
+      const token = parsed.tsgoFlags[index]!;
+      if (token.startsWith("-") || token.startsWith("@")) forwarded.push(token);
+      index += readCompilerOptionOccurrence(parsed.tsgoFlags, index).width;
+    }
+    return [
+      ...(parsed.project !== undefined ? ["--project"] : []),
+      ...(parsed.cacheDir !== undefined ? ["--cache-dir"] : []),
+      ...(parsed.checkers !== undefined ? ["--checkers"] : []),
+      ...(parsed.noPlugins ? ["--no-plugins"] : []),
+      ...(parsed.singleThreaded ? ["--singleThreaded"] : []),
+      ...forwarded,
+    ];
+  }
+
+  /**
+   * Anchors file preloads to the invocation directory and leaves package names
+   * to Node.
+   *
+   * Relative file spellings and already absolute paths use native path
+   * resolution; scoped and subpath package requests must not be anchored to the
+   * launcher install.
+   *
+   * @evidence contracts/common.md#principled-implementation Native absolute paths and explicit relative spellings denote files, while other requests remain module specifiers for Node resolution.
+   * @evidence contracts/common.md#clear-and-simple-design One native absolute check and one lexical relative check precede path.resolve; package specifiers return unchanged.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts No foreign resolver is patched and no installed-package lookup or guessed extension changes the caller request.
+   * @evidence contracts/common.md#meaningful-documentation Native purpose and operation prose explain launcher/Node ownership and optional-value meaning, separated from acknowledgment tags.
+   * @evidence contracts/portability.md#os-neutral-implementation Native path.isAbsolute and path.resolve preserve host path semantics; explicit dot/slash or dot/backslash relative forms are classified without case folding or manual file URLs.
+   * @evidence contracts/performance.md#efficient-algorithms Fixed prefix checks and one native path normalization cost O(P) path bytes with no filesystem traversal or per-package lookup.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work This invocation-local projection coordinates no shared computation and retains no historical answer cache.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Only call-local arrays or a returned path string exist; no process, directory, handle or task is acquired.
+   */
+  export function resolvePreload(cwd: string, preload: string): string {
+    if (path.isAbsolute(preload) || isRelativeSpecifier(preload)) {
+      return path.resolve(cwd, preload);
+    }
+    return preload;
+  }
+
+  /**
+   * Explicit relative file spellings; bare package specifiers remain module
+   * requests.
+   */
+  function isRelativeSpecifier(specifier: string): boolean {
+    return (
+      specifier === "." ||
+      specifier === ".." ||
+      specifier.startsWith("./") ||
+      specifier.startsWith("../") ||
+      specifier.startsWith(".\\") ||
+      specifier.startsWith("..\\")
+    );
+  }
+}

package/src/launcher/internal/assertNoSolutionBuild.ts

@@ -1,18 +1,16 @@
-import { type ParseResult } from "../../flags/parser";
+import { type ParseResult } from "../../flags/ParseResult";
 
 /**
  * Refuse tsgo's solution-build mode (`--build` / `-b`) in the launcher's own
  * voice, for whichever launcher parsed the arguments.
  *
- * Every ttsc build lane hands tsgo an argument list that opens with the project
- * ttsc resolved (`-p <tsconfig>` in `createTsgoBuildArgs`), because ttsc — not
- * tsgo — owns the `extends` chain, plugin config discovery, cache keys, and the
- * resident session's identity, and pins that one resolved project instead of
- * forwarding raw argv. A forwarded `--build` therefore always arrives after
- * `-p`, and tsgo replies "Option '--build' must be the first command line
- * argument" even though the user wrote it first. No spelling of the command
- * line can satisfy that diagnostic, so the flag is rejected here rather than
- * forwarded into an error that blames the user's argument order.
+ * Project-dependent builds select one config for plugin discovery, cache keys
+ * and resident identity. The direct compiler argv opens with that selection
+ * (`-p <tsconfig>` in `createTsgoBuildArgs`); TypeScript-Go still reads its own
+ * config and inheritance. Forwarding `--build` on this lane would place it
+ * after `-p`, producing "Option '--build' must be the first command line
+ * argument" even when the user wrote it first. Rejecting the unsupported mode
+ * here preserves the single-project contract instead of blaming user order.
  *
  * Both launchers refuse it, because both reach tsgo through the same pinned
  * project. `ttsx` additionally builds one entry inside that project, so a mode
@@ -28,6 +26,15 @@ import { type ParseResult } from "../../flags/parser";
  * `forwardAfterFirstPositional` and `honorDoubleDashSeparator`, so a token
  * after the entry lands in `result.tail` and never in `result.values`; reading
  * `values` is what keeps `ttsx script.ts --build` the user program's own flag.
+ *
+ * @evidence contracts/common.md#principled-implementation Presence in the launcher's parsed values identifies a requested unsupported compiler mode; the program's post-entry arguments are outside this map.
+ * @evidence contracts/common.md#clear-and-simple-design A shared pre-build guard owns this unsupported-mode diagnostic for both launchers instead of rewriting compiler argument order.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The rejection follows the supported single-project contract, including an explicit false token, without compensating for a tsgo diagnostic through a synthetic solution build.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain pinned-project semantics, presence detection and the boundary with user-program flags, with tags separated from prose.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources One presence check returns or throws without retaining the parsed map or acquiring a native resource.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms One canonical-key membership check makes a fixed mode decision; flag parsing and compiler execution belong to their existing owners.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work A mode refusal coordinates no producer computation or cross-call result.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation This guard inspects a canonical option key and constructs diagnostic text; native paths, processes and OS capability discovery are outside its operation.
  */
 export function assertNoSolutionBuild(
   result: ParseResult,

package/src/launcher/internal/assertTtsxNoWatch.ts

@@ -0,0 +1,49 @@
+import { CompilerArgumentsInspection } from "../../compiler/internal/CompilerArgumentsInspection";
+import { readCompilerOptionOccurrence } from "../../flags/readCompilerOptionOccurrence";
+import { readCompilerOptionValues } from "../../flags/readCompilerOptionValues";
+import { resolveFlagSpec } from "../../flags/resolveFlagSpec";
+
+/**
+ * Refuse `--watch` (or `-w`) before the one-shot ttsx check or build starts.
+ *
+ * A watch that restarts the program is a different feature; the message names
+ * the tools that provide its two halves. Arguments after the entry belong to
+ * the program and never reach this guard. Parsing supplies its compiler tokens
+ * without a cwd and remains in-memory. Preparation supplies the selected
+ * project's actual compiler cwd, after project/reference discovery and before
+ * effective-option reporting, cache writes or a checked build, to inspect
+ * response frames through their shared owner.
+ *
+ * Even an explicit false/null watch request is unsupported, matching direct
+ * launcher flags. Inspection failures propagate before a build starts. The
+ * observation does not pin response bytes against subsequent filesystem edits.
+ *
+ * @evidence contracts/common.md#principled-implementation The same refusal owns direct launcher requests and observed response options; native occurrence widths preserve scalar operands and preparation supplies the selected project root.
+ * @evidence contracts/common.md#clear-and-simple-design One mode guard serves parsing and the pre-build boundary, delegating response expansion to the existing inspection owner.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts No compiler grammar or watcher behavior is replaced; unsupported watch requests throw before execution and inspection failures remain failures.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs distinguish direct parsing, project-relative response observation and program argv, and state the observation's lifetime limit.
+ * @evidence contracts/portability.md#os-neutral-implementation Response resolution and UTF decoding belong to the shared native filesystem inspector; the guard receives a native directory rather than assuming the invocation cwd.
+ * @evidence contracts/performance.md#efficient-algorithms One occurrence scan finds response requests and another finds watch. When expansion is needed its delegated path/read/hash/token costs follow all expanded bytes, depth and occurrences without a fixed cap.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Each admission observes the current response contents and retains no historical answer.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Inspection transfers call-local arrays and synchronous observations; this guard retains no handles, process or cache.
+ */
+export function assertTtsxNoWatch(
+  args: readonly string[],
+  compilerCwd?: string,
+): void {
+  if (
+    compilerCwd !== undefined &&
+    readCompilerOptionValues(args).responseFiles.length !== 0
+  ) {
+    args = CompilerArgumentsInspection.inspect(args, compilerCwd).args;
+  }
+  let watching = false;
+  for (let index = 0; !watching && index < args.length; ) {
+    watching = resolveFlagSpec(args[index]!)?.name === "--watch";
+    index += readCompilerOptionOccurrence(args, index).width;
+  }
+  if (!watching) return;
+  throw new Error(
+    "ttsx: --watch is not supported; ttsx type-checks once and then runs the entry. For a watching type-check use `ttsc --watch --noEmit`; to restart the program on changes use `node --watch --require ttsc/register <entry.ts>`. Arguments after the entry, including --watch, go to the program.",
+  );
+}