PKGShell Extension

The official VS Code extension for PKGShell packages delivers full syntax highlighting, IntelliSense, diagnostics, and workflow helpers for .ini-based deployment scripts. It is optimized for internal packaging pipelines and bundles editor assistance, validation, formatting, and navigation tools in one place.

Overview
Highlights
Installation
Supported Files
IntelliSense & Editor Aids
Diagnostics & Quick Fixes
Formatter & Style Guide
Commands & Tools
Themes & Highlighting
Example Workflow
License & Versioning

Overview

PKGShell files combine INI sections, %VAR% substitutions, conditional expressions, and nested Program/SUB blocks. The extension understands the full grammar:

Language ID pkgshell for files such as pkgshell.ini or *_isis.ini.
TextMate grammar that recognizes PKGShell tokens, TEST/SUB headers, PKG commands, expressions, and comments.
Embedded reference data for command properties, environment/default variables, expression methods, and program options.
Rule-driven validation with context-aware code actions.

Highlights

Complete IntelliSense for CommandX, %variables%, expression functions, Program options, and Package Definition keys.
Hover tooltips that surface documentation from the PKGShell defaults (properties, methods, options, variables).
Go-to-definition for %variables%, SUB:/TEST: references, and CommandX.Label jumps.
CodeLens for [SUB:*], [TEST:*], and PKG: calls (with one-click navigation into the referenced package).
Formatter that enforces numbering, casing, spacing, and section layout.
PKG dependency graph view that visualizes PKG: call chains, highlights unresolved references, and warns about cycles before runtime.
SUB/TEST dependency map that exposes nested SUB: chains, callers, and unused test sections directly inside VS Code.
Expression & TEST playground view that evaluates %{…}% expressions or [TEST:*] blocks against customizable mock data so you can iterate on DiskFreeMB, FileExist, RegExist, etc., without running the package.
Diagnostic engine with 15+ rules and matching Quick Fixes.
Built-in commands for resequencing Command blocks and jumping into related packages.

Installation

Visual Studio Code Marketplace

Open Extensions (Ctrl+Shift+X).
Search for "PKGShell Syntax & IntelliSense".
Click Install and reload VS Code if prompted.

Manual Installation

Download the .vsix from the internal release channel or CHANGELOG.md.
Install via code --install-extension pkgshell-extension-x.y.z.vsix.
Confirm the extension is active (F1 → Extensions: Show Installed Extensions).

Supported Files

Extensions: .ini.
Filename patterns: pkgshell.ini, *_isis.ini, .*_isis.ini.
Language ID: pkgshell (shown in the status bar). IntelliSense, formatting, and diagnostics run only when this ID is active.
Automatic adoption: .ini files that match pkgshell.filenameGlobs or contain a [Package Definition] block with Name and numeric Build fields are automatically reassigned to the pkgshell language. Toggle content sniffing through pkgshell.contentDetection.enabled.

IntelliSense & Editor Aids

Command Properties

Typing Command10. opens the property list sourced from pkgshelldefaults/properties.js.
Each completion includes a description, default values, and sample usage.

`%Variables%`

Pressing % suggests entries from [Strings], Command = set VAR=, extension defaults, environment variables, [Package Definition], and dynamically detected Command variables.
Hovers reveal origin (Strings, Command, Env, Package) plus the resolved value.
Go-to-definition jumps straight to where the variable is defined.

Program Options

In program sections the provider suggests only unused options defined in pkgshelldefaults/programSection.js.
Hovers document type information and expected usage.

Expression Functions & Keywords

Within CommandX.Success/Required/While/Until/Foreach and [TEST:*] sections the completion list exposes methods like FILEEXIST, DATEADD, DISKFREEMB, etc., backed by pkgshelldefaults/methods.js.
Logical keywords (AND, OR, NOT, TRUE, FALSE) are offered automatically.

Package Definition

