InterSystems Local Development Package

⚠️ BETA VERSION - This extension is in development. Features may change and bugs may occur. Please report issues via e-mail.

Enhanced local development tools for InterSystems Caché/IRIS in Visual Studio Code. Streamline your workflow with server-side search, automatic project management, and project export capabilities.

Features Overview

• 🔗 Find References (CodeLens) - See who calls each method, across Caché and C#
• 🔍 Server-Side Code Search - Fast search across your codebase with filtering options
• 📦 Automatic Project Management - Auto-add classes to InterSystems projects during local development
• 📤 Project XML Export - Export InterSystems projects to XML directly from VS Code
• 🔄 Server Sync Checker - Detect when server files differ from local versions (multi-project, with on-demand content diff view)
• 📋 Project Browser - Visual overview of all projects, files, and cross-project duplicates
• 📂 Folder Visibility Manager - Show/hide projects in workspace and limit Sync Checker scope
• 🏷️ Go to Tag/Label - Studio-style label+offset^routine navigation with .int mapping
• 🖥️ Auto-Open Terminal - Automatically connect to Interystems terminal on workspace open
• 🔐 Secure Password Storage - Password kept in VS Code SecretStorage (OS keychain), not in settings

🔗 Find References (CodeLens)

See all callers of any method directly from the editor. A "Find references" link appears above every Method and ClassMethod definition.

How it works:

• Click "Find references" above a method definition
• Searches all callers across the Caché namespace via the Atelier API
• Also scans local C# files for a set of cross-language call patterns (string-based REST-style helpers that reference Caché classes/methods)
• Results are filtered to the specific class — won't mix up methods with the same name in different classes

Results display:

• Grouped by source: C# references first, then Caché references
• Caché references grouped by calling class with separators
• Click any result to navigate directly to the calling line

Caché patterns detected: | Pattern | Description | |---------|-------------| | ##class(Package.Class).Method(...) | Standard external call | | ..Method(...) | Internal call within a class |

C# detection is wired for project-specific REST helper patterns. If your codebase uses different helpers, that part of the search will return no hits — the Caché side works regardless.

🔍 Code Search

Search through your InterSystems codebase with server-side search.

Features:

• Package filtering
• File type filtering (classes/routines)
• Case-sensitive matching
• Jump to results
• In-page search (Ctrl+F) - Search within results with highlighting and navigation

Usage:

• Press Ctrl+Shift+F to open search panel
• Enter search term and optionally filter by package/file type
• Click results to open files
• Press Ctrl+F in results to search within the displayed results

📦 Project Watcher

Automatically syncs local class file changes with InterSystems projects.

Configuration: Enable intersystemsLocalDev.watcher.enabled and set intersystemsLocalDev.apiEndpoint in settings

Structure Required:

PROJECT_NAME/
└── CACHE*/                # CACHE, CACHE_Module1, CACHE_Module2, etc.
    ├── .project           # Contains project name
    └── Your/
        └── Classes/
            └── *.cls files

How it works: Monitors all folders with CACHE prefix (e.g. CACHE, CACHE_Module1, CACHE2) and auto-adds/removes classes to projects based on .project config files. Multiple CACHE folders per project are supported.

Status Bar: Shows watcher status (active/disabled/error) in bottom-left corner

📋 Project Browser

Visual overview of all projects and their files with cross-project duplicate detection.

Usage: Command Palette → "InterSystems: Project Browser"

Features:

• Accordion view of all visible projects with file counts
• File status indicators:
  • ✓ OK
  • ⚠ not in project (local file, not in server project)
  • ✗ missing locally (in server project, not on disk)
  • ≠ content differs (both exist, but server version has different content)
• Duplicate detection across projects (.cls/.mac by full class name, .inc/.int by filename)
• Search/filter across all projects and files
• Click actions:
  • Click any file → opens it in the editor
  • Click a content-differs file → opens a side-by-side diff (local ↔ server) in a native VS Code diff editor
• Issue badge tooltip shows only actually-present issue types per project
• Refresh and Force Sync buttons

🏷️ Go to Tag/Label

Studio-style navigation using label+offset^routine format — the same format InterSystems compiler uses in error messages.

Usage: Press Ctrl+Alt+G (or Cmd+Alt+G on Mac) to open the input box.

Supported formats: | Format | Example | Description | |--------|---------|-------------| | label+offset^routine | zSave+50^MyRoutine.mac | Full reference | | label+offset | MyMethod+21 | Current file | | label^routine | Main^Utils.mac | Jump to label | | label | MyMethod | Jump to label in current file | | +offset | +10 | Offset from top |

Smart .int mapping:

