@ttsc/graph 0.30.3 → 0.31.0

package/lib/nativeExecutable.js

@@ -15,6 +15,15 @@ const node_path_1 = __importDefault(require("node:path"));
  * package binaries without executable bits. The ttsc launcher already repairs
  * its native helper before spawning; @ttsc/graph has its own ttscgraph spawn
  * paths, so it must apply the same first-run repair here.
+ *
+ * @evidence contracts/common.md#principled-implementation POSIX executable access is checked before preserving existing permission bits and adding the required execution permissions.
+ * @evidence contracts/common.md#clear-and-simple-design This helper owns the native permission boundary for all graph spawn lanes.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Permission repair addresses supported package installation differences; failures still reach the original spawn path.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain the package-manager condition and why graph must apply its own spawn-boundary repair.
+ * @evidence contracts/performance.md#efficient-algorithms Permission repair uses constant-count access/stat/chmod operations without reading binary contents or scanning directories.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Permission is an effectful spawn precondition, not a completed producer result shared across requests.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources This precondition retains no handle, task or historical entry after synchronous filesystem calls.
+ * @evidence contracts/portability.md#os-neutral-implementation Windows has no POSIX executable-bit requirement; other hosts use filesystem access and mode APIs rather than path spelling assumptions.
  */
 function ensureExecutable(binary) {
     if (process.platform === "win32")
@@ -45,12 +54,28 @@ function ensureExecutable(binary) {
  * the same answer everywhere. Reading the result back still materializes a
  * string, so V8's own maximum string length remains the outer bound — a
  * property of the runtime rather than a budget chosen here.
+ *
+ * @evidence contracts/common.md#principled-implementation Passing file descriptors avoids spawnSync's pipe-buffer limit while later UTF-8 reads preserve each output channel.
+ * @evidence contracts/common.md#clear-and-simple-design One factory transfers descriptor and directory ownership through a read/dispose handle; private helpers isolate cleanup.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The capture uses supported spawn descriptors rather than patching child_process or imposing repository-sized output limits.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain file capture, heap materialization and the runtime string-length boundary; the handle documents caller disposal.
+ * @evidence contracts/portability.md#os-neutral-implementation Native fs descriptors and path.join operate on every host; storage is created beneath the resolved physical system-temp directory.
+ * @evidence contracts/performance.md#efficient-algorithms Capturing writes directly to files; reading costs linear output bytes and materializes one stream string, with no pipe-buffer copy in this heap.
+ * @evidence contracts/performance.md#reuse-equivalent-work Stdout and stderr are distinct effectful streams from one child invocation; reruns require new storage and cannot reuse a prior result.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources The returned owner disposes two descriptors and one directory; acquisition failure unwinds acquired storage and removal is best effort when foreign handles remain open.
  */
 function captureProcessOutput() {
     const directory = createCanonicalTempDirectory("ttscgraph-spawn-");
     const stdoutPath = node_path_1.default.join(directory, "stdout");
     const stderrPath = node_path_1.default.join(directory, "stderr");
-    const stdoutFd = node_fs_1.default.openSync(stdoutPath, "w+");
+    let stdoutFd;
+    try {
+        stdoutFd = node_fs_1.default.openSync(stdoutPath, "w+");
+    }
+    catch (error) {
+        removeQuietly(directory);
+        throw error;
+    }
     let stderrFd;
     try {
         stderrFd = node_fs_1.default.openSync(stderrPath, "w+");
@@ -62,21 +87,19 @@ function captureProcessOutput() {
         removeQuietly(directory);
         throw error;
     }
+    let disposed = false;
     return {
         dispose() {
+            if (disposed)
+                return;
+            disposed = true;
             closeQuietly(stdoutFd);
             closeQuietly(stderrFd);
             removeQuietly(directory);
         },
         read(stream) {
             const location = stream === "stdout" ? stdoutPath : stderrPath;
-            try {
-                return node_fs_1.default.readFileSync(location, "utf8");
-            }
-            catch {
-                // A spawn that never launched leaves nothing behind.
-                return "";
-            }
+            return node_fs_1.default.readFileSync(location, "utf8");
         },
         stderrFd,
         stdoutFd,
@@ -85,18 +108,55 @@ function captureProcessOutput() {
 /** Create capture storage beneath the frozen physical system-temp parent. */
 function createCanonicalTempDirectory(prefix) {
     const physicalParent = node_fs_1.default.realpathSync.native(node_os_1.default.tmpdir());
-    if (!node_fs_1.default.lstatSync(physicalParent).isDirectory()) {
+    const parentIdentity = node_fs_1.default.lstatSync(physicalParent);
+    if (!parentIdentity.isDirectory()) {
         throw new Error(`@ttsc/graph: temporary directory parent is not a directory: ${physicalParent}`);
     }
     const directory = node_fs_1.default.mkdtempSync(node_path_1.default.join(physicalParent, prefix));
-    if (!node_fs_1.default.lstatSync(directory).isDirectory()) {
-        throw new Error(`@ttsc/graph: temporary directory postflight is not a directory: ${directory}`);
+    let childIdentity;
+    try {
+        childIdentity = node_fs_1.default.lstatSync(directory);
+        if (!childIdentity.isDirectory() || childIdentity.isSymbolicLink()) {
+            throw new Error(`@ttsc/graph: temporary directory postflight is not a directory: ${directory}`);
+        }
+        const physicalDirectory = node_fs_1.default.realpathSync.native(directory);
+        if (node_path_1.default.dirname(physicalDirectory) !== physicalParent) {
+            throw new Error(`@ttsc/graph: temporary directory escaped its physical parent: ${physicalDirectory}`);
+        }
+        return physicalDirectory;
+    }
+    catch (error) {
+        removeUnchangedTempDirectory(directory, physicalParent, prefix, parentIdentity, childIdentity);
+        throw error;
+    }
+}
+/** Roll back only an unchanged direct child whose native ownership was seen. */
+function removeUnchangedTempDirectory(directory, parent, prefix, parentIdentity, childIdentity) {
+    if (childIdentity === undefined ||
+        !childIdentity.isDirectory() ||
+        childIdentity.isSymbolicLink() ||
+        node_path_1.default.dirname(directory) !== parent ||
+        !node_path_1.default.basename(directory).startsWith(prefix))
+        return;
+    try {
+        const currentParent = node_fs_1.default.lstatSync(parent);
+        const currentChild = node_fs_1.default.lstatSync(directory);
+        if (node_fs_1.default.realpathSync.native(parent) !== parent ||
+            !currentParent.isDirectory() ||
+            currentParent.isSymbolicLink() ||
+            currentParent.dev !== parentIdentity.dev ||
+            currentParent.ino !== parentIdentity.ino ||
+            !currentChild.isDirectory() ||
+            currentChild.isSymbolicLink() ||
+            currentChild.dev !== childIdentity.dev ||
+            currentChild.ino !== childIdentity.ino)
+            return;
+        removeQuietly(directory);
     }
-    const physicalDirectory = node_fs_1.default.realpathSync.native(directory);
-    if (node_path_1.default.dirname(physicalDirectory) !== physicalParent) {
-        throw new Error(`@ttsc/graph: temporary directory escaped its physical parent: ${physicalDirectory}`);
+    catch {
+        // Failed ownership checks leave storage untouched rather than delete a
+        // replacement or an unrelated canonical target.
     }
-    return physicalDirectory;
 }
 /** Close a descriptor, ignoring one that is already closed. */
 function closeQuietly(fd) {

package/lib/nativeExecutable.js.map

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

package/lib/reduce.d.ts

@@ -1,48 +1,22 @@
-export interface RawNode {
-    id: string;
-    name: string;
-    kind: string;
-    file: string;
-    external?: boolean;
-    ignored?: boolean;
-}
-export interface RawEdge {
-    from: string;
-    to: string;
-    kind: string;
-}
-export interface RawDump {
-    project?: string;
-    nodes: RawNode[];
-    edges: RawEdge[];
-}
-export interface ViewerNode {
-    id: string;
-    name: string;
-    kind: string;
-    file: string;
-    degree: number;
-}
-export interface ViewerLink {
-    source: string;
-    target: string;
-    kind: string;
-}
-export interface ViewerPayload {
-    project: string;
-    counts: {
-        rawNodes: number;
-        rawEdges: number;
-        nodes: number;
-        links: number;
-        droppedExternal: number;
-        droppedIgnored: number;
-        droppedByCap: number;
-    };
-    nodes: ViewerNode[];
-    links: ViewerLink[];
-}
-export declare function reduce(raw: RawDump, { maxNodes, keepExternal, keepIgnored }?: {
+import type { RawDump } from "./structures/RawDump";
+import type { ViewerPayload } from "./structures/ViewerPayload";
+/**
+ * Project a dump into a connected viewer graph, retaining high-degree nodes.
+ *
+ * Current portable coordinates retain their spelling. Legacy absolute paths are
+ * rerooted together, and node ids and edge endpoints use the same rewrite.
+ * Boundary and cap counters explain selection; isolated nodes are not drawn.
+ *
+ * @evidence contracts/common.md#principled-implementation Boundary selection precedes induced-edge filtering and degree ranking; final edge membership and matching identity rewrites preserve the displayed subgraph.
+ * @evidence contracts/common.md#clear-and-simple-design Pure projection separates path/identity codec, degree calculation and display-family mapping through private helpers.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Paths outside the common root keep identity rather than collapse to basename; filters use producer flags and general kinds without fixture lists.
+ * @evidence contracts/common.md#meaningful-documentation Native prose explains legacy/current coordinates and selection losses; DTO members document identity, degree and each counter.
+ * @evidence contracts/performance.md#efficient-algorithms Node/edge scans and degree maps cost O(N+E); degree selection sorts at most N nodes, adding O(N log N), with temporary maps/arrays proportional to the input.
+ * @evidence contracts/performance.md#reuse-equivalent-work Within one projection, indexed live/kept id sets and degree maps serve multiple filters; callers share the resulting payload across render requests rather than repeat reduction.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Temporary arrays and indexes become unreachable after return; the caller owns only selected DTO arrays and counts, with selected populations bounded by maxNodes and induced edges.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation rewrites path strings as text (separators and common root); it never opens, stats or resolves them.
+ */
+export declare function reduce(raw: RawDump, { maxNodes, keepExternal, keepIgnored, }?: {
     maxNodes?: number;
     keepExternal?: boolean;
     keepIgnored?: boolean;

package/lib/reduce.js

@@ -1,4 +1,6 @@
 "use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.reduce = reduce;
 // Reduce a raw `ttscgraph dump` to the payload the bundled 3D viewer renders.
 // The same pure transform is copied in
 // website/src/components/graph/TtscWebsiteGraphReduce.ts and
@@ -8,8 +10,6 @@
 // by tests/test-graph rather than by this comment. The CLI reduces in Node
 // before serving, so the browser viewer only ever renders a ready
 // `{ nodes, links }`.
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.reduce = reduce;
 function posix(p) {
     return p.replace(/\\/g, "/");
 }
@@ -162,8 +162,24 @@ const DISPLAY_KIND = {
     exports: "exports",
 };
 function displayKind(kind) {
-    return DISPLAY_KIND[kind] ?? kind;
+    return Object.hasOwn(DISPLAY_KIND, kind) ? DISPLAY_KIND[kind] : kind;
 }
+/**
+ * Project a dump into a connected viewer graph, retaining high-degree nodes.
+ *
+ * Current portable coordinates retain their spelling. Legacy absolute paths are
+ * rerooted together, and node ids and edge endpoints use the same rewrite.
+ * Boundary and cap counters explain selection; isolated nodes are not drawn.
+ *
+ * @evidence contracts/common.md#principled-implementation Boundary selection precedes induced-edge filtering and degree ranking; final edge membership and matching identity rewrites preserve the displayed subgraph.
+ * @evidence contracts/common.md#clear-and-simple-design Pure projection separates path/identity codec, degree calculation and display-family mapping through private helpers.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Paths outside the common root keep identity rather than collapse to basename; filters use producer flags and general kinds without fixture lists.
+ * @evidence contracts/common.md#meaningful-documentation Native prose explains legacy/current coordinates and selection losses; DTO members document identity, degree and each counter.
+ * @evidence contracts/performance.md#efficient-algorithms Node/edge scans and degree maps cost O(N+E); degree selection sorts at most N nodes, adding O(N log N), with temporary maps/arrays proportional to the input.
+ * @evidence contracts/performance.md#reuse-equivalent-work Within one projection, indexed live/kept id sets and degree maps serve multiple filters; callers share the resulting payload across render requests rather than repeat reduction.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Temporary arrays and indexes become unreachable after return; the caller owns only selected DTO arrays and counts, with selected populations bounded by maxNodes and induced edges.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation rewrites path strings as text (separators and common root); it never opens, stats or resolves them.
+ */
 function reduce(raw, { maxNodes = 1200, keepExternal = false, keepIgnored = false, } = {}) {
     // Drop external boundary leaves and git-ignored generated code (a Prisma
     // client and the like, tagged `ignored` by the dump) so the authored graph is

package/lib/reduce.js.map

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

package/lib/resolveGraphBinary.d.ts

@@ -22,5 +22,14 @@
  *    or an API `cwd` option), defaulting to `process.cwd()` when no project was
  *    named. A launcher started from an unrelated directory still resolves the
  *    `ttsc` installed under the target project it was asked to graph.
+ *
+ * @evidence contracts/common.md#principled-implementation Project-anchored module resolution locates the peer ttsc and then its platform binary; an explicit absolute override has precedence.
+ * @evidence contracts/common.md#clear-and-simple-design One resolver owns override and peer-package lookup for all graph launchers.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Resolution uses installed package contracts rather than guessing binary paths from repository layouts.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs and the ordered list explain peer placement, override precedence and target-project anchoring.
+ * @evidence contracts/portability.md#os-neutral-implementation Native path checks and module resolution select the platform/architecture package; only Windows's required executable suffix differs explicitly.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources returns a path string and opens no handle.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms performs a constant number of module resolutions (ttsc, then its platform package).
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work resolves on every call and caches nothing, so a reinstall between calls is honored.
  */
 export declare function resolveGraphBinary(env?: NodeJS.ProcessEnv, cwd?: string): string | null;

package/lib/resolveGraphBinary.js

@@ -30,6 +30,15 @@ const node_path_1 = __importDefault(require("node:path"));
  *    or an API `cwd` option), defaulting to `process.cwd()` when no project was
  *    named. A launcher started from an unrelated directory still resolves the
  *    `ttsc` installed under the target project it was asked to graph.
+ *
+ * @evidence contracts/common.md#principled-implementation Project-anchored module resolution locates the peer ttsc and then its platform binary; an explicit absolute override has precedence.
+ * @evidence contracts/common.md#clear-and-simple-design One resolver owns override and peer-package lookup for all graph launchers.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Resolution uses installed package contracts rather than guessing binary paths from repository layouts.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs and the ordered list explain peer placement, override precedence and target-project anchoring.
+ * @evidence contracts/portability.md#os-neutral-implementation Native path checks and module resolution select the platform/architecture package; only Windows's required executable suffix differs explicitly.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources returns a path string and opens no handle.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms performs a constant number of module resolutions (ttsc, then its platform package).
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work resolves on every call and caches nothing, so a reinstall between calls is honored.
  */
 function resolveGraphBinary(env = process.env, cwd = process.cwd()) {
     if (env.TTSC_GRAPH_BINARY && node_path_1.default.isAbsolute(env.TTSC_GRAPH_BINARY)) {
@@ -39,9 +48,8 @@ function resolveGraphBinary(env = process.env, cwd = process.cwd()) {
     try {
         // Anchor package lookup at the absolute project root so a relative `--cwd`
         // resolves the same way the native process interprets it.
-        const ttscPackageJson = require.resolve("ttsc/package.json", {
-            paths: [node_path_1.default.resolve(cwd)],
-        });
+        const fromProject = (0, node_module_1.createRequire)(node_path_1.default.join(node_path_1.default.resolve(cwd), "package.json"));
+        const ttscPackageJson = fromProject.resolve("ttsc/package.json");
         const fromTtsc = (0, node_module_1.createRequire)(ttscPackageJson);
         return fromTtsc.resolve(`@ttsc/${process.platform}-${process.arch}/bin/${exe}`);
     }

package/lib/resolveGraphBinary.js.map

@@ -1 +1 @@
-{"version":3,"file":"resolveGraphBinary.js","sourceRoot":"","sources":["../src/resolveGraphBinary.ts"],"names":[],"mappings":";;;;;;AAAA,6CAA4C;AAC5C,0DAA6B;AAE7B;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,4BACE,GAAG,GAAsB,OAAO,CAAC,GAAG,EACpC,GAAG,GAAW,OAAO,CAAC,GAAG,EAAE;IAE3B,IAAI,GAAG,CAAC,iBAAiB,IAAI,mBAAI,CAAC,UAAU,CAAC,GAAG,CAAC,iBAAiB,CAAC,EAAE,CAAC;QACpE,OAAO,GAAG,CAAC,iBAAiB,CAAC;IAC/B,CAAC;IACD,MAAM,GAAG,GAAG,OAAO,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,WAAW,CAAC;IACzE,IAAI,CAAC;QACH,2EAA2E;QAC3E,0DAA0D;QAC1D,MAAM,eAAe,GAAG,OAAO,CAAC,OAAO,CAAC,mBAAmB,EAAE;YAC3D,KAAK,EAAE,CAAC,mBAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;SAC3B,CAAC,CAAC;QACH,MAAM,QAAQ,GAAG,IAAA,2BAAa,EAAC,eAAe,CAAC,CAAC;QAChD,OAAO,QAAQ,CAAC,OAAO,CACrB,SAAS,OAAO,CAAC,QAAQ,IAAI,OAAO,CAAC,IAAI,QAAQ,GAAG,EAAE,CACvD,CAAC;IACJ,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC"}
+{"version":3,"file":"resolveGraphBinary.js","sourceRoot":"","sources":["../src/resolveGraphBinary.ts"],"names":[],"mappings":";;;;;;AAAA,6CAA4C;AAC5C,0DAA6B;AAE7B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,4BACE,GAAG,GAAsB,OAAO,CAAC,GAAG,EACpC,GAAG,GAAW,OAAO,CAAC,GAAG,EAAE;IAE3B,IAAI,GAAG,CAAC,iBAAiB,IAAI,mBAAI,CAAC,UAAU,CAAC,GAAG,CAAC,iBAAiB,CAAC,EAAE,CAAC;QACpE,OAAO,GAAG,CAAC,iBAAiB,CAAC;IAC/B,CAAC;IACD,MAAM,GAAG,GAAG,OAAO,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,WAAW,CAAC;IACzE,IAAI,CAAC;QACH,2EAA2E;QAC3E,0DAA0D;QAC1D,MAAM,WAAW,GAAG,IAAA,2BAAa,EAC/B,mBAAI,CAAC,IAAI,CAAC,mBAAI,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,cAAc,CAAC,CAC7C,CAAC;QACF,MAAM,eAAe,GAAG,WAAW,CAAC,OAAO,CAAC,mBAAmB,CAAC,CAAC;QACjE,MAAM,QAAQ,GAAG,IAAA,2BAAa,EAAC,eAAe,CAAC,CAAC;QAChD,OAAO,QAAQ,CAAC,OAAO,CACrB,SAAS,OAAO,CAAC,QAAQ,IAAI,OAAO,CAAC,IAAI,QAAQ,GAAG,EAAE,CACvD,CAAC;IACJ,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC"}

package/lib/runGraph.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Run the `@ttsc/graph` launcher.
+ *
+ * - `view`: JS-orchestrated 3D viewer (dump -> reduce -> serve -> open).
+ * - `dump`: pass through to the native `ttscgraph dump`, which prints the whole
+ *   graph as JSON for piping or the viewer.
+ * - Default: serve the MCP graph over stdio. The TypeScript server keeps a native
+ *   incremental compiler session resident, checks the disk snapshot before each
+ *   graph operation, and reuses the in-memory graph when unchanged; the agent's
+ *   MCP client speaks JSON-RPC over this process's stdin/stdout.
+ *
+ * @evidence contracts/common.md#principled-implementation The first command token selects view, native dump or stdio MCP; shared project parsing supplies the producer coordinates consistently.
+ * @evidence contracts/common.md#clear-and-simple-design The launcher owns lane dispatch while viewer, server and native dump helpers own their respective execution boundaries.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts A missing dump binary exposes only an explicitly qualified help summary; execution failures retain nonzero outcomes instead of fake graph answers.
+ * @evidence contracts/common.md#meaningful-documentation Native lane bullets explain observable CLI behavior and resident refresh ownership with a blank line before tags.
+ * @evidence contracts/portability.md#os-neutral-implementation Native lanes resolve the selected project's platform package and pass argv directly; stdio MCP uses Node transport APIs without shell path construction.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources starts the stdio server (owned by startServer), runs a synchronous dump child to completion or hands over to runView, and keeps no handle itself.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms dispatches on the first argv token to one lane and the lanes own the work.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work runs one launcher lane per process invocation, so there is nothing to share.
+ */
+export declare function runGraph(argv?: readonly string[]): number | void;

package/lib/runGraph.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runGraph = runGraph;
+const TtscGraphLauncherArguments_1 = require("./TtscGraphLauncherArguments");
+const GraphProcessTrace_1 = require("./internal/GraphProcessTrace");
+const publishedArtifacts_1 = require("./model/publishedArtifacts");
+const nativeExecutable_1 = require("./nativeExecutable");
+const resolveGraphBinary_1 = require("./resolveGraphBinary");
+const startServer_1 = require("./server/startServer");
+const view_1 = require("./view");
+// The server version reported in the MCP handshake; read from this package.
+const VERSION = require("../package.json")
+    .version;
+/**
+ * Run the `@ttsc/graph` launcher.
+ *
+ * - `view`: JS-orchestrated 3D viewer (dump -> reduce -> serve -> open).
+ * - `dump`: pass through to the native `ttscgraph dump`, which prints the whole
+ *   graph as JSON for piping or the viewer.
+ * - Default: serve the MCP graph over stdio. The TypeScript server keeps a native
+ *   incremental compiler session resident, checks the disk snapshot before each
+ *   graph operation, and reuses the in-memory graph when unchanged; the agent's
+ *   MCP client speaks JSON-RPC over this process's stdin/stdout.
+ *
+ * @evidence contracts/common.md#principled-implementation The first command token selects view, native dump or stdio MCP; shared project parsing supplies the producer coordinates consistently.
+ * @evidence contracts/common.md#clear-and-simple-design The launcher owns lane dispatch while viewer, server and native dump helpers own their respective execution boundaries.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts A missing dump binary exposes only an explicitly qualified help summary; execution failures retain nonzero outcomes instead of fake graph answers.
+ * @evidence contracts/common.md#meaningful-documentation Native lane bullets explain observable CLI behavior and resident refresh ownership with a blank line before tags.
+ * @evidence contracts/portability.md#os-neutral-implementation Native lanes resolve the selected project's platform package and pass argv directly; stdio MCP uses Node transport APIs without shell path construction.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources starts the stdio server (owned by startServer), runs a synchronous dump child to completion or hands over to runView, and keeps no handle itself.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms dispatches on the first argv token to one lane and the lanes own the work.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work runs one launcher lane per process invocation, so there is nothing to share.
+ */
+function runGraph(argv = process.argv.slice(2)) {
+    if (argv[0] === "view")
+        return (0, view_1.runView)(argv.slice(1));
+    if (argv[0] === "dump")
+        return runDump(argv.slice(1));
+    const { cwd, tsconfig } = TtscGraphLauncherArguments_1.TtscGraphLauncherArguments.project(argv);
+    void (0, startServer_1.startServer)({ cwd, tsconfig, version: VERSION }).catch((error) => {
+        process.stderr.write(`@ttsc/graph: ${error instanceof Error ? error.message : String(error)}\n`);
+        process.exit(1);
+    });
+}
+/**
+ * Pass `dump` through to the native binary, inheriting stdio so the JSON lands
+ * on this process's stdout. Returns the child's exit code.
+ */
+function runDump(argv) {
+    // Resolve the native binary from the target project the caller named with
+    // `--cwd`, not from wherever the launcher process happened to start.
+    const { cwd, tsconfig, artifactsSpecified } = TtscGraphLauncherArguments_1.TtscGraphLauncherArguments.dump(argv);
+    const binary = (0, resolveGraphBinary_1.resolveGraphBinary)(process.env, cwd);
+    if (binary === null) {
+        // `ttscgraph` owns the flag contract, so a resolvable binary always answers
+        // `--help` itself and stays the single source of truth. It cannot answer
+        // when it is absent, and that is exactly when a caller is most likely to be
+        // asking what the command needs — so fall back to a summary that names the
+        // authority rather than making usage unreachable behind an install error.
+        const fallback = TtscGraphLauncherArguments_1.TtscGraphLauncherArguments.missingDump(argv);
+        if (fallback.stdout !== undefined)
+            process.stdout.write(fallback.stdout);
+        if (fallback.stderr !== undefined)
+            process.stderr.write(fallback.stderr);
+        return fallback.code;
+    }
+    (0, nativeExecutable_1.ensureExecutable)(binary);
+    // The same artifacts `loadGraph` and the resident session ask for, so the
+    // three ways to reach a dump answer a citation the same way. A caller that
+    // named `--artifacts` itself owns the answer and is not overridden.
+    const published = artifactsSpecified
+        ? null
+        : (0, publishedArtifacts_1.publishArtifacts)({ cwd, tsconfig });
+    const result = GraphProcessTrace_1.GraphProcessTrace.spawnSync(binary, TtscGraphLauncherArguments_1.TtscGraphLauncherArguments.dumpVector(argv, published?.file ?? null), {
+        stdio: "inherit",
+        windowsHide: true,
+    });
+    const completion = TtscGraphLauncherArguments_1.TtscGraphLauncherArguments.dumpCompletion(result);
+    if (completion.diagnostic !== undefined)
+        process.stderr.write(completion.diagnostic);
+    return completion.code;
+}
+//# sourceMappingURL=runGraph.js.map

package/lib/runGraph.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runGraph.js","sourceRoot":"","sources":["../src/runGraph.ts"],"names":[],"mappings":";;;AAAA,6EAA0E;AAC1E,oEAAiE;AACjE,mEAA8D;AAC9D,yDAAsD;AACtD,6DAA0D;AAC1D,sDAAmD;AACnD,iCAAiC;AAEjC,4EAA4E;AAC5E,MAAM,OAAO,GAAY,OAAO,CAAC,iBAAiB,CAAyB;KACxE,OAAO,CAAC;AAEX;;;;;;;;;;;;;;;;;;;GAmBG;AACH,kBACE,IAAI,GAAsB,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;IAE/C,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,MAAM;QAAE,OAAO,IAAA,cAAO,EAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IACtD,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,MAAM;QAAE,OAAO,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAEtD,MAAM,EAAE,GAAG,EAAE,QAAQ,EAAE,GAAG,uDAA0B,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACnE,KAAK,IAAA,yBAAW,EAAC,EAAE,GAAG,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC,KAAK,CACzD,CAAC,KAAc,EAAE,EAAE;QACjB,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,gBAAgB,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAC3E,CAAC;QACF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CACF,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,SAAS,OAAO,CAAC,IAAuB;IACtC,0EAA0E;IAC1E,qEAAqE;IACrE,MAAM,EAAE,GAAG,EAAE,QAAQ,EAAE,kBAAkB,EAAE,GACzC,uDAA0B,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACxC,MAAM,MAAM,GAAG,IAAA,uCAAkB,EAAC,OAAO,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IACpD,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;QACpB,4EAA4E;QAC5E,yEAAyE;QACzE,4EAA4E;QAC5E,2EAA2E;QAC3E,0EAA0E;QAC1E,MAAM,QAAQ,GAAG,uDAA0B,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;QAC9D,IAAI,QAAQ,CAAC,MAAM,KAAK,SAAS;YAAE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QACzE,IAAI,QAAQ,CAAC,MAAM,KAAK,SAAS;YAAE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QACzE,OAAO,QAAQ,CAAC,IAAI,CAAC;IACvB,CAAC;IACD,IAAA,mCAAgB,EAAC,MAAM,CAAC,CAAC;IACzB,0EAA0E;IAC1E,2EAA2E;IAC3E,oEAAoE;IACpE,MAAM,SAAS,GAAG,kBAAkB;QAClC,CAAC,CAAC,IAAI;QACN,CAAC,CAAC,IAAA,qCAAgB,EAAC,EAAE,GAAG,EAAE,QAAQ,EAAE,CAAC,CAAC;IACxC,MAAM,MAAM,GAAG,qCAAiB,CAAC,SAAS,CACxC,MAAM,EACN,uDAA0B,CAAC,UAAU,CAAC,IAAI,EAAE,SAAS,EAAE,IAAI,IAAI,IAAI,CAAC,EACpE;QACE,KAAK,EAAE,SAAS;QAChB,WAAW,EAAE,IAAI;KAClB,CACF,CAAC;IACF,MAAM,UAAU,GAAG,uDAA0B,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC;IACrE,IAAI,UAAU,CAAC,UAAU,KAAK,SAAS;QACrC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC;IAC9C,OAAO,UAAU,CAAC,IAAI,CAAC;AACzB,CAAC"}

package/lib/server/IResolvedGraphHandle.d.ts

@@ -0,0 +1,22 @@
+import { TtscGraphReadonly } from "../model/TtscGraphReadonly";
+import { ITtscGraphNode as NodeShape } from "../structures/ITtscGraphNode";
+type ITtscGraphNode = TtscGraphReadonly<NodeShape>;
+/**
+ * Exact resolved node, ambiguous candidates or an empty unknown outcome.
+ *
+ * @evidence contracts/common.md#principled-implementation Optional node and candidates preserve the resolver's unique, ambiguous and absent states without fabricating identity.
+ * @evidence contracts/common.md#clear-and-simple-design One compact outcome is shared by direct-id, name and file-qualified resolution paths.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Ranked candidates remain unresolved choices rather than a guessed definitive node.
+ * @evidence contracts/common.md#meaningful-documentation Native member comments distinguish uniquely resolved identity from ranked ambiguity.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources data shape only: it holds no handle, task or retained state.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms data shape only: it contains no loop or algorithm.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work data shape only: it computes nothing another request could share.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation data shape only: it touches no file, path or process.
+ */
+export interface IResolvedGraphHandle {
+    /** Present when the handle identifies exactly one node. */
+    node?: ITtscGraphNode;
+    /** Ranked remaining choices when more than one identity matches. */
+    candidates?: ITtscGraphNode[];
+}
+export {};

package/lib/server/IResolvedGraphHandle.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=IResolvedGraphHandle.js.map

package/lib/server/IResolvedGraphHandle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IResolvedGraphHandle.js","sourceRoot":"","sources":["../../src/server/IResolvedGraphHandle.ts"],"names":[],"mappings":""}

package/lib/server/createServer.d.ts

@@ -7,16 +7,20 @@ import { TtscGraphSource } from "../TtscGraphApplication";
  * input and output schemas and its argument validator, with no hand-written
  * schema: the interface's JSDoc becomes the handshake instructions, the
  * method's becomes the tool description, and every property's becomes the
- * description of that field — including `audit`, whose JSDoc is how a caller
- * learns what the server checked before it answered.
+ * description of that field — including `audit`, whose JSDoc explains fact
+ * provenance and coverage without claiming a second compiler check.
  *
- * The registration was hand-written here for a while, because a tool that
- * declares an output schema must answer with `structuredContent` and the helper
- * also serialized the same JSON into a text block: the payload crossed the wire
- * twice, a client counted both copies against its tool-result cap, and a 30 KB
- * tour arrived as 60 KB, blew the cap, and was spilled to a file the model then
- * shelled out to read back. `@typia/mcp` 13.1.0 ships the structured result
- * once (samchon/typia#2020), so the hand-written server had nothing left to fix
- * and the library owns the registration again.
+ * The library owns registration and sends structured results once by default.
+ * Its version option identifies this graph server in the handshake without
+ * changing SDK internals after construction.
+ *
+ * @evidence contracts/common.md#principled-implementation The typed controller supplies reflected schemas and executor dispatch; the supported version option sets the MCP implementation identity at construction.
+ * @evidence contracts/common.md#clear-and-simple-design The integration delegates registration and result serialization to the library instead of maintaining another transport implementation.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Handshake version uses the public createMcpServer option; no SDK private field or foreign method is patched.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain schema/JSDoc reflection, structured-result ownership and public version configuration.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources returns a server whose transport lifetime startServer owns.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms builds the MCP server once from the typia controller, with no loop of its own.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work called once per process; the schema reflection happens at compile time.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation creates an in-memory MCP server object; startServer attaches the stdio transport.
  */
 export declare function createServer(graph: TtscGraphSource, version: string): McpServer;