ttsc 0.26.1 → 0.27.0

package/src/flags/schema.ts

@@ -219,6 +219,29 @@ export const FLAG_SCHEMA: readonly FlagSpec[] = [
     description: "Print the launcher version and exit.",
   },
 
+  // -------------------------------------------------------------------------
+  // Solution build mode — declared so the launcher can refuse it in its own
+  // voice instead of forwarding it.
+  //
+  // `createTsgoBuildArgs` opens the forwarded argv with `-p <tsconfig>` because
+  // ttsc resolves the project itself (extends chains, plugin config discovery,
+  // cache keys, resident session identity) and pins the result. A forwarded
+  // `--build` therefore always lands after `-p`, and tsgo answers with TS6369
+  // "Option '--build' must be the first command line argument" — a diagnostic
+  // that contradicts the command line the user actually typed. ttsc's plugin,
+  // cache, and emit architecture is built around one resolved project, so
+  // solution mode is unsupported rather than merely misordered.
+  // -------------------------------------------------------------------------
+  {
+    name: "--build",
+    aliases: ["-b"],
+    kind: "boolean",
+    subcommands: ["ttsc", "ttsx", "build", "check", "fix", "format"],
+    consumedBy: ["launcher"],
+    description:
+      "Refused by the launcher: ttsc pins one resolved project, so tsgo's solution-build mode is unsupported.",
+  },
+
   // -------------------------------------------------------------------------
   // Project location: shared by every subcommand.
   // -------------------------------------------------------------------------
@@ -612,10 +635,17 @@ export const FLAG_SCHEMA: readonly FlagSpec[] = [
   },
 
   // -------------------------------------------------------------------------