Keys such as Name, Build, Description, Programs, Contact, etc., are suggested in the [Package Definition] block.
Missing required fields can later be inserted via Quick Fix.

SUB/TEST References

SUB: and TEST: tokens autocomplete from existing [SUB:*] or [TEST:*] sections.
Go-to-definition jumps to the respective section header.

Additional Helpers

Hovers over CommandX.Property lines show the official documentation snippet.
Label references in GOTO Label or IF : expr : Label can navigate to their CommandX.Label.
%{ ... %} blocks receive consistent tooltips.

Diagnostics & Quick Fixes

Validation (validation.js) runs automatically on file open, edit, and save. Each rule lives in rules/ and can be extended if needed.

Rule	Purpose	Quick Fix
DuplicateCommand	Duplicate `CommandN` entries inside a section	Renumber to the next free ID and update related properties
InvalidCommandProperty	Unknown `CommandN.*` property	Diagnostic message (no auto-fix)
InvalidCommandSyntax	Bare `set` lines without a `CommandN` prefix	Convert to `CommandNN = SET ...` and renumber as needed
InvalidVariable	`%VAR%` is undefined	Highlights location so the missing source can be added
WrongCommandOrder	Lower command number follows a higher one	Quick Fix "Renumber commands sequentially"
MissingTestSection	`TEST:<name>` lacks a `[TEST:<name>]` block	Automatically insert the missing TEST section
MissingLabel	`GOTO`/`IF` refers to a label that does not exist	Diagnostic message
MissingSubSection	`SUB:<name>` lacks a `[SUB:<name>]` block	Create an empty SUB section with a placeholder command
InvalidIfSyntax	`IF` statement missing the `:expr:number` structure	Diagnostic message
InvalidExpression	Malformed expressions	Diagnostic message
InvalidProgramOption	Unsupported option or data type in a program header	Diagnostic message
DeprecatedParameters	Flags legacy package options such as `FinalStatus`, `IgnoreError`, `Reboot`, or `Verify`	Diagnostic message
MaintenanceWindowCoach	Warns about inconsistent combinations of `Schedule`, `MaxReject`, `Logoff`, `Kickstart`, `ManualClose`, and `Close`	Diagnostic message
ExecutionModeSanity	Enforces valid `Direct`/`Logoff`/`Dialog` combinations and disallows `Direct=1` sections from calling `PKG:` or reboot hooks	Diagnostic message
DialogRebootGuard	Flags `Command*.DoReboot/SuppressReboot/Retry` when `Dialog=1` because dialog mode cannot reboot the user session	Diagnostic message
PackageDefinition	Required keys missing in `[Package Definition]`	Quick Fix inserts the keys with default values
InvalidPkgCommand	`PKG:` missing its target	Quick Fix inserts `PKG:OtherPackage` as a placeholder
MissingPkgTarget	`PKG:Name[:Program]` references an unknown package/program	Diagnostic message
CommandNumbering	Gaps or duplicates in numbering	Quick Fix "Renumber commands sequentially"
UnusedSections	`[SUB:]` or `[TEST:]` blocks exist but are never referenced (reserved `[TEST:Required/PreQueue/Success]` are ignored)	Diagnostic message

All diagnostics show up in the Problems panel and support VS Code Code Actions (F1 → Quick Fix).

Formatter & Style Guide

Normalizes Command IDs (Command01, Command10), properties (Command10.Hidden = 1), and section names.
Enforces blank lines between sections, commands, and comment blocks.
Uppercases TEST:/SUB: references and camel-cases [Package Definition] keys.
Runs via Shift+Alt+F or on save (depending on your VS Code settings) using formatPkgshellDocument.

Commands & Tools

Command Palette

