pi-revit 0.2.0 → 0.2.2

package/extensions/pi-revit/index.ts

@@ -3,6 +3,7 @@ import { Type, type TSchema } from "typebox";
 import { readFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
+import { version as packageVersion } from "../../package.json";
 
 interface BridgeInfo {
 	baseUrl: string;
@@ -195,6 +196,17 @@ function registerBridgeTool(pi: ExtensionAPI, descriptor: BridgeToolDescriptor)
 	});
 }
 
+/** `pi update --extensions` refreshes this package but not the deployed Revit add-in,
+ * so a newer extension can silently talk to an older bridge. The add-in reports the
+ * package version it was built from (stamped by scripts/build.ps1); any difference
+ * means the update is incomplete. */
+function versionMismatch(addinVersion: unknown): string | null {
+	const addin = typeof addinVersion === "string" && addinVersion.length > 0 ? addinVersion : null;
+	if (addin === packageVersion) return null;
+	const state = addin ? `still runs version ${addin}` : "predates version reporting";
+	return `pi-revit ${packageVersion} is installed, but the Revit add-in ${state} — the update is incomplete. Close Revit and run: npx.cmd -y pi-revit (or ask the agent to run scripts\\deploy.ps1 from the installed package, then restart Revit).`;
+}
+
 function registerPing(pi: ExtensionAPI) {
 	pi.registerTool({
 		name: "ping",
@@ -206,8 +218,9 @@ function registerPing(pi: ExtensionAPI) {
 		executionMode: "sequential",
 		async execute(_toolCallId, _params, signal) {
 			const payload = await bridgeRequest("/ping", { method: "GET" }, signal, 10_000);
+			const warning = versionMismatch((payload as { addinVersion?: string }).addinVersion);
 			return {
-				content: [{ type: "text", text: JSON.stringify(payload) }],
+				content: [{ type: "text", text: JSON.stringify(payload) + (warning ? `\nWARNING: ${warning}` : "") }],
 				details: payload,
 			};
 		},
@@ -219,6 +232,19 @@ export default async function revitConnector(pi: ExtensionAPI) {
 	// bridge is down, so it is never part of /tools discovery.
 	registerPing(pi);
 
+	// Surface an incomplete update (see versionMismatch) once per session, right
+	// where the user lands after running `pi update --extensions`. Bridge down at
+	// session start is the normal Revit-closed case: stay quiet.
+	pi.on("session_start", async (_event, ctx) => {
+		try {
+			const payload = (await bridgeRequest("/ping", { method: "GET" }, undefined, 3_000)) as { addinVersion?: string };
+			const warning = versionMismatch(payload.addinVersion);
+			if (warning) ctx.ui.notify(warning, "warning");
+		} catch {
+			// No bridge, no verdict.
+		}
+	});
+
 	let descriptors: BridgeToolDescriptor[];
 	try {
 		const payload = (await bridgeRequest("/tools", { method: "GET" }, undefined, DISCOVERY_TIMEOUT_MS)) as {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-revit",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Native Pi connector for Autodesk Revit. Run npx.cmd -y pi-revit for the full Windows install.",
   "author": "Ahmad Altahlawi",
   "license": "MIT",

package/scripts/build.ps1

@@ -20,6 +20,17 @@ $ErrorActionPreference = 'Stop'
 $project = Join-Path $PSScriptRoot '..\src\Revit\RevitBridge.csproj'
 
 $buildArgs = @('build', $project, '-c', $Configuration)
+
+# Stamp the package version into the assembly so the bridge can report which release
+# the deployed add-in came from; the pi extension compares it against its own package
+# version at session start to detect partial updates.
+$packageJson = Join-Path $PSScriptRoot '..\package.json'
+if (Test-Path $packageJson) {
+    $packageVersion = (Get-Content $packageJson -Raw | ConvertFrom-Json).version
+    if ($packageVersion) {
+        $buildArgs += "-p:Version=$packageVersion"
+    }
+}
 if ($TargetFramework) {
     # Override TargetFrameworks (plural) rather than TargetFramework: NuGet restore ignores a
     # single -p:TargetFramework and still restores every framework the project declares, so a

package/src/Revit/BridgeServer.cs

@@ -1,6 +1,7 @@
 using System.IO;
 using System.Net;
 using System.Net.Sockets;
+using System.Reflection;
 using System.Text;
 using System.Text.Json;
 
@@ -22,6 +23,15 @@ namespace RevitBridge
     {
         private const int DefaultPort = 47777;
         private const int MaxPort = 47797;
+
+        /// <summary>Package version stamped into the assembly by scripts/build.ps1. The pi
+        /// extension compares this against its own package version to detect partial
+        /// updates (npm package updated, add-in not redeployed); a build made without
+        /// the stamp reports its default assembly version instead.</summary>
+        private static readonly string AddinVersion =
+            typeof(BridgeServer).Assembly.GetCustomAttribute<AssemblyInformationalVersionAttribute>()?.InformationalVersion?.Split('+')[0]
+            ?? typeof(BridgeServer).Assembly.GetName().Version?.ToString(3)
+            ?? "unknown";
         private const int MaxRequestBytes = 4_000_000;
         private const int MaxContentChars = 12_000;
 
@@ -260,7 +270,7 @@ namespace RevitBridge
         private async Task<(int Status, object Response)> RouteAsync(string method, string path, Dictionary<string, string> query, string body, CancellationToken token)
         {
             if (method == "GET" && path == "/ping")
-                return (200, new { ok = true, service = "revit-bridge", revitVersion = _revitVersion, pid = Environment.ProcessId });
+                return (200, new { ok = true, service = "revit-bridge", revitVersion = _revitVersion, pid = Environment.ProcessId, addinVersion = AddinVersion });
 
             if (method == "GET" && path == "/tools")
             {

package/src/Revit/Tools/SearchApiDocs.cs

@@ -21,16 +21,19 @@ namespace RevitBridge.Tools
     {
         private const int DefaultMaxResults = 10;
         private const int MaxResultsCap = 50;
+
+        // The Max*Chars caps apply to the model-visible markdown only; the index and
+        // the details payload keep the full documentation text.
         private const int MaxMarkdownChars = 6_000;
-        private const int MaxSummaryChars = 600;
         private const int MaxRemarksChars = 600;
         private const int MaxReturnsChars = 300;
         private const int MaxParamDocChars = 240;
         private const int MaxParamsPerMember = 10;
+        private const int MaxExceptionsPerMember = 8;
 
         public string Name => "search_api_docs";
         public string Label => "Search API Docs";
-        public string Description => "Search the offline Revit API documentation (the RevitAPI.xml and RevitAPIUI.xml files shipped with Revit) for types, methods, constructors, properties, fields, and events; every public API enum is fully searchable by value name (values the XML leaves undocumented are synthesized from the API assemblies). query is a single name or substring — e.g. 'FilteredElementCollector', 'Wall.Create', 'WALL_BASE_OFFSET' — ranked: exact name first, then prefix, then substring; dotted Type.Member queries match composites. Returns signatures with summary, remarks, parameter docs, return docs, and the Revit version a member was introduced in ('since'). Works with no document open. Use it to verify exact classes, members, and signatures before writing execute_csharp code. The first query builds the index (a few seconds); later queries are instant.";
+        public string Description => "Search the offline Revit API documentation (the RevitAPI.xml and RevitAPIUI.xml files shipped with Revit) for types, methods, constructors, properties, fields, and events; every public API enum is fully searchable by value name (values the XML leaves undocumented are synthesized from the API assemblies). query is a single name or substring — e.g. 'FilteredElementCollector', 'Wall.Create', 'WALL_BASE_OFFSET' — ranked: exact name first, then prefix, then substring; dotted Type.Member queries match composites, and same-named overloads rank simplest-first. To target one overload, continue the query past a parenthesis with parameter types, e.g. 'Wall.Create(Document, Curve'. Returns signatures with summary, remarks, parameter docs, return docs, exception docs, and the Revit version a member was introduced in ('since'); the top match shows its full docs inline. Works with no document open. Use it to verify exact classes, members, and signatures before writing execute_csharp code. The first query builds the index (a few seconds); later queries are instant.";
 
         public bool RequiresDocument => false;
 
@@ -97,6 +100,9 @@ namespace RevitBridge.Tools
                         .Select(pair => new Dictionary<string, object?> { ["name"] = pair.Key, ["description"] = pair.Value })
                         .ToList(),
                     ["returns"] = member.Returns,
+                    ["exceptions"] = member.Exceptions?
+                        .Select(pair => new Dictionary<string, object?> { ["type"] = pair.Key, ["description"] = pair.Value })
+                        .ToList(),
                 });
             }
 
@@ -134,6 +140,7 @@ namespace RevitBridge.Tools
             var top = scored
                 .OrderByDescending(entry => entry.Score)
                 .ThenBy(entry => entry.Member.Composite.Length)
+                .ThenBy(entry => entry.Member.ParameterCount)
                 .ThenBy(entry => entry.Member.FullName, StringComparer.Ordinal)
                 .Take(maxResults)
                 .Select(entry => entry.Member)
@@ -143,8 +150,15 @@ namespace RevitBridge.Tools
 
         private static int Score(ApiMember member, string q, string[] words)
         {
+            // A query with a parenthesis targets a specific overload by signature,
+            // e.g. 'wall.create(document, curve' — matched against the shortened
+            // signature text before any name-based ranking.
+            bool signatureQuery = q.Contains('(');
+
             int score;
             if (member.CompositeLower == q) score = 1000;
+            else if (signatureQuery && member.SignatureLower == q) score = 980;
+            else if (signatureQuery && member.SignatureLower.StartsWith(q, StringComparison.Ordinal)) score = 950;
             else if (member.ShortNameLower == q) score = 900;
             else if (member.CompositeLower.StartsWith(q, StringComparison.Ordinal)) score = 700;
             else if (member.ShortNameLower.StartsWith(q, StringComparison.Ordinal)) score = 650;
@@ -181,7 +195,7 @@ namespace RevitBridge.Tools
                     }
                     markdown.Append(line);
                     if (i == 0)
-                        AppendTopMatchDocs(markdown, member);
+                        AppendTopMatchDocs(markdown, member, top.Count(other => other.CompositeLower == member.CompositeLower));
                 }
             }
             foreach (string warning in index.Warnings)
@@ -190,18 +204,23 @@ namespace RevitBridge.Tools
         }
 
         /// <summary>The model sees only this markdown — details.payload never reaches it —
-        /// so the top match carries its remarks, parameter, and return docs inline. Lines
-        /// that would blow the markdown budget are dropped individually; narrowing the
-        /// query promotes any other match to the top slot with its docs.</summary>
-        private static void AppendTopMatchDocs(StringBuilder markdown, ApiMember member)
+        /// so the top match carries its remarks, parameter, return, and exception docs
+        /// inline (capped for display; the payload keeps full text). Lines that would blow
+        /// the markdown budget are dropped individually. When the top match is one of
+        /// several same-named overloads, a note says how to target another one.</summary>
+        private static void AppendTopMatchDocs(StringBuilder markdown, ApiMember member, int overloadCount)
         {
-            var lines = new List<string>(3);
+            var lines = new List<string>(5);
             if (member.Remarks is { } remarks)
-                lines.Add($"\n   remarks: {remarks}");
+                lines.Add($"\n   remarks: {Cap(remarks, MaxRemarksChars)}");
             if (member.Parameters is { Count: > 0 } parameters)
-                lines.Add($"\n   params: {string.Join("; ", parameters.Select(pair => $"{pair.Key} — {pair.Value}"))}");
+                lines.Add($"\n   params: {string.Join("; ", parameters.Select(pair => $"{pair.Key} — {Cap(pair.Value, MaxParamDocChars)}"))}");
             if (member.Returns is { } returns)
-                lines.Add($"\n   returns: {returns}");
+                lines.Add($"\n   returns: {Cap(returns, MaxReturnsChars)}");
+            if (member.Exceptions is { Count: > 0 } exceptions)
+                lines.Add($"\n   throws: {string.Join("; ", exceptions.Select(pair => $"{pair.Key} — {Cap(pair.Value, MaxParamDocChars)}"))}");
+            if (overloadCount > 1)
+                lines.Add($"\n   note: {member.Composite} has {overloadCount} overload(s) listed; full docs shown for the simplest top-ranked one. To target another, continue the query past a parenthesis with parameter types, e.g. '{member.Composite}(Document, '.");
             foreach (string line in lines)
             {
                 if (markdown.Length + line.Length > MaxMarkdownChars)
@@ -262,11 +281,18 @@ namespace RevitBridge.Tools
             public required string FullNameLower { get; init; }
             public required string CompositeLower { get; init; }
             public required string ShortNameLower { get; init; }
+            public required string SignatureLower { get; init; }
+
+            /// <summary>Top-level parameter count from the doc id; overload tie-breaks
+            /// rank the simplest overload first.</summary>
+            public required int ParameterCount { get; init; }
+
             public string? Summary { get; init; }
             public string? Remarks { get; init; }
             public string? Returns { get; init; }
             public string? Since { get; init; }
             public IReadOnlyList<KeyValuePair<string, string>>? Parameters { get; init; }
+            public IReadOnlyList<KeyValuePair<string, string>>? Exceptions { get; init; }
         }
 
         private sealed class DocIndex
@@ -364,6 +390,8 @@ namespace RevitBridge.Tools
                     FullNameLower = fullName.ToLowerInvariant(),
                     CompositeLower = composite.ToLowerInvariant(),
                     ShortNameLower = name.ToLowerInvariant(),
+                    SignatureLower = composite.ToLowerInvariant(),
+                    ParameterCount = 0,
                     Summary = enumType == typeof(BuiltInCategory)
                         ? "BuiltInCategory enum value — usable as the 'category' argument of get_elements/get_element_types and with FilteredElementCollector.OfCategory in execute_csharp."
                         : $"{typeName} enum value (not documented in the XML; synthesized from {assemblyName} metadata).",
@@ -481,12 +509,24 @@ namespace RevitBridge.Tools
                 if (parameters is { Count: >= MaxParamsPerMember })
                     break;
                 string? name = param.Attribute("name")?.Value;
-                string? text = Cap(CleanDocText(param), MaxParamDocChars);
+                string? text = CleanDocText(param);
                 if (string.IsNullOrEmpty(name) || string.IsNullOrEmpty(text))
                     continue;
                 (parameters ??= new List<KeyValuePair<string, string>>()).Add(new KeyValuePair<string, string>(name, text));
             }
 
+            List<KeyValuePair<string, string>>? exceptions = null;
+            foreach (var exception in element.Elements("exception"))
+            {
+                if (exceptions is { Count: >= MaxExceptionsPerMember })
+                    break;
+                string? cref = exception.Attribute("cref")?.Value;
+                string? text = CleanDocText(exception);
+                if (string.IsNullOrEmpty(cref) || string.IsNullOrEmpty(text))
+                    continue;
+                (exceptions ??= new List<KeyValuePair<string, string>>()).Add(new KeyValuePair<string, string>(ShortCref(cref), text));
+            }
+
             return new ApiMember
             {
                 Kind = kind,
@@ -498,14 +538,34 @@ namespace RevitBridge.Tools
                 FullNameLower = path.ToLowerInvariant(),
                 CompositeLower = composite.ToLowerInvariant(),
                 ShortNameLower = shortName.ToLowerInvariant(),
-                Summary = Cap(CleanDocText(element.Element("summary")), MaxSummaryChars),
-                Remarks = Cap(CleanDocText(element.Element("remarks")), MaxRemarksChars),
-                Returns = Cap(CleanDocText(element.Element("returns")), MaxReturnsChars),
+                SignatureLower = signature.ToLowerInvariant(),
+                ParameterCount = CountTopLevelParameters(paramText),
+                Summary = CleanDocText(element.Element("summary")),
+                Remarks = CleanDocText(element.Element("remarks")),
+                Returns = CleanDocText(element.Element("returns")),
                 Since = CleanDocText(element.Element("since")),
                 Parameters = parameters,
+                Exceptions = exceptions,
             };
         }
 
+        /// <summary>Parameter count of a doc-id parameter list; commas inside generic
+        /// braces (Dictionary{K,V}) do not separate parameters.</summary>
+        private static int CountTopLevelParameters(string? paramText)
+        {
+            if (string.IsNullOrEmpty(paramText))
+                return 0;
+            int count = 1;
+            int depth = 0;
+            foreach (char c in paramText)
+            {
+                if (c == '{') depth++;
+                else if (c == '}') depth--;
+                else if (c == ',' && depth == 0) count++;
+            }
+            return count;
+        }
+
         // ------------------------------------------------------------- text utils
 
         /// <summary>Flattens doc XML to plain text: see/seealso cref -> short type name,