pi-revit 0.1.0

package/scripts/setup-workspace.ps1

@@ -0,0 +1,53 @@
+#Requires -Version 5.1
+<#
+Sets up the pi-revit user environment on this PC:
+
+  1. Workspace at Documents\pi-revit (AGENTS.md conventions, Projects\sample template,
+     double-click launcher). Existing AGENTS.md files are never overwritten.
+  2. Global `pi-revit` command installed next to the `pi` command, so any terminal can run:
+       pi-revit              -> Pi in the workspace
+       pi-revit <project>    -> Pi in Projects\<project>
+       pi-revit <project> -c -> continue that project's last session
+
+Idempotent — safe to re-run. Usage:
+  scripts\setup-workspace.ps1
+  scripts\setup-workspace.ps1 -WorkspaceDir "D:\work\pi-revit"
+#>
+param(
+    [string]$WorkspaceDir = (Join-Path ([Environment]::GetFolderPath('MyDocuments')) 'pi-revit')
+)
+
+$ErrorActionPreference = 'Stop'
+$templates = Join-Path (Split-Path $PSScriptRoot -Parent) 'workspace'
+
+# 1. Workspace folders
+New-Item -ItemType Directory -Force -Path (Join-Path $WorkspaceDir 'Projects\sample') | Out-Null
+
+# Conventions / notes: copy only when missing so user edits survive re-runs.
+$workspaceAgents = Join-Path $WorkspaceDir 'AGENTS.md'
+if (-not (Test-Path $workspaceAgents)) {
+    Copy-Item (Join-Path $templates 'AGENTS.md') $workspaceAgents
+}
+$projectAgents = Join-Path $WorkspaceDir 'Projects\sample\AGENTS.md'
+if (-not (Test-Path $projectAgents)) {
+    Copy-Item (Join-Path $templates 'project-AGENTS.md') $projectAgents
+}
+
+# Launcher is code, not user data: always refresh.
+Copy-Item (Join-Path $templates 'pi-revit-here.cmd') (Join-Path $WorkspaceDir 'pi-revit.cmd') -Force
+
+Write-Host "Workspace ready: $WorkspaceDir" -ForegroundColor Green
+
+# 2. Global pi-revit command next to pi (that directory is on PATH by definition).
+#    The template's workspace path is rewritten to honor -WorkspaceDir.
+$pi = Get-Command pi -ErrorAction SilentlyContinue
+if ($pi) {
+    $binDir = Split-Path $pi.Source -Parent
+    $globalCmd = Get-Content (Join-Path $templates 'pi-revit-global.cmd')
+    $globalCmd = $globalCmd -replace '^set "WORKSPACE=.*$', ('set "WORKSPACE=' + $WorkspaceDir + '"')
+    Set-Content -Path (Join-Path $binDir 'pi-revit.cmd') -Value $globalCmd -Encoding Ascii
+    Write-Host "Global command installed: $(Join-Path $binDir 'pi-revit.cmd')" -ForegroundColor Green
+    Write-Host 'Run pi-revit from any terminal (pi-revit <project> for a project folder).'
+} else {
+    Write-Warning 'pi command not found on PATH. Install Pi first (npm install -g --ignore-scripts @earendil-works/pi-coding-agent), then re-run this script to get the global pi-revit command.'
+}

package/scripts/uninstall.ps1

