feat(installer): ESS Maker Profile lite mode, tutorial panel, and installer improvements

[amilandi]

Summary

Adds the ESS Maker Profile as an optional "lite mode" for the one-shot installer, along with a custom tutorial panel, button gating, and installer robustness fixes.

Testing from this branch

Lite mode (Windows PowerShell):

$branch = 'amilandin/ess-maker-profile-poc'; $base = "https://github.com/@raw/microsoft/Employee-Self-Service-Agent-Developer-Kit/$branch/setup"; & ([scriptblock]::Create((irm "$base/bootstrap-lite.ps1"))) -Branch $branch -SourceBaseUrl $base

Standard mode (Windows PowerShell):

$branch = 'amilandin/ess-maker-profile-poc'; $base = "https://github.com/@raw/microsoft/Employee-Self-Service-Agent-Developer-Kit/$branch/setup"; & ([scriptblock]::Create((irm "$base/bootstrap.ps1"))) -Branch $branch -SourceBaseUrl $base

Lite mode (macOS / Linux):

branch='amilandin/ess-maker-profile-poc'; base="https://github.com/@raw/microsoft/Employee-Self-Service-Agent-Developer-Kit/$branch/setup"; bash <(curl -fsSL "$base/bootstrap-lite-mac.sh") --branch "$branch" --source-base-url "$base"

Standard mode (macOS / Linux):

branch='amilandin/ess-maker-profile-poc'; base="https://github.com/@raw/microsoft/Employee-Self-Service-Agent-Developer-Kit/$branch/setup"; bash <(curl -fsSL "$base/bootstrap-mac.sh") --branch "$branch" --source-base-url "$base"

Note: These commands fetch the installer directly from the PR branch — no need to clone the repo first. For a clean Windows test, uninstall VS Code and delete %USERPROFILE%\source\Employee-Self-Service-Agent-Developer-Kit beforehand. On Mac, delete ~/source/Employee-Self-Service-Agent-Developer-Kit.

Lite mode (new)

• New bootstrap-lite.ps1 / bootstrap-lite-mac.sh install scripts that bundle the Maker Profile extension (chat-first VS Code layout with Quick Actions button rail)
• Standard mode (bootstrap.ps1) is the default — stock VS Code with /setup auto-injected into Copilot Chat
• Extension installs in both modes: lite applies the layout, standard only injects /setup
• Here is how lite mode looks:

- Here is how it looks after clicking the "View tutorial" button

ESS Maker Profile extension (v0.4.23)

• File-based prerequisite watcher — buttons enable/disable based on actual workspace artifacts (.local/config.json for setup, workspace/flightcheck/results.json for flightcheck). Uses FileSystemWatcher + 10s polling fallback.
• Custom tutorial panel — replaces the VS Code walkthrough API (which forced checkboxes). Opens beside chat via ViewColumn.Beside
• Button gating — "Generate tests" and "Push to Copilot Studio" require both setup AND flightcheck to complete first (verified by file existence)
• Mode toggle — "Switch to standard mode" / "Switch to lite mode" buttons with proper layout restore (explorer expands in standard mode)
• View container in primary sidebar — Quick Actions always appears on the left; auxiliary bar closed to prevent duplicate Chat panel
• Staggered re-focus — handles VS Code explorer restoration race condition
• Tutorial toggle — "View tutorial" button toggles to "Hide tutorial" when panel is open; tutorial has a close button

Installer fixes

• Mode setting — installer writes essMaker.mode to VS Code settings.json so the extension knows whether to apply lite layout or just inject /setup
• Code CLI fallback — checks %LOCALAPPDATA%\Programs\Microsoft VS Code\bin\code.cmd when code isn't on PATH after fresh winget install
• Non-git directory handling — if clone target exists without .git, auto-removes and re-clones instead of crashing
• macOS parity — equivalent fixes in install-ess-adk.sh and bootstrap-lite-mac.sh

Tests

• extension.test.js — 21 unit tests for ACTIONS structure, actionState logic, layout settings, package.json config
• Install-EssAdk.Tests.ps1 — 12 smoke tests for installer syntax, parameters, code CLI fallback, and bootstrap script consistency

Files changed

Area	Key files
Extension	tools/ess-maker-profile/extension/extension.js, package.json
Installer	setup/Install-EssAdk.ps1, setup/bootstrap-lite.ps1, setup/bootstrap.ps1
Mac scripts	setup/bootstrap-lite-mac.sh, setup/bootstrap-mac.sh, setup/install-ess-adk.sh
Tests	tools/ess-maker-profile/extension/extension.test.js, setup/Install-EssAdk.Tests.ps1

[avneeshraiusit]

🔴 Critical Issues

1. waitForWelcomeWizard shells out to Python to read SQLite — fragile & insecure

File: extension.js (~lines 230-290)

The extension spawns python -c with an inline script to query VS Code's internal state.vscdb — this is:

