@termwright/probe-tview 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 gorce-ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,116 @@
+# @termwright/probe-tview
+
+Semantics from a [tview](https://github.com/rivo/tview) application that
+**imports nothing of ours**.
+
+The application is built through an ephemeral Go workspace that redirects
+`github.com/rivo/tview` to an instrumented copy. Nothing is written into the
+project: its `go.mod`, its `go.sum` and any `go.work` of its own come out of the
+build byte-identical.
+
+## Install
+
+```sh
+npm install --save-dev @termwright/probe-tview
+```
+
+Requires the Go toolchain and `git` (which the toolchain needs anyway). Node >= 22.
+
+## Usage
+
+One call prepares the build; the launcher owns everything else.
+
+```ts
+import {prepareInstrumentedBuild} from '@termwright/probe-tview';
+
+const build = await prepareInstrumentedBuild({moduleDir: 'path/to/app'});
+
+// build.env carries GOWORK; the project's own files are untouched.
+await execFile('go', ['build', '-o', 'app-binary', '.'], {cwd: 'path/to/app', env: build.env});
+
+await launchTerminal({command: ['./app-binary']});
+```
+
+The framework version is read from the module, the instrumented copy is cached,
+and a second call with the same inputs reuses it.
+
+## What it gives you
+
+Being inside the package is the point. A `tview.Grid` exposes no accessor for
+its children at all, so an out-of-package adapter has to be handed a callback;
+here it is a field read that also carries whether the item was drawn. A widget
+on a `Pages` page that is not shown reports as **hidden** rather than going
+missing, so a test can tell "not on screen" from "not there".
+
+Identity is the primitive's pointer: tview retains its widget tree, so the same
+`*Button` is the same button across frames. The handshake therefore reports
+`identityKind: 'stable'` and only the probe capabilities it earns:
+`stable-identity` and `annotations`. Its `frameworkVersion` is the exact
+version selected by the verified patch set, not the Go runtime version.
+
+## Describing what the probe cannot see
+
+Zero-config means the probe reads facts. It cannot read intent — which button
+is the destructive one, which list is the inbox, what "overdue" means here. For
+that, and only for that, an application may import
+`github.com/gorce-ai/termwright/clients/go/annotate`:
+
+```go
+import (
+	"github.com/gorce-ai/termwright/clients/go/annotate"
+	"github.com/gorce-ai/termwright/clients/go/protocol"
+)
+
+annotate.Tag(label, annotate.Semantics{Key: "unread-label"})
+annotate.Tag(unreadBadge, annotate.Semantics{
+	Role: "status", Name: "Unread messages", TestID: "unread-badge",
+	Actions: []protocol.Action{protocol.ActionFocus, protocol.ActionActivate},
+	LabelledBy: []annotate.SemanticKey{"unread-label"},
+})
+```
+
+The probe merges this with what it observed: the wording is the author's, the
+bounds and the focus stay the probe's. `Semantics` has no field for bounds,
+focus, visibility, value, rendered text or framework state — not by convention
+but structurally, so an annotation cannot go stale against the screen. Actions
+come from the protocol's closed descriptive set and never install callbacks.
+Tagging retains nothing; the entry is released with the widget.
+
+`LabelledBy` and `DescribedBy` use framework-neutral `SemanticKey` strings, so
+one annotation does not retain its targets. The probe resolves them after the
+whole tree has been walked. Missing or duplicate keys are omitted instead of
+becoming dangling or arbitrary node references. Pointer identity remains the
+stable node id; a key is only the relation target for tview. Primary framework
+provenance is reported in `p`, with recognizer and annotation exceptions in
+`px`.
+
+This is the one import that makes an application no longer zero-config, which
+is why it is optional and why the two example fixtures in this package are kept
+apart.
+
+## Dormant without instrumentation
+
+Without `TERMWRIGHT_ENDPOINT` and `TERMWRIGHT_TOKEN` the instrumented copy opens
+no socket, writes no marker and renders exactly what upstream renders. That is
+measured, not asserted: the test suite builds the same application twice, once
+against untouched tview and once against the copy, and requires the two screens
+to be byte-identical.
+
+## When it refuses
+
+- `-mod=vendor` in `GOFLAGS` is reported by name rather than overridden;
+  workspace mode is incompatible with it, and overriding would change what
+  compiles.
+- A framework version with no patch set is named as such — "this is not
+  tview v0.42.0" — instead of failing somewhere inside a diff.
+
+## Development
+
+```sh
+pnpm build && pnpm typecheck && pnpm test
+```
+
+The suites that need Go or a pseudo-terminal skip themselves where either is
+missing, and say so in a test named for it. `TERMWRIGHT_SKIP_GO=1` and
+`TERMWRIGHT_SKIP_PTY=1` force it. Implementation notes, including the traps
+that cost time, are in [`NOTES.md`](NOTES.md).

package/dist/index.d.ts

@@ -0,0 +1,88 @@
+export * from '@termwright/probe-go';
+import { ProbeFrame, SemanticSnapshot, SemanticRole } from '@termwright/protocol';
+
+/**
+ * IR → semantic tree, as a pure function.
+ *
+ * The Go probe normalises inside the copy, because that is where the private
+ * state is. This module is the same normalisation expressed over Probe IR, and
+ * it exists for two reasons that are worth stating, since duplicated logic is
+ * usually a smell:
+ *
+ * 1. **It is testable without a process.** The B tier of the campaign's test
+ *    plan feeds IR in and inspects the tree that comes out — no build, no
+ *    toolchain, no pseudo-terminal, and every edge case reachable in one line
+ *    instead of being coaxed out of a running application.
+ * 2. **It is the contract the Go side is held to.** The recorded IR of a real
+ *    frame goes through here, and the result must match what the probe
+ *    published. Two implementations that disagree describe the same
+ *    application differently, which is the failure mode the convergence round
+ *    existed to prevent.
+ */
+
+/** What a recognizer needs to know about the frame it is given. */
+interface RecognizeOptions {
+    readonly sessionId: string;
+    readonly revision: number;
+    readonly columns: number;
+    readonly rows: number;
+}
+/** Resolves one object's role from its framework type. */
+declare function roleFor(frameworkType: string): SemanticRole;
+/**
+ * Normalises one observed frame into a semantic snapshot.
+ *
+ * Facts are carried across, never invented. An object without geometry stays
+ * without bounds; a state the probe did not report stays absent, because
+ * "the probe did not say" and "the widget is not focused" are different
+ * claims and only one of them is safe to make.
+ */
+declare function recognize(frame: ProbeFrame, options: RecognizeOptions): SemanticSnapshot;
+
+/**
+ * The one call a launcher makes.
+ *
+ * Everything else in this package is a step: read the workspace, materialise a
+ * copy, patch it, key the cache, write the file. A user should not assemble
+ * those, and neither should a test — the assembly order is where the mistakes
+ * live, and there is exactly one correct one.
+ */
+/** Module path of the framework this probe instruments. */
+declare const FRAMEWORK = "github.com/rivo/tview";
+/** Module path of the protocol client the injected probe imports. */
+declare const CLIENT_MODULE = "github.com/gorce-ai/termwright/clients/go";
+/** Version of this probe; part of the cache key, so a new patch set invalidates copies. */
+declare const PROBE_VERSION = "0.1.0";
+interface PrepareOptions {
+    /** Directory of the Go module to build. */
+    readonly moduleDir: string;
+    /** Framework version to instrument, e.g. `v0.42.0`. */
+    readonly frameworkVersion?: string;
+    /** Where the protocol client lives on disk. Defaults to the copy shipped here. */
+    readonly clientDir?: string;
+    /** Where the generated workspace is written. Defaults to inside the copy's cache entry. */
+    readonly workspaceFile?: string;
+    /** Environment the build will run with; checked, never mutated. */
+    readonly env?: NodeJS.ProcessEnv;
+}
+interface PreparedBuild {
+    /** Hand this to the build as `GOWORK`. */
+    readonly workspaceFile: string;
+    /** The instrumented copy, for a canary check or for diagnosis. */
+    readonly copyDir: string;
+    /** Environment to build with: the caller's, plus GOWORK. */
+    readonly env: NodeJS.ProcessEnv;
+    /** True when the copy was built during this call rather than reused. */
+    readonly built: boolean;
+}
+/**
+ * Makes a build of `moduleDir` compile against the instrumented framework.
+ *
+ * Does not build anything and does not spawn the application: a launcher owns
+ * that. This returns what the build needs and nothing else, which keeps the
+ * package testable and keeps the decision about *how* to run the user's build
+ * where it belongs.
+ */
+declare function prepareInstrumentedBuild(options: PrepareOptions): Promise<PreparedBuild>;
+
+export { CLIENT_MODULE, FRAMEWORK, PROBE_VERSION, type PrepareOptions, type PreparedBuild, type RecognizeOptions, prepareInstrumentedBuild, recognize, roleFor };

package/dist/index.js

@@ -0,0 +1,219 @@
+// src/index.ts
+export * from "@termwright/probe-go";
+
+// src/recognizer.ts
+var ROLE_BY_TYPE = {
+  Button: "button",
+  Checkbox: "checkbox",
+  InputField: "textbox",
+  TextArea: "textbox",
+  DropDown: "list",
+  List: "list",
+  TreeView: "list",
+  Table: "table",
+  TextView: "text",
+  Modal: "dialog",
+  Form: "region",
+  Flex: "region",
+  Grid: "region",
+  Pages: "region",
+  Frame: "region",
+  Box: "region"
+};
+function roleFor(frameworkType) {
+  return ROLE_BY_TYPE[frameworkType] ?? "generic";
+}
+function recognize(frame, options) {
+  const nodes = [];
+  const rootIds = [];
+  for (const object of frame.objects) {
+    const node = recognizeObject(object);
+    nodes.push(node);
+    if (object.parent === void 0) rootIds.push(object.identity.value);
+  }
+  return {
+    v: 1,
+    sessionId: options.sessionId,
+    revision: options.revision,
+    columns: options.columns,
+    rows: options.rows,
+    rootIds,
+    nodes
+  };
+}
+function recognizeObject(object) {
+  const role = roleFor(object.frameworkType);
+  const state = recognizeState(object);
+  return {
+    id: object.identity.value,
+    role,
+    // The framework's own name survives on every node, not only generic ones:
+    // it is what lets a reader tell a Flex-shaped region from a Form-shaped
+    // one after both became `region`.
+    frameworkType: object.frameworkType,
+    name: object.annotations?.name ?? object.text ?? "",
+    ...object.parent === void 0 ? {} : { parentId: object.parent },
+    // intendedRect is where the widget was drawn. visibleRect is absent for
+    // tview, which computes no clip, so nothing here fabricates one.
+    ...object.geometry?.intendedRect === void 0 ? {} : { bounds: object.geometry.intendedRect },
+    ...object.state?.value === void 0 ? {} : { value: object.state.value },
+    ...state === void 0 ? {} : { state }
+  };
+}
+function recognizeState(object) {
+  const observed = object.state;
+  if (observed === void 0) return void 0;
+  const state = {};
+  if (observed.focused !== void 0) state["focused"] = observed.focused;
+  if (observed.disabled !== void 0) state["disabled"] = observed.disabled;
+  if (observed.checked !== void 0) state["checked"] = observed.checked;
+  if (observed.expanded !== void 0) state["expanded"] = observed.expanded;
+  if (observed.readonly !== void 0) state["readonly"] = observed.readonly;
+  if (observed.displayed === false) state["hidden"] = true;
+  if (observed.selectedIndex !== void 0) state["positionInSet"] = observed.selectedIndex + 1;
+  if (observed.scroll !== void 0 && observed.scroll.row >= 0) {
+    state["scrollOffset"] = observed.scroll.row;
+  }
+  if (observed.scrollExtent !== void 0 && observed.scrollExtent.rows >= 0) {
+    state["scrollExtent"] = observed.scrollExtent.rows;
+  }
+  return Object.keys(state).length === 0 ? void 0 : state;
+}
+
+// src/launch.ts
+import { execFile } from "child_process";
+import { existsSync } from "fs";
+import { join } from "path";
+import { fileURLToPath } from "url";
+import { promisify } from "util";
+import {
+  applyPatchSet,
+  assertNoVendorMode,
+  copyDir,
+  digestPatchSet,
+  ensureUpstreamModule,
+  isComplete,
+  markComplete,
+  materializeUpstream,
+  prepareCopyDir,
+  readManifest,
+  readWorkspace,
+  writeProvenance,
+  writeWorkspace
+} from "@termwright/probe-go";
+var run = promisify(execFile);
+var FRAMEWORK = "github.com/rivo/tview";
+var CLIENT_MODULE = "github.com/gorce-ai/termwright/clients/go";
+var PROBE_VERSION = "0.1.0";
+async function prepareInstrumentedBuild(options) {
+  const env = options.env ?? process.env;
+  assertNoVendorMode(env);
+  const frameworkVersion = options.frameworkVersion ?? await detectFrameworkVersion(options.moduleDir, env);
+  const patchSetDir = patchSetFor(frameworkVersion);
+  const manifest = await readManifest(patchSetDir);
+  const key = {
+    framework: FRAMEWORK,
+    frameworkVersion,
+    probeVersion: PROBE_VERSION,
+    toolchain: await toolchain(env),
+    patchDigest: await digestPatchSet(patchSetDir)
+  };
+  const copy = copyDir(key, env);
+  const built = !await isComplete(copy);
+  if (built) {
+    await prepareCopyDir(copy);
+    await materializeUpstream(await upstreamDir(frameworkVersion, env), copy);
+    await applyPatchSet(copy, patchSetDir);
+    await writeProvenance(copy, manifest);
+    await markComplete(copy, key);
+  }
+  const workspaceFile = await writeWorkspace(options.workspaceFile ?? join(copy, "..", "generated.work"), {
+    moduleDir: options.moduleDir,
+    inherited: await readWorkspace(options.moduleDir),
+    suppliedUses: await clientWorkspaceUses(options, env),
+    replaces: [
+      { from: FRAMEWORK, to: copy },
+      ...await clientVersionReplacements(options, env)
+    ]
+  });
+  return { workspaceFile, copyDir: copy, env: { ...env, GOWORK: workspaceFile }, built };
+}
+async function clientWorkspaceUses(options, env) {
+  if (await modulePath(options.moduleDir, env) === CLIENT_MODULE) return [];
+  return [{ dir: options.clientDir ?? await defaultClientDir(env), module: CLIENT_MODULE }];
+}
+async function clientVersionReplacements(options, env) {
+  if (await modulePath(options.moduleDir, env) === CLIENT_MODULE) return [];
+  const to = options.clientDir ?? await defaultClientDir(env);
+  const versions = /* @__PURE__ */ new Set(["v0.0.0"]);
+  try {
+    const { stdout } = await run("go", ["list", "-m", "-f", "{{.Version}}", CLIENT_MODULE], {
+      cwd: options.moduleDir,
+      env: { ...env, GOWORK: "off" }
+    });
+    if (stdout.trim() !== "") versions.add(stdout.trim());
+  } catch {
+  }
+  return [...versions].map((version) => ({ from: CLIENT_MODULE, to, version }));
+}
+async function detectFrameworkVersion(moduleDir, env) {
+  const { stdout } = await run("go", ["list", "-m", "-f", "{{.Version}}", FRAMEWORK], {
+    cwd: moduleDir,
+    // Without this a workspace already in effect could report a replaced
+    // version, and the patch set would be chosen for the wrong source.
+    env: { ...env, GOWORK: "off" }
+  });
+  return stdout.trim();
+}
+async function modulePath(moduleDir, env) {
+  const { stdout } = await run("go", ["list", "-m", "-f", "{{.Path}}"], {
+    cwd: moduleDir,
+    env: { ...env, GOWORK: "off" }
+  });
+  return stdout.trim();
+}
+async function upstreamDir(version, env) {
+  return ensureUpstreamModule({
+    module: FRAMEWORK,
+    version,
+    cachePath: ["github.com", "rivo", `tview@${version}`],
+    env
+  });
+}
+async function toolchain(env) {
+  const { stdout } = await run("go", ["version"], { env });
+  return stdout.trim();
+}
+function moduleCachePath(module, version) {
+  const parts = module.split("/");
+  const last = parts.pop();
+  return last === void 0 ? [] : [...parts, `${last}@${version}`];
+}
+function patchSetFor(version) {
+  return join(packageRoot(), "upstream-patches", "tview", version);
+}
+async function defaultClientDir(env) {
+  const vendored = join(packageRoot(), "go-client");
+  if (existsSync(join(vendored, "go.mod"))) return vendored;
+  const inRepo = join(packageRoot(), "..", "..", "clients", "go");
+  if (existsSync(join(inRepo, "go.mod"))) return inRepo;
+  const version = `v${PROBE_VERSION}`;
+  return ensureUpstreamModule({
+    module: CLIENT_MODULE,
+    version,
+    cachePath: moduleCachePath(CLIENT_MODULE, version),
+    env
+  });
+}
+function packageRoot() {
+  return join(fileURLToPath(new URL(".", import.meta.url)), "..");
+}
+export {
+  CLIENT_MODULE,
+  FRAMEWORK,
+  PROBE_VERSION,
+  prepareInstrumentedBuild,
+  recognize,
+  roleFor
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/recognizer.ts","../src/launch.ts"],"sourcesContent":["/**\n * `@termwright/probe-tview` — semantics from a tview application that imports\n * nothing of ours.\n *\n * The application is built through an ephemeral Go workspace that redirects\n * `github.com/rivo/tview` to an instrumented copy. The project's `go.mod`,\n * `go.sum` and any workspace of its own are never touched.\n *\n * @packageDocumentation\n */\n\n\n\n\n// The Go machinery is shared with every other copy-based probe.\nexport * from '@termwright/probe-go';\n\nexport { recognize, roleFor, type RecognizeOptions } from './recognizer.js';\n\nexport {\n  prepareInstrumentedBuild,\n  CLIENT_MODULE,\n  FRAMEWORK,\n  PROBE_VERSION,\n  type PrepareOptions,\n  type PreparedBuild,\n} from './launch.js';\n","/**\n * IR → semantic tree, as a pure function.\n *\n * The Go probe normalises inside the copy, because that is where the private\n * state is. This module is the same normalisation expressed over Probe IR, and\n * it exists for two reasons that are worth stating, since duplicated logic is\n * usually a smell:\n *\n * 1. **It is testable without a process.** The B tier of the campaign's test\n *    plan feeds IR in and inspects the tree that comes out — no build, no\n *    toolchain, no pseudo-terminal, and every edge case reachable in one line\n *    instead of being coaxed out of a running application.\n * 2. **It is the contract the Go side is held to.** The recorded IR of a real\n *    frame goes through here, and the result must match what the probe\n *    published. Two implementations that disagree describe the same\n *    application differently, which is the failure mode the convergence round\n *    existed to prevent.\n */\n\nimport type { ProbeFrame, ProbeObject } from '@termwright/protocol';\nimport type { SemanticNode, SemanticRole, SemanticSnapshot } from '@termwright/protocol';\n\n/**\n * tview widget type → role.\n *\n * Keyed on the framework's own type name, which the probe reports for every\n * object. Anything absent from this table is deliberately *not* a failure: it\n * becomes `generic` and keeps its `frameworkType`, so a widget added by a\n * future tview release is still addressable rather than dropped.\n */\nconst ROLE_BY_TYPE: Readonly<Record<string, SemanticRole>> = {\n  Button: 'button',\n  Checkbox: 'checkbox',\n  InputField: 'textbox',\n  TextArea: 'textbox',\n  DropDown: 'list',\n  List: 'list',\n  TreeView: 'list',\n  Table: 'table',\n  TextView: 'text',\n  Modal: 'dialog',\n  Form: 'region',\n  Flex: 'region',\n  Grid: 'region',\n  Pages: 'region',\n  Frame: 'region',\n  Box: 'region',\n};\n\n/** What a recognizer needs to know about the frame it is given. */\nexport interface RecognizeOptions {\n  readonly sessionId: string;\n  readonly revision: number;\n  readonly columns: number;\n  readonly rows: number;\n}\n\n/** Resolves one object's role from its framework type. */\nexport function roleFor(frameworkType: string): SemanticRole {\n  return ROLE_BY_TYPE[frameworkType] ?? 'generic';\n}\n\n/**\n * Normalises one observed frame into a semantic snapshot.\n *\n * Facts are carried across, never invented. An object without geometry stays\n * without bounds; a state the probe did not report stays absent, because\n * \"the probe did not say\" and \"the widget is not focused\" are different\n * claims and only one of them is safe to make.\n */\nexport function recognize(frame: ProbeFrame, options: RecognizeOptions): SemanticSnapshot {\n  const nodes: SemanticNode[] = [];\n  const rootIds: string[] = [];\n\n  for (const object of frame.objects) {\n    const node = recognizeObject(object);\n    nodes.push(node);\n    if (object.parent === undefined) rootIds.push(object.identity.value);\n  }\n\n  return {\n    v: 1,\n    sessionId: options.sessionId,\n    revision: options.revision,\n    columns: options.columns,\n    rows: options.rows,\n    rootIds,\n    nodes,\n  };\n}\n\nfunction recognizeObject(object: ProbeObject): SemanticNode {\n  const role = roleFor(object.frameworkType);\n  const state = recognizeState(object);\n\n  return {\n    id: object.identity.value,\n    role,\n    // The framework's own name survives on every node, not only generic ones:\n    // it is what lets a reader tell a Flex-shaped region from a Form-shaped\n    // one after both became `region`.\n    frameworkType: object.frameworkType,\n    name: object.annotations?.name ?? object.text ?? '',\n    ...(object.parent === undefined ? {} : { parentId: object.parent }),\n    // intendedRect is where the widget was drawn. visibleRect is absent for\n    // tview, which computes no clip, so nothing here fabricates one.\n    ...(object.geometry?.intendedRect === undefined\n      ? {}\n      : { bounds: object.geometry.intendedRect }),\n    ...(object.state?.value === undefined ? {} : { value: object.state.value }),\n    ...(state === undefined ? {} : { state }),\n  } as SemanticNode;\n}\n\nfunction recognizeState(object: ProbeObject): SemanticNode['state'] {\n  const observed = object.state;\n  if (observed === undefined) return undefined;\n\n  const state: Record<string, unknown> = {};\n  if (observed.focused !== undefined) state['focused'] = observed.focused;\n  if (observed.disabled !== undefined) state['disabled'] = observed.disabled;\n  if (observed.checked !== undefined) state['checked'] = observed.checked;\n  if (observed.expanded !== undefined) state['expanded'] = observed.expanded;\n  if (observed.readonly !== undefined) state['readonly'] = observed.readonly;\n  // `displayed: false` is the probe's way of saying the framework hid it; the\n  // wire calls that `hidden`, and the inversion is the whole translation.\n  if (observed.displayed === false) state['hidden'] = true;\n  if (observed.selectedIndex !== undefined) state['positionInSet'] = observed.selectedIndex + 1;\n  // A negative scroll offset is a pre-layout artefact, not a position. The Go\n  // probe drops it at the source; this is the same rule, restated where a test\n  // can reach it in one line.\n  if (observed.scroll !== undefined && observed.scroll.row >= 0) {\n    state['scrollOffset'] = observed.scroll.row;\n  }\n  if (observed.scrollExtent !== undefined && observed.scrollExtent.rows >= 0) {\n    state['scrollExtent'] = observed.scrollExtent.rows;\n  }\n\n  return Object.keys(state).length === 0 ? undefined : (state as SemanticNode['state']);\n}\n","/**\n * The one call a launcher makes.\n *\n * Everything else in this package is a step: read the workspace, materialise a\n * copy, patch it, key the cache, write the file. A user should not assemble\n * those, and neither should a test — the assembly order is where the mistakes\n * live, and there is exactly one correct one.\n */\n\nimport { execFile } from 'node:child_process';\nimport { existsSync } from 'node:fs';\nimport { join } from 'node:path';\nimport { fileURLToPath } from 'node:url';\nimport { promisify } from 'node:util';\nimport {\n  applyPatchSet,\n  assertNoVendorMode,\n  copyDir,\n  digestPatchSet,\n  ensureUpstreamModule,\n  isComplete,\n  markComplete,\n  materializeUpstream,\n  prepareCopyDir,\n  readManifest,\n  readWorkspace,\n  writeProvenance,\n  writeWorkspace,\n  type CopyKeyInput,\n} from '@termwright/probe-go';\n\nconst run = promisify(execFile);\n\n/** Module path of the framework this probe instruments. */\nexport const FRAMEWORK = 'github.com/rivo/tview';\n\n/** Module path of the protocol client the injected probe imports. */\nexport const CLIENT_MODULE = 'github.com/gorce-ai/termwright/clients/go';\n\n/** Version of this probe; part of the cache key, so a new patch set invalidates copies. */\nexport const PROBE_VERSION = '0.1.0';\n\nexport interface PrepareOptions {\n  /** Directory of the Go module to build. */\n  readonly moduleDir: string;\n  /** Framework version to instrument, e.g. `v0.42.0`. */\n  readonly frameworkVersion?: string;\n  /** Where the protocol client lives on disk. Defaults to the copy shipped here. */\n  readonly clientDir?: string;\n  /** Where the generated workspace is written. Defaults to inside the copy's cache entry. */\n  readonly workspaceFile?: string;\n  /** Environment the build will run with; checked, never mutated. */\n  readonly env?: NodeJS.ProcessEnv;\n}\n\nexport interface PreparedBuild {\n  /** Hand this to the build as `GOWORK`. */\n  readonly workspaceFile: string;\n  /** The instrumented copy, for a canary check or for diagnosis. */\n  readonly copyDir: string;\n  /** Environment to build with: the caller's, plus GOWORK. */\n  readonly env: NodeJS.ProcessEnv;\n  /** True when the copy was built during this call rather than reused. */\n  readonly built: boolean;\n}\n\n/**\n * Makes a build of `moduleDir` compile against the instrumented framework.\n *\n * Does not build anything and does not spawn the application: a launcher owns\n * that. This returns what the build needs and nothing else, which keeps the\n * package testable and keeps the decision about *how* to run the user's build\n * where it belongs.\n */\nexport async function prepareInstrumentedBuild(\n  options: PrepareOptions,\n): Promise<PreparedBuild> {\n  const env = options.env ?? process.env;\n  // Refused rather than overridden: forcing workspace mode over a vendored\n  // build would change what compiles, behind the user's back.\n  assertNoVendorMode(env);\n\n  const frameworkVersion = options.frameworkVersion ?? (await detectFrameworkVersion(options.moduleDir, env));\n  const patchSetDir = patchSetFor(frameworkVersion);\n  const manifest = await readManifest(patchSetDir);\n\n  const key: CopyKeyInput = {\n    framework: FRAMEWORK,\n    frameworkVersion,\n    probeVersion: PROBE_VERSION,\n    toolchain: await toolchain(env),\n    patchDigest: await digestPatchSet(patchSetDir),\n  };\n\n  const copy = copyDir(key, env);\n  const built = !(await isComplete(copy));\n  if (built) {\n    await prepareCopyDir(copy);\n    await materializeUpstream(await upstreamDir(frameworkVersion, env), copy);\n    await applyPatchSet(copy, patchSetDir);\n    await writeProvenance(copy, manifest);\n    // Last, so an interrupted build is rebuilt rather than compiled.\n    await markComplete(copy, key);\n  }\n\n  const workspaceFile = await writeWorkspace(options.workspaceFile ?? join(copy, '..', 'generated.work'), {\n    moduleDir: options.moduleDir,\n    inherited: await readWorkspace(options.moduleDir),\n    suppliedUses: await clientWorkspaceUses(options, env),\n    replaces: [\n      { from: FRAMEWORK, to: copy },\n      ...(await clientVersionReplacements(options, env)),\n    ],\n  });\n\n  return { workspaceFile, copyDir: copy, env: { ...env, GOWORK: workspaceFile }, built };\n}\n\nasync function clientWorkspaceUses(\n  options: PrepareOptions,\n  env: NodeJS.ProcessEnv,\n): Promise<{ dir: string; module: string }[]> {\n  if ((await modulePath(options.moduleDir, env)) === CLIENT_MODULE) return [];\n  return [{ dir: options.clientDir ?? (await defaultClientDir(env)), module: CLIENT_MODULE }];\n}\n\nasync function clientVersionReplacements(\n  options: PrepareOptions,\n  env: NodeJS.ProcessEnv,\n): Promise<{ from: string; to: string; version: string }[]> {\n  if ((await modulePath(options.moduleDir, env)) === CLIENT_MODULE) return [];\n  const to = options.clientDir ?? (await defaultClientDir(env));\n  const versions = new Set(['v0.0.0']);\n  try {\n    const { stdout } = await run('go', ['list', '-m', '-f', '{{.Version}}', CLIENT_MODULE], {\n      cwd: options.moduleDir,\n      env: { ...env, GOWORK: 'off' },\n    });\n    if (stdout.trim() !== '') versions.add(stdout.trim());\n  } catch {\n    // A project need not import annotations itself. The injected copy still\n    // carries v0.0.0, which is the only version that must be redirected then.\n  }\n  return [...versions].map((version) => ({ from: CLIENT_MODULE, to, version }));\n}\n\n/** Reads the framework version the module actually resolves to. */\nasync function detectFrameworkVersion(moduleDir: string, env: NodeJS.ProcessEnv): Promise<string> {\n  const { stdout } = await run('go', ['list', '-m', '-f', '{{.Version}}', FRAMEWORK], {\n    cwd: moduleDir,\n    // Without this a workspace already in effect could report a replaced\n    // version, and the patch set would be chosen for the wrong source.\n    env: { ...env, GOWORK: 'off' },\n  });\n  return stdout.trim();\n}\n\nasync function modulePath(moduleDir: string, env: NodeJS.ProcessEnv): Promise<string> {\n  const { stdout } = await run('go', ['list', '-m', '-f', '{{.Path}}'], {\n    cwd: moduleDir,\n    env: { ...env, GOWORK: 'off' },\n  });\n  return stdout.trim();\n}\n\n/** Locates the pristine module, fetching it when the cache is cold. */\nasync function upstreamDir(version: string, env: NodeJS.ProcessEnv): Promise<string> {\n  return ensureUpstreamModule({\n    module: FRAMEWORK,\n    version,\n    cachePath: ['github.com', 'rivo', `tview@${version}`],\n    env,\n  });\n}\n\nasync function toolchain(env: NodeJS.ProcessEnv): Promise<string> {\n  const { stdout } = await run('go', ['version'], { env });\n  return stdout.trim();\n}\n\n/** Directory layout used by Go for the lowercase client module path. */\nfunction moduleCachePath(module: string, version: string): readonly string[] {\n  const parts = module.split('/');\n  const last = parts.pop();\n  return last === undefined ? [] : [...parts, `${last}@${version}`];\n}\n\nfunction patchSetFor(version: string): string {\n  return join(packageRoot(), 'upstream-patches', 'tview', version);\n}\n\n/**\n * Where the protocol client lives.\n *\n * A package may vendor it as `go-client/`; this repository uses the workspace\n * source so client edits are picked up without a copy. A published standalone\n * probe resolves the matching tagged Go module into GOMODCACHE, the same\n * release strategy as probe-charm.\n */\nasync function defaultClientDir(env: NodeJS.ProcessEnv): Promise<string> {\n  const vendored = join(packageRoot(), 'go-client');\n  if (existsSync(join(vendored, 'go.mod'))) return vendored;\n\n  const inRepo = join(packageRoot(), '..', '..', 'clients', 'go');\n  if (existsSync(join(inRepo, 'go.mod'))) return inRepo;\n\n  // Published probes and the Go client are released from one versioned\n  // commit. Outside the monorepo, materialise that exact module version in the\n  // normal Go cache instead of requiring a second manually supplied path.\n  const version = `v${PROBE_VERSION}`;\n  return ensureUpstreamModule({\n    module: CLIENT_MODULE,\n    version,\n    cachePath: moduleCachePath(CLIENT_MODULE, version),\n    env,\n  });\n}\n\nfunction packageRoot(): string {\n  return join(fileURLToPath(new URL('.', import.meta.url)), '..');\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@termwright/probe-tview",
+  "version": "0.2.0",
+  "description": "zero-config tview probe: an ephemeral Go workspace redirects the build to an instrumented copy, with no change to the project",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Gorce-AI/termwright.git",
+    "directory": "packages/probe-tview"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "upstream-patches"
+  ],
+  "dependencies": {
+    "@termwright/protocol": "0.2.0",
+    "@termwright/probe-go": "0.2.0"
+  },
+  "devDependencies": {
+    "@termwright/driver": "0.2.0"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --sourcemap --clean",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}