@@ -0,0 +1,103 @@
+#Requires -Version 5.1
+<#
+Removes everything the pi-revit install scripts placed on this PC:
+
+  - Revit bridge add-in:  %APPDATA%\Autodesk\Revit\Addins\<version>\RevitBridge.addin
+                          %APPDATA%\Autodesk\Revit\Addins\<version>\RevitBridge\
+  - Global command:       the pi-revit command next to the pi command
+  - Bridge runtime:       %APPDATA%\RevitBridge\ (per-start connection token / bridge.json)
+  - Pi package:           the pi-revit registration (pi remove), best-effort when pi is on PATH
+
+The workspace at Documents\pi-revit holds YOUR data (AGENTS.md notes, per-project
+session history) and is preserved by default. Pass -RemoveWorkspace to delete it too.
+
+Pi itself (the global coding agent) is yours to manage and is never touched.
+
+Close Revit before running. Idempotent — safe to re-run.
+
+Usage:
+  scripts\uninstall.ps1
+  scripts\uninstall.ps1 -RevitVersion 2027
+  scripts\uninstall.ps1 -RemoveWorkspace
+#>
+param(
+    [string]$RevitVersion = '',
+    [string]$WorkspaceDir = (Join-Path ([Environment]::GetFolderPath('MyDocuments')) 'pi-revit'),
+    [switch]$RemoveWorkspace
+)
+
+$ErrorActionPreference = 'Stop'
+
+function Remove-IfExists {
+    param([string]$Path, [string]$Label)
+    if (Test-Path -LiteralPath $Path) {
+        Remove-Item -LiteralPath $Path -Recurse -Force
+        Write-Host "Removed $Label : $Path" -ForegroundColor Green
+    } else {
+        Write-Host "Not present, skipped $Label : $Path"
+    }
+}
+
+# 1. Revit add-in. With no -RevitVersion, sweep every Addins\<version> folder so the
+#    user need not remember which Revit they deployed to.
+$addinsRoot = Join-Path $env:APPDATA 'Autodesk\Revit\Addins'
+$versions = if ($RevitVersion) {
+    @($RevitVersion)
+} elseif (Test-Path -LiteralPath $addinsRoot) {
+    Get-ChildItem -LiteralPath $addinsRoot -Directory | ForEach-Object { $_.Name }
+} else {
+    @()
+}
+foreach ($v in $versions) {
+    $dir = Join-Path $addinsRoot $v
+    Remove-IfExists (Join-Path $dir 'RevitBridge.addin') "Revit $v add-in manifest"
+    Remove-IfExists (Join-Path $dir 'RevitBridge')       "Revit $v add-in folder"
+}
+
+# 2. Global pi-revit command next to pi.
+$pi = Get-Command pi -ErrorAction SilentlyContinue
+if ($pi) {
+    $binDir = Split-Path $pi.Source -Parent
+    Remove-IfExists (Join-Path $binDir 'pi-revit.cmd') 'global pi-revit command'
+} else {
+    Write-Host 'pi not found on PATH; skipping the global pi-revit command.'
+}
+
+# 3. Bridge runtime folder (connection token; recreated on each Revit start).
+Remove-IfExists (Join-Path $env:APPDATA 'RevitBridge') 'bridge runtime folder'
+
+# 4. Pi package registration. Mirror the documented install command exactly:
+#    `pi install ./` stores the package keyed by a path resolved relative to Pi's
+#    settings file, so removal must use the same `./` form from the repo root.
+#    An absolute path may not match the original registration. The repo root is
+#    the parent of this script's folder.
+if ($pi) {
+    $repoRoot = Split-Path $PSScriptRoot -Parent
+    Push-Location $repoRoot
+    try {
+        $global:LASTEXITCODE = 0
+        & pi remove ./
+        if ($LASTEXITCODE -eq 0) {
+            Write-Host 'Removed the pi-revit Pi package.' -ForegroundColor Green
+        } else {
+            Write-Warning "pi remove exited with code $LASTEXITCODE; run 'pi remove ./' from this repo manually."
+        }
+    } catch {
+        Write-Warning "Could not auto-remove the Pi package; run 'pi remove ./' from this repo manually. ($_)"
+    } finally {
+        Pop-Location
+    }
+}
+
+# 5. Workspace (user data) — opt-in only.
+if ($RemoveWorkspace) {
+    Remove-IfExists $WorkspaceDir 'workspace'
+} else {
+    Write-Host ''
+    Write-Host "Workspace preserved (your notes + session history): $WorkspaceDir" -ForegroundColor Yellow
+    Write-Host 'Pass -RemoveWorkspace to delete it too.'
+}
+
+Write-Host ''
+Write-Host 'pi-revit uninstalled. Pi itself is untouched; remove it yourself if you want:' -ForegroundColor Green
+Write-Host '  npm uninstall -g @earendil-works/pi-coding-agent'