• Fragile: Assumes python is on PATH (not guaranteed on Windows). If Python isn't installed, the whole wizard-wait chain silently fails.
• Brittle coupling: Relies on undocumented internal VS Code state DB key (welcomeOnboarding.state). This can change without notice in any VS Code update.
• Shell injection risk: resolvedDbPath is interpolated into a Python string with r"""...""". While rare, paths with triple-quotes would break this.
• Performance: Spawning a Python process every 2 seconds for up to 5 minutes (150 polls) is wasteful.

Fix: Use VS Code's own APIs (vscode.workspace.onDidChangeConfiguration, or watch for the known welcome walkthrough completion event) instead of polling an internal SQLite DB.

2. Clipboard hijack for /setup injection

File: extension.js injectSetup() function

The code overwrites the user's clipboard with /setup, pastes it, then restores the previous clipboard. This is a classic race condition — if the user copies something between the read and the restore, their clipboard content is lost. Also breaks if the paste action fails silently.

Fix: Use the proper Chat API (vscode.commands.executeCommand('workbench.action.chat.open', { query: '/setup' })) or VS Code's chat command with input arguments.

3. Binary .vsix committed to source

File: ess-maker-profile-0.4.23.vsix

Checking in a binary artifact to git bloats the repo history permanently. Every version bump adds another immutable blob.

Fix: Build the VSIX in CI and publish as a release artifact, or use a vsce package step in the installer.

---

🟠 Significant Concerns

4. VS Code settings.json mutation is destructive

File: Install-EssAdk.ps1 (maker profile section)

ConvertFrom-Json | ConvertTo-Json strips comments from settings.json (JSON with Comments is standard in VS Code settings). Many users have //-commented lines. This silently corrupts their settings file.

Fix: Use a regex insert or a JSON5-aware parser, or write to a separate file that the extension reads.

5. Global settings modification without consent

The extension applies CHAT_ONLY_LAYOUT at Global scope — permanently modifying 30+ user settings. If the user uninstalls the extension without clicking "Restore Standard Layout," their VS Code is left in a broken state (no menu bar, no status bar, no tabs).

Fix: Persist original values before overwriting and restore on extension uninstall. Better: use workspace-scoped settings only.

6. Remove-Item -Recurse -Force on non-git directory

File: Install-EssAdk.ps1

This silently deletes the user's data if they happen to have a folder with the same name that isn't a git repo. At minimum, prompt the user before nuking a directory.

7. 10-second polling fallback never stops

File: extension.js startPrereqWatcher()

The setInterval(refresh, 10000) runs forever while VS Code is open, even if the workspace has no ESS content. The cleanup only happens on deactivation, but the extension activates onStartupFinished unconditionally.

---

🟡 Minor Issues

8. eval() in test file

File: extension.test.js — Uses eval() to extract ACTIONS and actionState from the source. Brittle regex over code. Consider exporting these as a separate module.

9. macOS source for installer execution

File: bootstrap-lite-mac.sh — source runs in the current shell. If install-ess-adk.sh calls exit, it kills the user's terminal session.

10. Inconsistent mode semantics

-SkipMakerProfile means "use standard mode" but the flag name suggests "skip installing the extension." The extension is still installed — it just doesn't apply the lite layout. The parameter name is misleading.

11. No test.sh for the setup/ directory

The setup scripts have Install-EssAdk.Tests.ps1 but no test.sh wrapper, so CI won't run these tests per the repo convention.

---

✅ What's Good

