ttsc 0.30.3 → 0.31.0

package/lib/plugin/internal/source/resolveSourceBuildCachePaths.js

@@ -0,0 +1,236 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveSourceBuildCachePaths = resolveSourceBuildCachePaths;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const SidecarEnvironment_1 = require("../../../compiler/internal/sharedHost/SidecarEnvironment");
+const SourceBuildCacheLayout_1 = require("./SourceBuildCacheLayout");
+/**
+ * Resolve all source-plugin build cache directories for one invocation.
+ *
+ * `pluginRoot` stores compiled plugin binaries; `goBuildRoot` is the Go object
+ * cache passed as `GOCACHE` while ttsc builds those binaries. The default Go
+ * cache lives under `root`; `TTSC_GO_CACHE_DIR` is independently resolved,
+ * while external `GOCACHE` preserves its supplied value for Go to validate.
+ * Their selection provenance keeps the ownership policies distinct.
+ *
+ * @evidence contracts/common.md#principled-implementation Plugin and Go paths derive from one root while provenance preserves dedicated ttsc ownership versus external GOCACHE.
+ * @evidence contracts/common.md#clear-and-simple-design Root selection and Go override selection are separate helpers; the result carries paths with their ownership discriminant.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Workspace markers and environment overrides are supported configuration inputs rather than project-name exceptions.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain each payload and independent Go ownership, separated from tags under the documentation guidance.
+ * @evidence contracts/portability.md#os-neutral-implementation Native path APIs anchor ttsc overrides; environment names use Windows case-insensitive lookup, and external GOCACHE preserves Go's supplied spelling and validation semantics.
+ * @evidence contracts/performance.md#efficient-algorithms Default discovery walks ancestor directories, reading each inspected manifest's bytes and snapshotting entries at the node_modules/.cache/ttsc layout levels; those entry populations are not capped or recursively traversed. Path processing depends on visited text, while Windows override lookup scans current environment names. Explicit root selection skips ancestor discovery; Go provenance selection still observes its overrides.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Shared workspace placement permits producer caches to be shared, but this path query coordinates neither completed nor in-flight computations and establishes no answer equivalence.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Returning paths and provenance acquires no retained cache entry or handle.
+ */
+function resolveSourceBuildCachePaths(projectRoot, cacheDir, env = process.env) {
+    const root = resolveSourceBuildCacheRoot(projectRoot, cacheDir, env);
+    const goBuild = resolveGoBuildCacheRoot(root, projectRoot, env);
+    return {
+        root,
+        pluginRoot: node_path_1.default.join(root, PLUGIN_CACHE_DIRNAME),
+        goBuildRoot: goBuild.root,
+        goBuildRootSource: goBuild.source,
+    };
+}
+const LOCAL_CACHE_PARENT_DIRNAME = ".cache";
+const PLUGIN_CACHE_DIRNAME = "plugins";
+// Directories whose presence marks a monorepo/workspace root, so every package
+// in the workspace can select one cache location. Reuse of a compiled plugin
+// still requires the build owner's key and artifact validity. `package.json`
+// with a `workspaces` field (yarn/npm/bun) is checked
+// separately in isWorkspaceRootDir.
+const WORKSPACE_ROOT_MARKER_FILES = ["pnpm-workspace.yaml"];
+/**
+ * Resolve the cache root for one invocation.
+ *
+ * Priority:
+ *
+ * 1. Explicit `cacheDir` option (resolved relative to `projectRoot`);
+ * 2. `TTSC_CACHE_DIR` environment variable (relative to `projectRoot`);
+ * 3. `<workspaceRoot>/node_modules/.cache/ttsc` — project-local by default.
+ *
+ * There is no automatic global (`~/.cache`) fallback. Removing the selected
+ * workspace's node_modules reclaims its default cache; explicit and environment
+ * overrides may select storage elsewhere and keep their own lifetime.
+ */
+function resolveSourceBuildCacheRoot(projectRoot, cacheDir, env) {
+    if (cacheDir) {
+        return node_path_1.default.resolve(projectRoot, cacheDir);
+    }
+    const configured = SidecarEnvironment_1.SidecarEnvironment.read(env, "TTSC_CACHE_DIR");
+    if (configured) {
+        // Anchor a relative TTSC_CACHE_DIR to the project root (not the process
+        // cwd) so a programmatic host whose cwd differs from the project still
+        // resolves — and later cleans — the same cache. Absolute values pass
+        // through path.resolve unchanged.
+        return node_path_1.default.resolve(projectRoot, configured);
+    }
+    return node_path_1.default.join(resolveWorkspaceRoot(projectRoot), SourceBuildCacheLayout_1.SourceBuildCacheLayout.NODE_MODULES_DIRNAME, LOCAL_CACHE_PARENT_DIRNAME, SourceBuildCacheLayout_1.SourceBuildCacheLayout.TTSC_CACHE_DIRNAME);
+}
+/**
+ * Resolve the monorepo/workspace root for `projectRoot` so packages can select
+ * the same default cache location. This query does not certify artifact reuse.
+ *
+ * Walks up from `projectRoot` and returns, in order of preference: the NEAREST
+ * ancestor that is a workspace root (holds `pnpm-workspace.yaml`, or a
+ * `package.json` with a `workspaces` field); else the nearest ancestor that
+ * contains an installation; else the outermost ttsc-only cache owner at or
+ * below the nearest ordinary package manifest, or `projectRoot` itself.
+ *
+ * A nonempty, unmarked ttsc-only `.cache/ttsc` payload is fallback cache
+ * evidence rather than an installation. Empty or marked ttsc roots remain
+ * installation evidence, including the interval before marker publication.
+ * Remembering the outermost fallback owner avoids choosing a nearer unmarked
+ * payload merely because it contains previously produced ttsc output.
+ *
+ * Nearest (not highest) so an unrelated ancestor that happens to declare
+ * `workspaces` — for example a `package.json` in the user's home directory —
+ * cannot override a nearer declared workspace root.
+ */
+function resolveWorkspaceRoot(projectRoot) {
+    let dir = node_path_1.default.resolve(projectRoot);
+    let nearestNodeModulesOwner = null;
+    let outermostTtscCacheOwner = null;
+    let packageBoundarySeen = false;
+    for (;;) {
+        if (isWorkspaceRootDir(dir)) {
+            return dir;
+        }
+        const nodeModules = classifyNodeModulesBoundary(dir);
+        if (nearestNodeModulesOwner === null && nodeModules === "installation") {
+            nearestNodeModulesOwner = dir;
+        }
+        else if (nodeModules === "ttsc-cache" && !packageBoundarySeen) {
+            outermostTtscCacheOwner = dir;
+        }
+        packageBoundarySeen ||= hasPackageManifest(dir);
+        const parent = node_path_1.default.dirname(dir);
+        if (parent === dir) {
+            break;
+        }
+        dir = parent;
+    }
+    return (nearestNodeModulesOwner ??
+        outermostTtscCacheOwner ??
+        node_path_1.default.resolve(projectRoot));
+}
+/**
+ * Classify the evidence carried by `dir/node_modules`.
+ *
+ * An empty directory remains installation evidence for package managers and
+ * callers that materialize the root before populating it. The distinguished
+ * `ttsc-cache` shape is an ordinary `.cache/ttsc` layout with no sibling.
+ * Counting an unmarked legacy layout as an installation would let ttsc's output
+ * change its own workspace-root query. This is placement evidence, not proof of
+ * every descendant's ownership: selected cache owners validate their actual
+ * roots and entries before writes or deletion. Aliases and unreadable
+ * directories at the inspected layout levels remain installation evidence.
+ */
+function classifyNodeModulesBoundary(dir) {
+    const nodeModules = node_path_1.default.join(dir, SourceBuildCacheLayout_1.SourceBuildCacheLayout.NODE_MODULES_DIRNAME);
+    if (!node_fs_1.default.existsSync(nodeModules))
+        return "absent";
+    try {
+        if (node_fs_1.default.lstatSync(nodeModules).isSymbolicLink())
+            return "installation";
+        const entries = node_fs_1.default.readdirSync(nodeModules, { withFileTypes: true });
+        const cache = entries.length === 1 ? entries[0] : undefined;
+        if (!isOrdinaryDirectory(cache, LOCAL_CACHE_PARENT_DIRNAME)) {
+            return "installation";
+        }
+        const cacheEntries = node_fs_1.default.readdirSync(node_path_1.default.join(nodeModules, LOCAL_CACHE_PARENT_DIRNAME), { withFileTypes: true });
+        const ttsc = cacheEntries.length === 1 ? cacheEntries[0] : undefined;
+        if (!isOrdinaryDirectory(ttsc, SourceBuildCacheLayout_1.SourceBuildCacheLayout.TTSC_CACHE_DIRNAME)) {
+            return "installation";
+        }
+        const ttscRoot = node_path_1.default.join(nodeModules, LOCAL_CACHE_PARENT_DIRNAME, SourceBuildCacheLayout_1.SourceBuildCacheLayout.TTSC_CACHE_DIRNAME);
+        if (SourceBuildCacheLayout_1.SourceBuildCacheLayout.isEmptyOrMarkedDefaultWorkspaceCacheRoot(ttscRoot)) {
+            return "installation";
+        }
+        return "ttsc-cache";
+    }
+    catch {
+        return "installation";
+    }
+}
+/** Probe for the package boundary used by fallback discovery. */
+function hasPackageManifest(dir) {
+    try {
+        return node_fs_1.default.statSync(node_path_1.default.join(dir, "package.json")).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/** Match one named ordinary directory in a collected snapshot. */
+function isOrdinaryDirectory(entry, name) {
+    return entry?.name === name && entry.isDirectory() && !entry.isSymbolicLink();
+}
+/** Recognize a supported workspace declaration at one ancestor. */
+function isWorkspaceRootDir(dir) {
+    for (const marker of WORKSPACE_ROOT_MARKER_FILES) {
+        if (node_fs_1.default.existsSync(node_path_1.default.join(dir, marker))) {
+            return true;
+        }
+    }
+    return packageJsonDeclaresWorkspaces(node_path_1.default.join(dir, "package.json"));
+}
+/** Recognize nonempty array and packages-array workspace declarations. */
+function packageJsonDeclaresWorkspaces(packageJsonPath) {
+    let text;
+    try {
+        text = node_fs_1.default.readFileSync(packageJsonPath, "utf8");
+    }
+    catch {
+        return false;
+    }
+    try {
+        const workspaces = JSON.parse(text)
+            .workspaces;
+        // A real workspace root declares a NON-EMPTY package list (an array, or an
+        // object with a `packages` array). Ignore `false`, `[]`, `null`, or `{}` so
+        // a disabled or empty declaration on an unrelated ancestor cannot hijack
+        // the cache location.
+        if (Array.isArray(workspaces)) {
+            return workspaces.length > 0;
+        }
+        if (workspaces !== null && typeof workspaces === "object") {
+            const packages = workspaces.packages;
+            return Array.isArray(packages) && packages.length > 0;
+        }
+        return false;
+    }
+    catch {
+        return false;
+    }
+}
+/** Select a Go object path together with cleanup-ownership provenance. */
+function resolveGoBuildCacheRoot(root, projectRoot, env) {
+    const dedicated = SidecarEnvironment_1.SidecarEnvironment.read(env, "TTSC_GO_CACHE_DIR");
+    if (dedicated) {
+        // Anchor a relative TTSC_GO_CACHE_DIR to the project root, matching
+        // TTSC_CACHE_DIR, so the build and a later `clean` from a different cwd
+        // agree on the directory. Absolute values pass through unchanged.
+        return {
+            root: node_path_1.default.resolve(projectRoot, dedicated),
+            source: "TTSC_GO_CACHE_DIR",
+        };
+    }
+    const external = SidecarEnvironment_1.SidecarEnvironment.read(env, "GOCACHE");
+    if (external && external.length > 0) {
+        return {
+            root: external,
+            source: "GOCACHE",
+        };
+    }
+    return {
+        root: node_path_1.default.join(root, SourceBuildCacheLayout_1.SourceBuildCacheLayout.GO_BUILD_CACHE_DIRNAME),
+        source: "ttsc-cache",
+    };
+}
+//# sourceMappingURL=resolveSourceBuildCachePaths.js.map

package/lib/plugin/internal/source/resolveSourceBuildCachePaths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolveSourceBuildCachePaths.js","sourceRoot":"","sources":["../../../../src/plugin/internal/source/resolveSourceBuildCachePaths.ts"],"names":[],"mappings":"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"}

package/lib/plugin/internal/source/selectPluginModuleReplaceDirectories.d.ts

@@ -0,0 +1,29 @@
+import type { IPluginModuleReplaceDirectory } from "./IPluginModuleReplaceDirectory";
+/**
+ * Select unversioned local replacement targets outside the observed physical
+ * module root, preserving Go's module identity and original target spelling.
+ *
+ * The caller supplies directives parsed by Go and its actual physical-path
+ * observer. This selection neither parses go.mod nor proves an observation's
+ * native identity. Internal targets, including observed aliases, stay in the
+ * module's own source population.
+ *
+ * @evidence contracts/common.md#principled-implementation Go-local path syntax admits only absolute or dot-relative unversioned targets; observed native containment separates the external population, and module/version sorting preserves the existing record order.
+ * @evidence contracts/common.md#clear-and-simple-design Directive filtering, original-root anchoring and physical containment form one internal selection operation; parsing and native observation remain supplied by the owner.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Actual parsed directives and observed paths drive selection, not a handwritten go.mod parser or fixture-specific module names.
+ * @evidence contracts/common.md#meaningful-documentation Native prose identifies parsed-input and physical-observation premises and distinguishes internal source ownership.
+ * @evidence contracts/portability.md#os-neutral-implementation Node native path operations anchor relative targets and compare containment; Go dot-relative backslash syntax is accepted only on Windows as before. Supplied physical observations retain their owner's best-effort limitations.
+ * @evidence contracts/performance.md#efficient-algorithms All directive entries are visited; selected local targets require native path text work and delegated physical observation, followed by sorting returned module/version text. Observations can traverse ancestors and are not claimed constant.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This selection adds no historical directive or identity cache; the supplied observer and upstream source-key owner retain their existing reuse policies.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Selected records transfer to the caller; no native handle, child, task or historical population is retained by this operation.
+ */
+export declare function selectPluginModuleReplaceDirectories(root: string, replacements: readonly {
+    New?: {
+        Path?: string;
+        Version?: string;
+    };
+    Old?: {
+        Path?: string;
+        Version?: string;
+    };
+}[], physicalPath: (location: string) => string): IPluginModuleReplaceDirectory[];

package/lib/plugin/internal/source/selectPluginModuleReplaceDirectories.js

@@ -0,0 +1,68 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.selectPluginModuleReplaceDirectories = selectPluginModuleReplaceDirectories;
+const node_path_1 = __importDefault(require("node:path"));
+/**
+ * Select unversioned local replacement targets outside the observed physical
+ * module root, preserving Go's module identity and original target spelling.
+ *
+ * The caller supplies directives parsed by Go and its actual physical-path
+ * observer. This selection neither parses go.mod nor proves an observation's
+ * native identity. Internal targets, including observed aliases, stay in the
+ * module's own source population.
+ *
+ * @evidence contracts/common.md#principled-implementation Go-local path syntax admits only absolute or dot-relative unversioned targets; observed native containment separates the external population, and module/version sorting preserves the existing record order.
+ * @evidence contracts/common.md#clear-and-simple-design Directive filtering, original-root anchoring and physical containment form one internal selection operation; parsing and native observation remain supplied by the owner.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Actual parsed directives and observed paths drive selection, not a handwritten go.mod parser or fixture-specific module names.
+ * @evidence contracts/common.md#meaningful-documentation Native prose identifies parsed-input and physical-observation premises and distinguishes internal source ownership.
+ * @evidence contracts/portability.md#os-neutral-implementation Node native path operations anchor relative targets and compare containment; Go dot-relative backslash syntax is accepted only on Windows as before. Supplied physical observations retain their owner's best-effort limitations.
+ * @evidence contracts/performance.md#efficient-algorithms All directive entries are visited; selected local targets require native path text work and delegated physical observation, followed by sorting returned module/version text. Observations can traverse ancestors and are not claimed constant.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This selection adds no historical directive or identity cache; the supplied observer and upstream source-key owner retain their existing reuse policies.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Selected records transfer to the caller; no native handle, child, task or historical population is retained by this operation.
+ */
+function selectPluginModuleReplaceDirectories(root, replacements, physicalPath) {
+    const physicalRoot = physicalPath(root);
+    const out = [];
+    for (const replacement of replacements) {
+        const modulePath = replacement.Old?.Path;
+        const spelled = replacement.New?.Path;
+        if (modulePath === undefined ||
+            spelled === undefined ||
+            replacement.New?.Version !== undefined ||
+            !isFilesystemPath(spelled))
+            continue;
+        const directory = physicalPath(node_path_1.default.resolve(root, spelled));
+        const relative = node_path_1.default.relative(physicalRoot, directory);
+        if (relative !== ".." &&
+            !relative.startsWith(`..${node_path_1.default.sep}`) &&
+            !node_path_1.default.isAbsolute(relative))
+            continue;
+        out.push({
+            directory,
+            modulePath,
+            spelled,
+            ...(replacement.Old?.Version === undefined
+                ? {}
+                : { version: replacement.Old.Version }),
+        });
+    }
+    return out.sort((left, right) => left.modulePath === right.modulePath
+        ? (left.version ?? "") < (right.version ?? "")
+            ? -1
+            : 1
+        : left.modulePath < right.modulePath
+            ? -1
+            : 1);
+}
+/** Go local target syntax: absolute or dot-relative with native separators. */
+function isFilesystemPath(target) {
+    return (node_path_1.default.isAbsolute(target) ||
+        target.startsWith("./") ||
+        target.startsWith("../") ||
+        (process.platform === "win32" &&
+            (target.startsWith(".\\") || target.startsWith("..\\"))));
+}
+//# sourceMappingURL=selectPluginModuleReplaceDirectories.js.map

package/lib/plugin/internal/source/selectPluginModuleReplaceDirectories.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"selectPluginModuleReplaceDirectories.js","sourceRoot":"","sources":["../../../../src/plugin/internal/source/selectPluginModuleReplaceDirectories.ts"],"names":[],"mappings":";;;;;;AAAA,0DAA6B;AAI7B;;;;;;;;;;;;;;;;;GAiBG;AACH,8CACE,IAAY,EACZ,YAGG,EACH,YAA0C;IAE1C,MAAM,YAAY,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;IACxC,MAAM,GAAG,GAAoC,EAAE,CAAC;IAChD,KAAK,MAAM,WAAW,IAAI,YAAY,EAAE,CAAC;QACvC,MAAM,UAAU,GAAG,WAAW,CAAC,GAAG,EAAE,IAAI,CAAC;QACzC,MAAM,OAAO,GAAG,WAAW,CAAC,GAAG,EAAE,IAAI,CAAC;QACtC,IACE,UAAU,KAAK,SAAS;YACxB,OAAO,KAAK,SAAS;YACrB,WAAW,CAAC,GAAG,EAAE,OAAO,KAAK,SAAS;YACtC,CAAC,gBAAgB,CAAC,OAAO,CAAC;YAE1B,SAAS;QACX,MAAM,SAAS,GAAG,YAAY,CAAC,mBAAI,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC;QAC5D,MAAM,QAAQ,GAAG,mBAAI,CAAC,QAAQ,CAAC,YAAY,EAAE,SAAS,CAAC,CAAC;QACxD,IACE,QAAQ,KAAK,IAAI;YACjB,CAAC,QAAQ,CAAC,UAAU,CAAC,KAAK,mBAAI,CAAC,GAAG,EAAE,CAAC;YACrC,CAAC,mBAAI,CAAC,UAAU,CAAC,QAAQ,CAAC;YAE1B,SAAS;QACX,GAAG,CAAC,IAAI,CAAC;YACP,SAAS;YACT,UAAU;YACV,OAAO;YACP,GAAG,CAAC,WAAW,CAAC,GAAG,EAAE,OAAO,KAAK,SAAS;gBACxC,CAAC,CAAC,EAAE;gBACJ,CAAC,CAAC,EAAE,OAAO,EAAE,WAAW,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC;SAC1C,CAAC,CAAC;IACL,CAAC;IACD,OAAO,GAAG,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAC9B,IAAI,CAAC,UAAU,KAAK,KAAK,CAAC,UAAU;QAClC,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,IAAI,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,IAAI,EAAE,CAAC;YAC5C,CAAC,CAAC,CAAC,CAAC;YACJ,CAAC,CAAC,CAAC;QACL,CAAC,CAAC,IAAI,CAAC,UAAU,GAAG,KAAK,CAAC,UAAU;YAClC,CAAC,CAAC,CAAC,CAAC;YACJ,CAAC,CAAC,CAAC,CACR,CAAC;AACJ,CAAC;AAED,+EAA+E;AAC/E,SAAS,gBAAgB,CAAC,MAAc;IACtC,OAAO,CACL,mBAAI,CAAC,UAAU,CAAC,MAAM,CAAC;QACvB,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC;QACvB,MAAM,CAAC,UAAU,CAAC,KAAK,CAAC;QACxB,CAAC,OAAO,CAAC,QAAQ,KAAK,OAAO;YAC3B,CAAC,MAAM,CAAC,UAAU,CAAC,KAAK,CAAC,IAAI,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,CAC3D,CAAC;AACJ,CAAC"}

package/lib/plugin/internal/source/spawnGoTool.d.ts

@@ -0,0 +1,22 @@
+import { type SpawnSyncOptionsWithStringEncoding, type SpawnSyncReturns } from "node:child_process";
+/**
+ * Run a Go tool command synchronously and return its complete output.
+ *
+ * Output is captured through files rather than pipes, so no buffer ceiling can
+ * turn a verbose `go build` into a failure. On Windows a `.cmd` or `.bat`
+ * wrapper is run through a generated shim with exact argument quoting; a
+ * descriptor-exhaustion failure on POSIX is retried through the low-descriptor
+ * broker.
+ *
+ * @evidence contracts/common.md#principled-implementation Child streams are routed to owned files and then reconstructed as the normal SpawnSyncReturns shape; Windows wrappers receive one-pass environment expansion and native argv quoting rather than unsafe shell concatenation.
+ * @evidence contracts/common.md#clear-and-simple-design Output capture lifetime is separate from process selection and wrapper quoting; finally covers spawn failures and output-read failures alike.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts POSIX broker retry handles actual descriptor exhaustion and Windows cmd handles supported batch wrappers; neither changes a failed build into an assumed success.
+ * @evidence contracts/common.md#meaningful-documentation Native comments explain file capture, missing-wrapper ENOENT and the platform errno/quoting semantics; prose and tags remain distinct.
+ * @evidence contracts/portability.md#os-neutral-implementation Windows cmd wrappers are isolated with verbatim arguments and case-insensitive environment lookup; native binaries and POSIX go use Node spawning and the descriptor broker.
+ * @evidence contracts/performance.md#efficient-algorithms File capture avoids the pipe buffer ceiling but performs native acquisition/spawn/full output reads and decoding. Windows selection adds PATH/PATHEXT/native queries; wrapper environment/payload construction processes full argument/name bytes and regex quoting whose backtracking is not asserted linear here. Complete stdout/stderr strings and transient buffers/serialized argv data contribute memory beyond argument count.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Go commands can write build/module state and cannot share a result merely because executable and arguments match.
+ *
+ * @evidence contracts/performance.md#bound-retention-and-release-resources The call delegates file/descriptor acquisition to the capture owner and disposes it in finally; cleanup can fail and replace an earlier result/error. Returned decoded output belongs to the caller with no independent byte ceiling. Synchronous completion concerns the selected command, not proof that arbitrary inherited-handle descendants have terminated.
+ */
+export declare function spawnGoTool(goBinary: string, args: readonly string[], options: SpawnSyncOptionsWithStringEncoding): SpawnSyncReturns<string>;

package/lib/plugin/internal/source/spawnGoTool.js

@@ -0,0 +1,164 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.spawnGoTool = spawnGoTool;
+const node_child_process_1 = require("node:child_process");
+const node_crypto_1 = __importDefault(require("node:crypto"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_url_1 = require("node:url");
+const node_util_1 = __importDefault(require("node:util"));
+const captureProcessOutput_1 = require("../../../compiler/internal/captureProcessOutput");
+const E2ETrace_1 = require("../../../internal/E2ETrace");
+const OwnedSynchronousProcess_1 = require("../../../internal/OwnedSynchronousProcess");
+const spawnSyncResilient_1 = require("../../../internal/spawnSyncResilient");
+const GoToolResolution_1 = require("./GoToolResolution");
+const windowsGoCommandArgs_1 = require("./windowsGoCommandArgs");
+/**
+ * Run a Go tool command synchronously and return its complete output.
+ *
+ * Output is captured through files rather than pipes, so no buffer ceiling can
+ * turn a verbose `go build` into a failure. On Windows a `.cmd` or `.bat`
+ * wrapper is run through a generated shim with exact argument quoting; a
+ * descriptor-exhaustion failure on POSIX is retried through the low-descriptor
+ * broker.
+ *
+ * @evidence contracts/common.md#principled-implementation Child streams are routed to owned files and then reconstructed as the normal SpawnSyncReturns shape; Windows wrappers receive one-pass environment expansion and native argv quoting rather than unsafe shell concatenation.
+ * @evidence contracts/common.md#clear-and-simple-design Output capture lifetime is separate from process selection and wrapper quoting; finally covers spawn failures and output-read failures alike.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts POSIX broker retry handles actual descriptor exhaustion and Windows cmd handles supported batch wrappers; neither changes a failed build into an assumed success.
+ * @evidence contracts/common.md#meaningful-documentation Native comments explain file capture, missing-wrapper ENOENT and the platform errno/quoting semantics; prose and tags remain distinct.
+ * @evidence contracts/portability.md#os-neutral-implementation Windows cmd wrappers are isolated with verbatim arguments and case-insensitive environment lookup; native binaries and POSIX go use Node spawning and the descriptor broker.
+ * @evidence contracts/performance.md#efficient-algorithms File capture avoids the pipe buffer ceiling but performs native acquisition/spawn/full output reads and decoding. Windows selection adds PATH/PATHEXT/native queries; wrapper environment/payload construction processes full argument/name bytes and regex quoting whose backtracking is not asserted linear here. Complete stdout/stderr strings and transient buffers/serialized argv data contribute memory beyond argument count.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Go commands can write build/module state and cannot share a result merely because executable and arguments match.
+ *
+ * @evidence contracts/performance.md#bound-retention-and-release-resources The call delegates file/descriptor acquisition to the capture owner and disposes it in finally; cleanup can fail and replace an earlier result/error. Returned decoded output belongs to the caller with no independent byte ceiling. Synchronous completion concerns the selected command, not proof that arbitrary inherited-handle descendants have terminated.
+ */
+function spawnGoTool(goBinary, args, options) {
+    // The child's streams go to files rather than pipes, so no output ceiling
+    // applies: `spawnSync` only bounds what it must hold in this process's
+    // memory, and a `go build` that says a great deal is not a failure to invent
+    // a limit for. See `captureProcessOutput`.
+    const capture = (0, captureProcessOutput_1.captureProcessOutput)();
+    const spawnOptions = {
+        ...options,
+        stdio: ["ignore", capture.stdoutFd, capture.stderrFd],
+    };
+    try {
+        const result = spawnGoToolProcess(goBinary, args, spawnOptions, {
+            stderr: capture.stderrPath,
+            stdout: capture.stdoutPath,
+        });
+        const stdout = capture.read("stdout", "utf8");
+        const stderr = capture.read("stderr", "utf8");
+        return {
+            ...result,
+            output: [null, stdout, stderr],
+            stderr,
+            stdout,
+        };
+    }
+    finally {
+        capture.dispose();
+    }
+}
+/**
+ * Launch the Go tool, routing through cmd.exe only where Windows needs a
+ * wrapper. Output routing is the caller's concern; this owns process
+ * selection.
+ */
+function spawnGoToolProcess(goBinary, args, options, output) {
+    if (process.platform !== "win32") {
+        return (0, spawnSyncResilient_1.spawnSyncResilient)(goBinary, args, options, output);
+    }
+    const inheritedEnv = options.env ?? process.env;
+    const resolved = GoToolResolution_1.GoToolResolution.resolveWindowsGoTool(goBinary, inheritedEnv, spawnWorkingDirectory(options.cwd));
+    if (!resolved.wrapper) {
+        const nativeArgs = [...args];
+        return E2ETrace_1.E2ETrace.synchronous(goBinary, nativeArgs, options, "windows-go-tool", () => OwnedSynchronousProcess_1.OwnedSynchronousProcess.launch(goBinary, nativeArgs, options) ??
+            (0, node_child_process_1.spawnSync)(goBinary, nativeArgs, options));
+    }
+    // Supply the install-guidance ENOENT result when no regular wrapper candidate
+    // was selected, before cmd.exe becomes the actual child. Candidate stat
+    // failures do not distinguish every absence/permission cause. Node refuses to
+    // launch a `.cmd` or `.bat` without a shell (CVE-2024-27980) and answers
+    // EINVAL, which would hide that the file does not exist.
+    if (resolved.location === null) {
+        return missingGoTool(goBinary, args);
+    }
+    const shim = createWindowsGoCommandShim([resolved.location, ...args]);
+    const command = GoToolResolution_1.GoToolResolution.readWindowsEnvironmentValue(inheritedEnv, "COMSPEC") ??
+        GoToolResolution_1.GoToolResolution.readWindowsEnvironmentValue(process.env, "COMSPEC") ??
+        "cmd.exe";
+    const commandArgs = (0, windowsGoCommandArgs_1.windowsGoCommandArgs)(shim.payload);
+    const trace = E2ETrace_1.E2ETrace.begin(command, commandArgs, options, "windows-go-wrapper");
+    const wrapperOptions = {
+        ...options,
+        env: { ...inheritedEnv, ...shim.environment },
+        shell: false,
+        // The /c payload is already one fully quoted Windows command line.
+        windowsVerbatimArguments: true,
+    };
+    const result = OwnedSynchronousProcess_1.OwnedSynchronousProcess.launch(command, commandArgs, wrapperOptions) ??
+        (0, node_child_process_1.spawnSync)(command, commandArgs, wrapperOptions);
+    E2ETrace_1.E2ETrace.result(trace, result);
+    return result;
+}
+/**
+ * Construct a no-process ENOENT-shaped result for unavailable wrapper
+ * selection. Errno comes from Node's system-error map; this is not a recorded
+ * native spawn failure proving the wrapper's exact absence/permission cause.
+ */
+function missingGoTool(goBinary, args) {
+    const error = Object.assign(new Error(`spawnSync ${goBinary} ENOENT`), {
+        code: "ENOENT",
+        errno: systemErrno("ENOENT"),
+        path: goBinary,
+        spawnargs: [...args],
+        syscall: `spawnSync ${goBinary}`,
+    });
+    return {
+        error,
+        output: [null, "", ""],
+        pid: 0,
+        signal: null,
+        status: null,
+        stderr: "",
+        stdout: "",
+    };
+}
+/** The platform errno Node reports for the named system error. */
+function systemErrno(name) {
+    for (const [errno, [errorName]] of node_util_1.default.getSystemErrorMap()) {
+        if (errorName === name)
+            return errno;
+    }
+    return undefined;
+}
+function spawnWorkingDirectory(cwd) {
+    if (cwd === undefined)
+        return process.cwd();
+    return node_path_1.default.resolve(typeof cwd === "string" ? cwd : (0, node_url_1.fileURLToPath)(cwd));
+}
+/** Pass volatile cmd wrapper arguments through one-pass environment expansion. */
+function createWindowsGoCommandShim(args) {
+    const prefix = `TTSC_GO_COMMAND_SHIM_${node_crypto_1.default
+        .randomBytes(8)
+        .toString("hex")
+        .toUpperCase()}_ARG_`;
+    const environment = Object.fromEntries(args.map((arg, index) => [prefix + index, quoteWindowsCommandArg(arg)]));
+    return {
+        environment,
+        // cmd expands each placeholder exactly once. Percent-shaped text inside an
+        // expanded value is not scanned as a second environment reference.
+        payload: `"${args.map((_, index) => `%${prefix}${index}%`).join(" ")}"`,
+    };
+}
+/** Quote one argv value for the Windows command-line parser used by cmd. */
+function quoteWindowsCommandArg(arg) {
+    return `"${String(arg)
+        .replace(/(\\*)"/g, '$1$1\\"')
+        .replace(/(\\*)$/, "$1$1")}"`;
+}
+//# sourceMappingURL=spawnGoTool.js.map

package/lib/plugin/internal/source/spawnGoTool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spawnGoTool.js","sourceRoot":"","sources":["../../../../src/plugin/internal/source/spawnGoTool.ts"],"names":[],"mappings":"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"}

package/lib/plugin/internal/source/touchPluginCacheEntryInUse.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Mark the plugin cache entry holding `binary` as used now, when the binary
+ * lives in one.
+ *
+ * The cache's collector considers recent use when selecting its protected byte
+ * cohort; freshness is not an unconditional pin. A build or cache hit records a
+ * use. A long-lived consumer, such as a `ttsc --watch` session reusing its
+ * resident check plugins, runs the binary again and again without either, so
+ * its entry aged out and could be removed while the session still needed it to
+ * respawn a sidecar. The consumer records each cycle's use here instead. This
+ * improves its recency priority but does not give it ownership of a permanently
+ * retained binary. A binary outside the cache, whose directory carries no
+ * last-use record, is left alone.
+ *
+ * @param binary The plugin executable being used.
+ * @evidence contracts/common.md#principled-implementation An observed regular last-use marker selects the cache convention for refresh, rather than authenticating the binary or its producer. Atomic entry replacement avoids modifying an aliased marker inode; sequential checks do not pin the containing pathname.
+ * @evidence contracts/common.md#clear-and-simple-design The binary's containing entry is projected directly, with a marker-presence gate before publication.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The marker is authored cache provenance, not a filename exception for a particular plugin or consumer.
+ * @evidence contracts/common.md#meaningful-documentation Native prose explains resident-use refresh, the absent-marker boundary and tolerated refresh failures.
+ * @evidence contracts/portability.md#os-neutral-implementation Native dirname/join and metadata replacement handle platform paths; locked or missing files remain a tolerated refresh failure.
+ * @evidence contracts/performance.md#efficient-algorithms Containing-path construction, marker stat and atomic timestamp replacement use a fixed operation count without reading binary bytes; costs still include native path resolution and timestamp/pending-name text.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This helper does not validate the resident binary's build inputs or coordinate its production.
+ *
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Refresh changes recency priority, not reader ownership or a storage bound. The collector owns eviction attempts and retained history; refresh failures are swallowed and atomic writer cleanup is best-effort. This operation retains no worker or handle.
+ */
+export declare function touchPluginCacheEntryInUse(binary: string): void;

package/lib/plugin/internal/source/touchPluginCacheEntryInUse.js

@@ -0,0 +1,48 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.touchPluginCacheEntryInUse = touchPluginCacheEntryInUse;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const SourceBuildCacheLayout_1 = require("./SourceBuildCacheLayout");
+/**
+ * Mark the plugin cache entry holding `binary` as used now, when the binary
+ * lives in one.
+ *
+ * The cache's collector considers recent use when selecting its protected byte
+ * cohort; freshness is not an unconditional pin. A build or cache hit records a
+ * use. A long-lived consumer, such as a `ttsc --watch` session reusing its
+ * resident check plugins, runs the binary again and again without either, so
+ * its entry aged out and could be removed while the session still needed it to
+ * respawn a sidecar. The consumer records each cycle's use here instead. This
+ * improves its recency priority but does not give it ownership of a permanently
+ * retained binary. A binary outside the cache, whose directory carries no
+ * last-use record, is left alone.
+ *
+ * @param binary The plugin executable being used.
+ * @evidence contracts/common.md#principled-implementation An observed regular last-use marker selects the cache convention for refresh, rather than authenticating the binary or its producer. Atomic entry replacement avoids modifying an aliased marker inode; sequential checks do not pin the containing pathname.
+ * @evidence contracts/common.md#clear-and-simple-design The binary's containing entry is projected directly, with a marker-presence gate before publication.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The marker is authored cache provenance, not a filename exception for a particular plugin or consumer.
+ * @evidence contracts/common.md#meaningful-documentation Native prose explains resident-use refresh, the absent-marker boundary and tolerated refresh failures.
+ * @evidence contracts/portability.md#os-neutral-implementation Native dirname/join and metadata replacement handle platform paths; locked or missing files remain a tolerated refresh failure.
+ * @evidence contracts/performance.md#efficient-algorithms Containing-path construction, marker stat and atomic timestamp replacement use a fixed operation count without reading binary bytes; costs still include native path resolution and timestamp/pending-name text.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This helper does not validate the resident binary's build inputs or coordinate its production.
+ *
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Refresh changes recency priority, not reader ownership or a storage bound. The collector owns eviction attempts and retained history; refresh failures are swallowed and atomic writer cleanup is best-effort. This operation retains no worker or handle.
+ */
+function touchPluginCacheEntryInUse(binary) {
+    const record = node_path_1.default.join(node_path_1.default.dirname(binary), SourceBuildCacheLayout_1.SourceBuildCacheLayout.CACHE_LAST_USED_FILE);
+    try {
+        if (!node_fs_1.default.statSync(record).isFile())
+            return;
+        SourceBuildCacheLayout_1.SourceBuildCacheLayout.replaceCacheMetadataFile(record, `${Date.now()}\n`);
+    }
+    catch {
+        // Not a cache entry, or the record cannot be written: the use goes
+        // unrecorded, and a removed binary is rebuilt at the next resolution.
+    }
+}
+//# sourceMappingURL=touchPluginCacheEntryInUse.js.map

package/lib/plugin/internal/source/touchPluginCacheEntryInUse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"touchPluginCacheEntryInUse.js","sourceRoot":"","sources":["../../../../src/plugin/internal/source/touchPluginCacheEntryInUse.ts"],"names":[],"mappings":";;;;;;AAAA,sDAAyB;AACzB,0DAA6B;AAE7B,qEAAkE;AAElE;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,oCAA2C,MAAc;IACvD,MAAM,MAAM,GAAG,mBAAI,CAAC,IAAI,CACtB,mBAAI,CAAC,OAAO,CAAC,MAAM,CAAC,EACpB,+CAAsB,CAAC,oBAAoB,CAC5C,CAAC;IACF,IAAI,CAAC;QACH,IAAI,CAAC,iBAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE;YAAE,OAAO;QAC1C,+CAAsB,CAAC,wBAAwB,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IAC7E,CAAC;IAAC,MAAM,CAAC;QACP,mEAAmE;QACnE,sEAAsE;IACxE,CAAC;AACH,CAAC"}