Command	Description
`PKGShell: Renum` (`pkgshell.resequenceCommands`)	Prompts for an increment (default `10`) and renumbers every `CommandN` per section, including attached properties. Ideal for inserting new steps without collisions.
`PKGShell: Wrap Selected Commands In SUB` (`pkgshell.wrapSelectionInSub`)	Moves the selected commands—properties, guards, Foreach definitions, etc.—into a new `[SUB:<name>]` section and replaces the first command in-place with `CommandNN = SUB:<name>`. Useful for factoring reusable blocks or preparing PKG sub-calls.
`PKGShell: Show PKG Dependency Graph` (`pkgshell.showPkgGraph`)	Focuses the PKGShell PKG Graph view, which renders the current package plus all `PKG:` dependencies, unresolved calls, and detected cycles in a tree.
`PKGShell: Show SUB/TEST Dependency Map` (`pkgshell.showStructureGraph`)	Opens the PKGShell SUB/TEST Graph view that lists every `[SUB:]`/`[TEST:]` section, its callers, nested references, and unused definitions.
`PKGShell: Open Expression Playground` (`pkgshell.openExpressionPlayground`)	Opens the PKGShell Expressions view that evaluates `%{…}%` snippets or `[TEST:*]` blocks against mock data editable in JSON form.

CodeLens

[SUB:*] and [TEST:*] headers show reference counters (for example SUB:Cleanup (3 references)). Clicking opens the VS Code references peek.
PKG: lines receive a lens Open PKG:Name[:Program]. Selecting it opens the referenced INI and optionally focuses the program section.

Additional Tools

Quick Fixes (see table above) automate repetitive tasks such as creating missing sections, inserting placeholders, or cleaning up numbering.
PKG: lines are validated against a workspace-wide package index (rules/utils/packageIndex.js).
The PKGShell PKG Graph view (Explorer sidebar) traverses the package index to display sub-package chains, unresolved/variable targets, and cycle warnings with one-click navigation into every referenced package.
The PKGShell SUB/TEST Graph view inspects every [SUB:*], [TEST:*], and Command = SUB/TEST: usage to reveal callers, recursive chains, and unused definitions.
The PKGShell Expressions view provides an interactive playground for single expressions or full [TEST:*] blocks, complete with editable mock environment data for DiskFreeMB, FileExist, RegExist, ServiceExist, Wmi*, and related functions.
WAIT without a duration is valid (indefinite wait) and is no longer flagged by validation.

Themes & Highlighting

PKGShell now advertises standard TextMate scopes (e.g., entity.name.function, variable.parameter) so whatever VS Code theme you run colors the language naturally.
The extension preconfigures editor.tokenColorCustomizations with rules that target only *.pkgshell scopes, restoring the familiar PKGShell palette without hijacking other languages. Override these colors via Settings → editor.tokenColorCustomizations if you prefer a different look.
Inline powershell.exe/pwsh.exe -Command payloads embed the stock PowerShell grammar, so the script portion receives full PowerShell highlighting while the surrounding PKGShell tokens keep their own colors.
The TextMate grammar syntaxes/pkgshell.tmLanguage.json still covers comments, %VAR%, TEST:/SUB: headers, PKG/IF/GOTO, expression operators, and strings.

Example Workflow

Open your pkgshell.ini. VS Code should detect the Pkgshell language automatically.
Insert a new command block and use Command20. → IntelliSense to add properties.
Type % inside the command to reference variables or environment values. Hover to confirm the resolved value and source.
Author the logic for Command20.Success → expression IntelliSense suggests functions like FileExist and DateDiff.
Use F8 to iterate through diagnostics and apply Quick Fixes to create missing [TEST:*] or [SUB:*] sections.
Run PKGShell: Renum whenever you need to close numbering gaps.
Format the document (Shift+Alt+F) to align spacing, casing, and section layout.

License & Versioning

Versioning: SemVer (package.json). Detailed changes are listed in CHANGELOG.md.
The README doubles as the Marketplace description—update both whenever new capabilities ship.

Pkgshell Syntax & IntelliSense

Raizor