-  // `--tsgo-args` — JSON-encoded passthrough envelope the launcher emits on
-  // the way down to native sidecars. The sidecars decode it back into the
-  // tsgo argv. Listed here so the schema describes every flag the Go layers
-  // accept, not just the user-facing ones.
+  // `--tsgo-args` — JSON-encoded passthrough envelope a native sidecar decodes
+  // back into the tsgo argv. Listed here so the schema describes every flag
+  // the Go layers accept, not just the user-facing ones.
+  //
+  // The launcher no longer emits it. A CLI flag is fatal to any host whose
+  // `flag.FlagSet` does not declare it, and this one was added to a plugin
+  // protocol third-party hosts had already frozen, so every forwarded compiler
+  // flag exited 2 on a typia/nestia-shaped sidecar (issue #1188). The payload
+  // now rides the `TTSC_TSGO_ARGS` environment variable, which an unaware host
+  // simply ignores. ttsc's own hosts still accept the flag so an older
+  // launcher, or an embedder that composes sidecar argv itself, keeps working.
   // -------------------------------------------------------------------------
   {
     name: "--tsgo-args",
@@ -631,7 +661,7 @@ export const FLAG_SCHEMA: readonly FlagSpec[] = [
     ],
     consumedBy: ["host", "lint"],
     description:
-      "JSON-encoded tsgo passthrough argv (internal: emitted by runBuild).",
+      "JSON-encoded tsgo passthrough argv (internal: accepted by ttsc's own hosts; the launcher forwards it in TTSC_TSGO_ARGS).",
   },
   {
     name: "--plugins-json",

package/src/internal/createCanonicalTempDirectory.ts

@@ -0,0 +1,53 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+export interface CanonicalTempDirectoryOperations {
+  lstat(location: string): { isDirectory(): boolean };
+  mkdtemp(prefix: string): string;
+  realpath(location: string): string;
+}
+
+const FILESYSTEM_OPERATIONS: CanonicalTempDirectoryOperations = {
+  lstat: fs.lstatSync,
+  mkdtemp: fs.mkdtempSync,
+  realpath: fs.realpathSync.native,
+};
+
+/**
+ * Create a unique temporary directory under a frozen physical parent.
+ *
+ * The parent is resolved before creation so retargeting the caller's
+ * TEMP/TMPDIR alias cannot redirect later writes or recursive cleanup. The
+ * postflight accepts only a real directory that resolves to a direct child of
+ * that same parent; a rejected child is deliberately left untouched because no
+ * safe ownership identity was established.
+ */
+export function createCanonicalTempDirectory(
+  prefix: string,
+  parent: string = os.tmpdir(),
+  operations: CanonicalTempDirectoryOperations = FILESYSTEM_OPERATIONS,
+): string {
+  if (prefix.length === 0 || path.basename(prefix) !== prefix) {
+    throw new TypeError("ttsc: temporary directory prefix must be a basename");
+  }
+  const physicalParent = operations.realpath(path.resolve(parent));
+  if (!operations.lstat(physicalParent).isDirectory()) {
+    throw new Error(
+      `ttsc: temporary directory parent is not a directory: ${physicalParent}`,
+    );
+  }
+  const directory = operations.mkdtemp(path.join(physicalParent, prefix));
+  if (!operations.lstat(directory).isDirectory()) {
+    throw new Error(
+      `ttsc: temporary directory postflight is not a directory: ${directory}`,
+    );
+  }
+  const physicalDirectory = operations.realpath(directory);
+  if (path.dirname(physicalDirectory) !== physicalParent) {
+    throw new Error(
+      `ttsc: temporary directory escaped its physical parent: ${physicalDirectory}`,
+    );
+  }
+  return physicalDirectory;
+}

package/src/internal/projectInputPathIdentity.ts

@@ -11,7 +11,9 @@ export type FilesystemPathIdentity = {
 
 export type FilesystemPathIdentityOperations = {
   caseSensitive(directory: string): boolean;
+  lstat?(location: string): fs.Stats | fs.BigIntStats;
   platform: NodeJS.Platform;
+  readdir?(directory: string): string[];
   realpath(location: string): string;
   throwOnRealpathError: boolean;
 };
@@ -53,10 +55,16 @@ export function createFilesystemPathIdentityContext(
   const pathApi = platform === "win32" ? path.win32 : path;
   const throwOnRealpathError = operations.throwOnRealpathError ?? true;
   const realpath = operations.realpath ?? physicalRealpath;
+  const lstat = operations.lstat ?? fs.lstatSync;
+  const readdir = operations.readdir ?? fs.readdirSync;
   const caseSensitive =
     operations.caseSensitive ??
     ((directory: string) =>
-      filesystemDirectoryIsCaseSensitive(directory, platform));
+      filesystemDirectoryIsCaseSensitive(directory, platform, {
+        lstat,
+        readdir,
+        realpath,
+      }));
 
   const resolve = (location: string): FilesystemPathIdentity => {
     const normalized = resolveFilesystemPath(location, platform);
@@ -210,10 +218,15 @@ function physicalRealpath(location: string): string {
 function filesystemDirectoryIsCaseSensitive(
   directory: string,
   platform: NodeJS.Platform,
+  operations: {
+    lstat(location: string): fs.Stats | fs.BigIntStats;
+    readdir(directory: string): string[];
+    realpath(location: string): string;
+  },
 ): boolean {
   let entries: string[];
   try {
-    entries = fs.readdirSync(directory);
+    entries = operations.readdir(directory);
   } catch {
     return unprovenCaseSensitivity(platform);
   }
@@ -229,7 +242,7 @@ function filesystemDirectoryIsCaseSensitive(
     const alternate = alternateCase(name);
     if (alternate === name) continue;
     try {
-      fs.lstatSync(path.join(directory, alternate));
+      operations.lstat(path.join(directory, alternate));
       return false;
     } catch (error) {
       if (isMissingFilesystemEntry(error)) {
@@ -254,7 +267,7 @@ function filesystemDirectoryIsCaseSensitive(
       const alternate = alternateCase(name);
       if (alternate !== name) {
         try {
-          physicalRealpath(path.join(parent, alternate));
+          operations.realpath(path.join(parent, alternate));
           return false;
         } catch (error) {
           if (isMissingFilesystemEntry(error) === false) throw error;

package/src/internal/resolveNodeBinary.ts

@@ -0,0 +1,173 @@
+import childProcess from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+
+export type JavaScriptRuntimeCapabilities = {
+  bun: boolean;
+  executable?: string;
+  registerHooks: boolean;
+};
+
+type RuntimeCapabilityCacheEntry = {
+  capabilities: JavaScriptRuntimeCapabilities;
+  identity: string;
+};
+
+const runtimeCapabilityCache = new Map<string, RuntimeCapabilityCacheEntry>();
+
+/** Probe an interpreter instead of inferring its identity from the host. */
+export function javascriptRuntimeCapabilities(
+  runtime: string,
+  env: NodeJS.ProcessEnv,
+  cwd: string,
+): JavaScriptRuntimeCapabilities {
+  const effectiveEnv = { ...process.env, ...env };
+  const cacheKey = runtimeCapabilityCacheKey(runtime, effectiveEnv);
+  const beforeIdentity = runtimeExecutableIdentity(runtime);
+  if (cacheKey !== undefined && beforeIdentity !== undefined) {
+    const cached = runtimeCapabilityCache.get(cacheKey);
+    if (cached?.identity === beforeIdentity) return { ...cached.capabilities };
+    runtimeCapabilityCache.delete(cacheKey);
+  }
+  const result = childProcess.spawnSync(
+    runtime,
+    [
+      "-e",
+      `const Module = require("node:module"); process.stdout.write(JSON.stringify({ bun: typeof globalThis.Bun === "object", executable: process.execPath, registerHooks: typeof Module.registerHooks === "function" }));`,
+    ],
+    {
+      cwd,
+      encoding: "utf8",
+      env: effectiveEnv,
+      timeout: 30_000,
+      windowsHide: true,
+    },
+  );
+  let capabilities: JavaScriptRuntimeCapabilities = {
+    bun: false,
+    registerHooks: false,
+  };
+  if (result.status === 0) {
+    try {
+      const parsed = JSON.parse(
+        result.stdout,
+      ) as Partial<JavaScriptRuntimeCapabilities>;
+      capabilities = {
+        bun: parsed.bun === true,
+        ...(typeof parsed.executable === "string" &&
+        path.isAbsolute(parsed.executable)
+          ? { executable: path.resolve(parsed.executable) }
+          : {}),
+        registerHooks: parsed.registerHooks === true,
+      };
+    } catch {
+      // An incompatible executable is not a Node runtime candidate.
+    }
+  }
+  // Cache successful absolute candidates only when the child reports that same
+  // executable and both its lexical link and physical target retain the same
+  // filesystem identity. Relative/bare commands and wrappers can resolve
+  // differently by cwd/PATH/environment, negative probes can become valid later,
+  // and NODE_OPTIONS can load mutable user code, so none of those states are
+  // memoized. This removes a process spawn from the common path without
+  // authorizing a replaced or redirected runtime in a long-lived host.
+  const afterIdentity = runtimeExecutableIdentity(runtime);
+  if (
+    cacheKey !== undefined &&
+    capabilities.executable !== undefined &&
+    beforeIdentity !== undefined &&
+    beforeIdentity === afterIdentity &&
+    sameRuntimeExecutable(runtime, capabilities.executable)
+  ) {
+    runtimeCapabilityCache.set(cacheKey, {
+      capabilities: { ...capabilities },
+      identity: afterIdentity,
+    });
+  }
+  return capabilities;
+}
+
+/** True when a probe ran the candidate itself rather than a mutable wrapper. */
+function sameRuntimeExecutable(candidate: string, executable: string): boolean {
+  try {
+    const candidateStats = fs.statSync(candidate, { bigint: true });
+    const executableStats = fs.statSync(executable, { bigint: true });
+    return (
+      (candidateStats.ino !== 0n &&
+        candidateStats.dev === executableStats.dev &&
+        candidateStats.ino === executableStats.ino) ||
+      fs.realpathSync.native(candidate) === fs.realpathSync.native(executable)
+    );
+  } catch {
+    return false;
+  }
+}
+
+/** Stable cache key only for an absolute runtime with no preload authority. */
+function runtimeCapabilityCacheKey(
+  runtime: string,
+  env: NodeJS.ProcessEnv,
+): string | undefined {
+  if (!path.isAbsolute(runtime) || env.NODE_OPTIONS?.trim()) return undefined;
+  return path.resolve(runtime);
+}
+
+/** Identity of an executable spelling and the physical file it selects. */
+function runtimeExecutableIdentity(runtime: string): string | undefined {
+  if (!path.isAbsolute(runtime)) return undefined;
+  try {
+    const lexical = fs.lstatSync(runtime, { bigint: true });
+    const physicalPath = fs.realpathSync.native(runtime);
+    const physical = fs.statSync(physicalPath, { bigint: true });
+    return [
+      physicalPath,
+      lexical.dev,
+      lexical.ino,
+      lexical.mode,
+      lexical.size,
+      lexical.mtimeNs,
+      lexical.ctimeNs,
+      physical.dev,
+      physical.ino,
+      physical.mode,
+      physical.size,
+      physical.mtimeNs,
+      physical.ctimeNs,
+    ].join("\0");
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Locate a real Node runtime for ttsx and native JavaScript config loaders.
+ *
+ * Bun can directly evaluate a descriptor, but it does not implement the
+ * synchronous `module.registerHooks` contract used by those loaders.
+ */
+export function resolveNodeBinary(
+  env: NodeJS.ProcessEnv = process.env,
+  cwd: string = process.cwd(),
+): string | undefined {
+  const candidates = [
+    env.TTSC_NODE_BINARY,
+    process.env.TTSC_NODE_BINARY,
+    process.execPath,
+    "node",
+  ];
+  const seen = new Set<string>();
+  for (const candidate of candidates) {
+    if (candidate === undefined || candidate.trim() === "") continue;
+    if (seen.has(candidate)) continue;
+    seen.add(candidate);
+    const capabilities = javascriptRuntimeCapabilities(candidate, env, cwd);
+    if (
+      !capabilities.bun &&
+      capabilities.registerHooks &&
+      capabilities.executable !== undefined
+    ) {
+      return capabilities.executable;
+    }
+  }
+  return undefined;
+}

package/src/internal/resolveSafeCacheCleanupTargets.ts

@@ -0,0 +1,85 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import {
+  type FilesystemPathIdentityOperations,
+  createFilesystemPathIdentityContext,
+  isFilesystemPathIdentityWithin,
+  resolveFilesystemPath,
+} from "./projectInputPathIdentity";
+
+export interface SafeCacheCleanupTarget {
+  exists: boolean;
+  path: string;
+  requestedPath: string;
+}
+
+/**
+ * Resolve one cache-clean transaction to physical deletion targets.
+ *
+ * Every target is proved before the caller removes the first one. Existing
+ * aliases are pinned to their physical spelling, while a missing suffix keeps
+ * the identity of its nearest existing parent. Identity errors other than a
+ * genuinely missing path fail closed.
+ */
+export function resolveSafeCacheCleanupTargets(
+  projectRoot: string,
+  cacheDirectories: readonly string[],
+  operations: Partial<FilesystemPathIdentityOperations> = {},
+): SafeCacheCleanupTarget[] {
+  const identities = createFilesystemPathIdentityContext(operations);
+  const lstat = operations.lstat ?? fs.lstatSync;
+  const project = identities.resolve(projectRoot);
+  return cacheDirectories.map((cacheDirectory) => {
+    const requestedCache = resolveFilesystemPath(cacheDirectory);
+    // Fix every mutable alias ancestor before inspecting the terminal entry.
+    // All later identity checks and deletion paths use this physical-parent
+    // candidate, so a concurrent retarget cannot move ownership mid-proof.
+    const pinnedCache = path.join(
+      identities.resolve(path.dirname(requestedCache)).path,
+      path.basename(requestedCache),
+    );
+    const cache = identities.resolve(pinnedCache);
+    if (
+      requestedCache === path.parse(requestedCache).root ||
+      cache.path === path.parse(cache.path).root
+    ) {
+      throw new Error(
+        `ttsc: refusing to clean cache directory ${JSON.stringify(requestedCache)} because filesystem roots are never valid cache directories`,
+      );
+    }
+    if (isFilesystemPathIdentityWithin(cache.key, project.key)) {
+      throw new Error(
+        `ttsc: refusing to clean cache directory ${JSON.stringify(requestedCache)} because it equals or contains project root ${JSON.stringify(project.path)}; choose a dedicated cache directory`,
+      );
+    }
+    const status = lstatIfPresent(pinnedCache, lstat);
+    // Recursive rm removes a terminal symlink or junction itself rather than
+    // following it. Preserve that behavior while pinning any mutable alias in
+    // its ancestors to the physical parent selected by this transaction.
+    const deletionPath = status?.isSymbolicLink() ? pinnedCache : cache.path;
+    return {
+      exists: status !== undefined,
+      path: deletionPath,
+      requestedPath: requestedCache,
+    };
+  });
+}
+
+function lstatIfPresent(
+  location: string,
+  lstat: NonNullable<FilesystemPathIdentityOperations["lstat"]>,
+): fs.Stats | fs.BigIntStats | undefined {
+  try {
+    return lstat(location);
+  } catch (error) {
+    if (
+      error instanceof Error &&
+      "code" in error &&
+      (error.code === "ENOENT" || error.code === "ENOTDIR")
+    ) {
+      return undefined;
+    }
+    throw error;
+  }
+}

package/src/launcher/internal/assertNoSolutionBuild.ts

@@ -0,0 +1,40 @@
+import { type ParseResult } from "../../flags/parser";
+
+/**
+ * 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.
+ *
+ * Both launchers refuse it, because both reach tsgo through the same pinned
+ * project. `ttsx` additionally builds one entry inside that project, so a mode
+ * whose whole purpose is compiling many projects has nothing to mean there
+ * either.
+ *
+ * Presence — not the parsed boolean — is what is refused: `--build false` still
+ * asks for a mode ttsc does not implement, and silently consuming it would drop
+ * the flag with no diagnostic at all.
+ *
+ * What this deliberately does not reach is a `--build` that belongs to the
+ * program `ttsx` is running. `runTtsx` parses with
+ * `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.
+ */
+export function assertNoSolutionBuild(
+  result: ParseResult,
+  errorPrefix: string,
+): void {
+  if (!result.values.has("--build")) return;
+  throw new Error(
+    `${errorPrefix} --build (solution mode) is not supported; ttsc resolves and pins one project per run, so compile each referenced project with its own ttsc -p <tsconfig> run`,
+  );
+}