• File-based prerequisite watching is a solid pattern for gating buttons
• Tutorial panel as a webview (instead of VS Code's limited walkthrough API) is pragmatic
• Test coverage for the action state machine logic
• Code CLI fallback for fresh winget installs is a real UX fix
• Mode toggle is well-designed

[avneeshraiusit]

Some manual and LLM generated comments

[amilandi]

Our screenshots do not have the option to switch back to lite mode on the left bottom? That was part of original POC, intentional?

If the user wants to use the quick actions from standard mode (including the option to switch back to lite mode) then they need to click this button on the left, which shows up in standard mode

[amilandi]

Thanks for the review! Here's what I've addressed and what's acknowledged for future work:

Fixed in d66fc97

#1 — Python subprocess replaced with pure Node.js
waitForWelcomeWizard now uses fs.readFileSync + Buffer.indexOf to search the raw SQLite file for welcomeOnboarding.state. No Python dependency, no shell injection risk, no external process spawning. Re: undocumented DB key — this is the only mechanism available; VS Code has no API for welcome wizard completion state. We accept the coupling risk since the fallback (5-min timeout → user clicks Connect) is graceful.

#2 — Clipboard hijack replaced with Chat API
injectSetup now uses workbench.action.chat.open with { query: '/setup', isPartialQuery: false } as the primary approach. Clipboard paste is retained only as a fallback for older VS Code builds.

#7 — Polling stops when prerequisites are met
The 10-second polling fallback now stops once both setup and flightcheck prerequisites are confirmed. FileSystemWatcher remains active so deletions restart polling.

#9 — bootstrap-mac source/exit fixed
All three Mac bootstrap scripts (bootstrap-mac.sh, bootstrap-lite-mac.sh, bootstrap-flightcheck-mac.sh) now use bash instead of source to run the installer in a subshell. Env vars were already exported.

Already handled (no changes needed)

#6 — Remove-Item safety
Both the Windows and Mac installers already check for .git/ directory before removing — only non-git directories (partial install leftovers) are deleted. See Install-EssAdk.ps1 line 574 and install-ess-adk.sh line 170.

Acknowledged for future work

#3 — Binary VSIX in git
Valid concern. For this POC/prototype, the VSIX is committed for simplicity. Moving to CI-built artifacts is planned for the production version.

#4 — settings.json comment stripping
ConvertFrom-Json does strip JSONC comments. For the installer's use case (writing to a fresh or simple settings.json), this is acceptable. A JSON5-aware approach is a good improvement for later.

#5 — Global settings modification
The extension applies settings at Global scope intentionally (workspace scope is unreliable on Windows for certain UI settings like menu bar/title bar). The "Restore Standard Layout" command reverses all changes. Adding save/restore of original values on uninstall is a good improvement for later.

#8 — eval() in tests
Agree it's brittle. Refactoring exports is a low-priority improvement.

#10 — SkipMakerProfile naming
The flag name reflects the installer's perspective ("skip installing the maker profile extension's layout"), not the mode name. Could be renamed for clarity but would be a breaking change for anyone with existing automation.

#11 — No test.sh
Setup tests are PowerShell-specific (Pester). Mac-side testing would require a separate test harness. Deferred.

[amilandi]

Update on #7 (polling): Reverted the polling stop in 661fd9b. Continuous polling is needed because:

• Users can reset quick actions, which clears prerequisite state
• Switching environments deletes .local/config.json and workspace/flightcheck/results.json
• The 10s interval is lightweight (just fs.existsSync + file reads) and ensures buttons always reflect the true state

[avneeshraiusit]

Follow-up: Review Feedback Resolution

Thanks for the updates! Here's where things stand:

#	Issue	Status	Notes
1	Python shell-out for wizard detection	✅ Fixed	Pure Node.js readFileSync + Buffer.indexOf. No more spawning Python.
2	Clipboard hijack	✅ Fixed	Now uses chat.open with { query, isPartialQuery: false }. Clipboard is fallback only.
3	Binary .vsix in repo	❌ Open	Still committed — permanent repo bloat on every version bump.
4	settings.json comment stripping	❌ Open	`ConvertFrom-Json
5	Global settings without backup	❌ Open	30+ global settings modified with no backup. Uninstalling the extension leaves VS Code broken.
6	Remove-Item -Recurse -Force without prompt	❌ Open	Still silently deletes non-git directories matching the repo name.
7	Polling never stops	✅ Accepted	Rationale is sound — users can reset state or switch environments. Cost is low.
9	macOS source killing terminal	✅ Fixed	Changed to bash "$TEMP_DIR/..." across all bootstrap scripts.

Still blocking (IMO)

#4 is the most user-impacting. Many VS Code users have // comments in their settings.json. The ConvertFrom-Json → ConvertTo-Json round-trip silently strips them all. Options:

• Write essMaker.mode to a separate file the extension reads (e.g. ~/.ess-maker/config.json)
• Use string manipulation to insert the key without full JSON deserialization
• Use code --config CLI if available

#5 should at minimum save original values before overwriting (e.g. into globalState) and restore them when "Restore Standard Layout" is clicked or on extension uninstall.

#6 — a simple Read-Host "Remove $repoPath? (y/N)" or at least a visible warning before deletion would prevent accidental data loss.

#3 (binary in repo) is less urgent but worth a follow-up issue to build the VSIX in CI.

[amilandi]

Addressed the remaining items in b6b7d40:

#4 — settings.json comment preservation ✅
Replaced ConvertFrom-Json | ConvertTo-Json with regex-based string manipulation. The installer now uses -replace to insert/update essMaker.mode without parsing or rewriting the full file. JSONC comments are preserved.

#5 — Settings backup/restore ✅
applyChatOnlyLayout now saves original user global settings to globalState before overwriting (only on first apply). restoreStandardLayout reads from that backup and restores original values — or removes the key if the user had no prior value. Backup is cleared after restore.

#6 — 5-second abort window before deletion ✅
Both Windows and Mac installers now print a clear warning and sleep 5 seconds before removing a non-git directory, giving users time to Ctrl+C if the directory contains their own data.

Only #3 (binary VSIX in git) remains open — will track as a follow-up for CI-based artifact publishing.

[avneeshraiusit]

Q: why did we leave "Only #3 (binary VSIX in git) remains open — will track as a follow-up for CI-based artifact publishing." ?

[avneeshraiusit]

Approving with a suggestion

[amilandi]

Re: #3 (binary VSIX in git) — We left this open because the installer currently fetches the VSIX directly from
aw.githubusercontent.com, so removing it from the repo requires changing the delivery mechanism (e.g., CI builds the VSIX and uploads to GitHub Releases, then the installer pulls from there instead). That's a separate piece of work we'll track as a follow-up — it doesn't block the current PR's functionality and the file is only ~24KB per version bump.

[avneeshraiusit]

Approved