package/skills/pi-revit/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: pi-revit
+description: Work with the open Autodesk Revit model through the Revit bridge tools (ping, get_model_overview, get_elements, get_element_details, get_element_types, manage_selection, set_parameters, search_api_docs, execute_csharp, capture_view, export_documents, get_model_health). Use when the user asks about the Revit project, its elements, parameters, selection, or wants to change, script, capture, or export the model.
+---
+
+# Revit
+
+Work with the live Revit model. The tools call a headless bridge add-in inside Revit (2025, 2026, or 2027); Revit must be running with a project open (only `ping` and `search_api_docs` work without a document).
+
+## Tool selection
+
+| Task | Tool |
+|------|------|
+| Bridge alive? Which Revit version? | `ping` |
+| Orientation: project info, units, levels, grids, category counts | `get_model_overview` |
+| List or count elements of ANY category (walls, doors, rooms, sheets, views, ...) | `get_elements` |
+| Read parameter VALUES, location, bounding box, materials of specific elements | `get_element_details` |
+| List element types / family symbols; "used vs merely loaded" | `get_element_types` |
+| Read or change the user's selection; zoom; temporary isolate | `manage_selection` |
+| Write parameter values; rename anything (levels, views, sheets, types) | `set_parameters` |
+| Look up Revit API classes/members/signatures | `search_api_docs` |
+| Everything else (create, delete, move, views, sheets, tagging, ...) | `execute_csharp` |
+| PNG snapshot of a view (visual QA) | `capture_view` (advanced) |
+| PDF/DWG/PNG/IFC file export | `export_documents` (advanced) |
+| Warnings / model quality audit | `get_model_health` (advanced) |
+
+Workflow guidance:
+
+- Call `get_model_overview` first when starting work on an unfamiliar model — one call returns project metadata, units, levels, grids, and category counts.
+- `get_elements` is the listing/counting primitive (`count_only: true` for bare counts). It returns identity fields only (id, name, category, typeName, levelId); read parameter values with `get_element_details`. Prefer a `category` or `of_class` scope when filtering by a parameter's display name.
+- The selection pipeline is `get_elements` -> ids -> `manage_selection` (action `set`); there is no inline filter on selection.
+- `set_parameters` is the home for bulk parameter writes AND renames (the `Name` parameter covers levels, views, sheets, types). One transaction per batch; per-element failures are reported.
+- Before writing `execute_csharp` code, verify unfamiliar classes/members with `search_api_docs` (works with no document open; first query builds the index and takes a few seconds).
+
+## execute_csharp playbook
+
+- Globals: `doc` (Document), `uidoc` (UIDocument), `uiapp` (UIApplication), and `Dump(value)` to record intermediates into the result's `dumps[]`.
+- The transaction is automatic: the whole script runs inside ONE backend-owned transaction — committed on success, rolled back on any exception. Do not open your own `Transaction` (sub-transactions are fine).
+- Scripts must be fully synchronous: `await`/`async` is rejected at compile time; never block on `Task.Result`/`.Wait()`.
+- Return primitives, strings, or anonymous objects/lists; raw Revit API objects are projected to compact shapes (Element -> `{id,name,category,typeName,levelId}`, ElementId -> number, XYZ -> `{x,y,z}`).
+- Lengths are internal units (decimal feet) — convert with `UnitUtils.ConvertToInternalUnits`/`ConvertFromInternalUnits`.
+- Common pitfalls: call `FamilySymbol.Activate()` before `NewFamilyInstance`; use collector-level filtering (`OfCategory`/`OfClass`/`WhereElementIsNotElementType`) and bounded loops — the budget is 120s and Revit cannot be interrupted mid-script; modal dialogs are auto-dismissed and reported in `suppressedDialogs`.
+- `capture_view` returns a `filePath` to a temp PNG, never image data — open it with the read tool to actually see it.
+
+## Failure modes
+
+- **Bridge not reachable** ("Revit bridge is not available" / "Could not reach the Revit bridge"): Revit is not running or the add-in did not load. Ask the user to start Revit, then retry `ping`.
+- **HTTP 409 / "No active Revit document is open."** (`hasActiveDocument: false`): Revit is running but no project is open. Ask the user to open a project, then retry. This fails immediately; do not wait or retry blindly.
+- **Timeout** ("Revit did not answer within Ns", 30s default / 120s for execute_csharp, capture_view, export_documents): Revit is busy or showing a modal dialog. An already-started tool still runs to completion in Revit — verify model state (e.g. `get_elements`) before re-issuing a write.
+- **Cancelled**: same caveat — the bridge cannot abort queued or running work, so verify model state before retrying a write tool.