• For .mac and .cls files with offset, the extension fetches the compiled .int from the server via Atelier API
• Maps the .int line back to the original source code, correctly handling macro expansions (e.g. a single $$$MacroName line that expands into many lines of compiled code)
• For .cls: handles compiler-generated z prefix on method names and { brace offset
• Falls back to simple offset if server is unavailable

🔄 Server Sync Checker

Checks if files on the InterSystems server differ from your local versions. Monitors all visible projects (respects folder visibility settings).

Two kinds of checks:

1. Project membership (cheap, automatic): detects files that are in the server project but missing locally, or local files that aren't in the server project.

   • Runs at startup, on every poll interval (default 60s), and 5s after saving a local file (debounced)
   • Uses a single SQL query per project plus parallel HEAD verification of missing-locally candidates

2. Content diff (heavier, on-demand): compares the actual content of each tracked file against the server.

   • Runs once at startup (baseline) and on manual Force Sync (refresh button)
   • No automatic periodic content check — manual trigger keeps server load predictable
   • Uses ETag as a cheap filter (HEAD request); content GET is only issued when the ETag has moved
   • Normalization: BOM, CRLF/CR → LF, trailing whitespace per line, leading/trailing blank lines
   • When a diff is found, the file is flagged with a ≠ icon in the Project Browser; click it to open a side-by-side diff view

Performance:

• Shared HTTP/HTTPS keep-alive agent reuses TCP/TLS connections across requests — significant speedup for remote/VPN servers
• Checks are parallelized across projects, PKG expansion, missing-locally verification (10 at a time) and content compare (10 concurrent per project)

Status Bar (bottom-left):

• ✓ Projects — All local files match across all visible projects
• ⚠ Projects (3) — 3 issues found (counts not-in-project + missing-locally + content-differs); click for Project Browser
• 🔄 Refresh button — Force immediate sync check (includes content diff)

Diagnostics: View → Output → channel "InterSystems Sync Checker" shows stale items, content diff positions, and other details.

Configuration:

{
  "intersystemsLocalDev.syncChecker.enabled": true,
  "intersystemsLocalDev.syncChecker.intervalSeconds": 60
}

🖥️ Auto-Open Terminal

Automatically opens Intersystems terminal when you open an InterSystems workspace.

Features:

• Auto-detects InterSystems workspaces (containing .cls files)
• Opens two terminals: one standard terminal (background) and one Intersystems terminal (focused)
• Prevents duplicates on window reload
• Configurable telnet host and port

Configuration:

{
  "intersystemsLocalDev.autoOpenTerminal": true,
  "intersystemsLocalDev.terminalHost": "<your-cache-host>",
  "intersystemsLocalDev.terminalPort": 23
}

The shipped defaults point at an internal Caché host — override terminalHost / terminalPort to match your own server.

📤 Project Export

Export InterSystems project to XML file.

Usage: Right-click any project in the PROJECTS sidebar → "Export Project to XML" → choose save location

📂 Folder Visibility

Show or hide project folders in the workspace — useful when you have many CACHE* folders and only want to focus on a subset. Hidden folders are also excluded from Sync Checker, so background polling stays cheap.

Usage:

• Press Ctrl+K Ctrl+V (or Cmd+K Cmd+V on Mac), or run Command Palette → "InterSystems: Manage Folder Visibility"
• Toggle visibility per folder in the webview panel
• State is persisted per workspace (in workspace state, not settings.json)

🔐 Password Management

Your InterSystems server password is stored in VS Code SecretStorage — the OS-level credential store (Windows Credential Manager / macOS Keychain / Linux libsecret). It is encrypted, local to each machine, and intentionally NOT synced via VS Code Settings Sync.

First-time setup: On the first activation in a workspace, the extension shows an input box asking for the password. Answer "Yes" to the follow-up prompt to save it permanently.

Change / clear the stored password: Press F1 → "InterSystems: Set Password".

• Type a new password and press Enter → overwrites the existing one
• Leave empty and press Enter → confirms and clears the stored password
• After a change, accept the Reload Window prompt so Watcher and Sync Checker pick up the new credentials

Notes:

• The legacy intersystemsLocalDev.password setting is deprecated. If present, it is migrated into SecretStorage on first run and then cleared from settings.json.
• Each machine needs its own one-time password entry; there is no cloud sync of secrets.

Initial Configuration

1. Open Settings (Ctrl+,) and search for intersystems local development
2. Configure server connection:
   • Server URL
   • Namespace
   • Username
   • (Password is not in settings — see Password Management)
3. (Optional) For watcher and export:
   • Watcher Enabled
   • API Endpoint
   • Projects Path (default Projects, relative to workspace root)
4. (Optional) For terminal:
   • Auto Open Terminal
   • Terminal Host
   • Terminal Port

{
  "intersystemsLocalDev.serverUrl": "http://<your-cache-host>:57772",
  "intersystemsLocalDev.namespace": "USER",
  "intersystemsLocalDev.username": "admin",
  "intersystemsLocalDev.apiEndpoint": "/api/extension",
  "intersystemsLocalDev.projectsPath": "Projects",
  "intersystemsLocalDev.watcher.enabled": true,
  "intersystemsLocalDev.syncChecker.enabled": true,
  "intersystemsLocalDev.syncChecker.intervalSeconds": 60,
  "intersystemsLocalDev.autoOpenTerminal": true,
  "intersystemsLocalDev.terminalHost": "<your-cache-host>",
  "intersystemsLocalDev.terminalPort": 23
}

Replace <your-cache-host> with the hostname or IP of your Caché/IRIS server. apiEndpoint must match the route exposed by your server-side helper (the shipped default is /api/extension).

Commands & Keyboard Shortcuts

Enjoy developing! 🚀