package/src/Revit/Application.cs

@@ -0,0 +1,94 @@
+using Autodesk.Revit.UI;
+using RevitApplication = Autodesk.Revit.ApplicationServices.Application;
+
+namespace RevitBridge
+{
+    /// <summary>
+    /// Headless add-in entry point. Starts the local bridge on Revit startup and
+    /// stops it on shutdown. No ribbon, no panels, no UI.
+    /// </summary>
+    public sealed class Application : IExternalApplication
+    {
+        private BridgeServer? _server;
+        private ExternalEvent? _externalEvent;
+
+        // ExternalEvents are only pumped while Revit is idle with a document
+        // context; with zero documents open a queued tool call would hang
+        // instead of failing. This cached flag lets the bridge answer 409
+        // immediately. Maintained from document events.
+        private static RevitApplication? _application;
+        private static volatile bool _hasOpenDocument;
+
+        internal static bool HasOpenDocument => _hasOpenDocument;
+
+        public Result OnStartup(UIControlledApplication application)
+        {
+            try
+            {
+                var controlled = application.ControlledApplication;
+                controlled.DocumentOpened += (sender, _) => UpdateDocumentState(sender);
+                controlled.DocumentCreated += (sender, _) => UpdateDocumentState(sender);
+                controlled.DocumentClosed += (sender, _) => UpdateDocumentState(sender);
+
+                var queue = new CommandQueue();
+                // Must be created here: OnStartup is a valid Revit API context.
+                _externalEvent = ExternalEvent.Create(queue);
+                queue.ExternalEvent = _externalEvent;
+
+                _server = new BridgeServer(
+                    queue,
+                    ToolRegistry.CreateDefault(),
+                    application.ControlledApplication.VersionNumber,
+                    () => HasOpenDocument);
+                _server.Start();
+                TryDeleteStartupError();
+                return Result.Succeeded;
+            }
+            catch (Exception ex)
+            {
+                // A broken bridge must never block Revit startup; Pi-side tooling
+                // reports the missing bridge info file instead. Leave a breadcrumb
+                // so "add-in loaded but bridge startup threw" is diagnosable.
+                _server?.Stop();
+                _server = null;
+                TryWriteStartupError(ex);
+                return Result.Succeeded;
+            }
+        }
+
+        public Result OnShutdown(UIControlledApplication application)
+        {
+            _server?.Stop();
+            _externalEvent?.Dispose();
+            return Result.Succeeded;
+        }
+
+        private static void UpdateDocumentState(object? sender)
+        {
+            if (sender is RevitApplication app)
+                _application = app;
+            _hasOpenDocument = (_application?.Documents?.Size ?? 0) > 0;
+        }
+
+        private static string StartupErrorPath() =>
+            Path.Combine(BridgeServer.BridgeInfoDirectory(), "startup-error.txt");
+
+        private static void TryWriteStartupError(Exception ex)
+        {
+            try
+            {
+                Directory.CreateDirectory(BridgeServer.BridgeInfoDirectory());
+                File.WriteAllText(StartupErrorPath(), $"{DateTime.Now:o} Revit bridge failed to start:{Environment.NewLine}{ex}{Environment.NewLine}");
+            }
+            catch
+            {
+                // Diagnostics must never break Revit startup.
+            }
+        }
+
+        private static void TryDeleteStartupError()
+        {
+            try { File.Delete(StartupErrorPath()); } catch { }
+        }
+    }
+}