Package all three layers. Test installation scripts. Verify governance survives deployment.

# Distribution & Deployment - Virsaitis

**Module**: Distribution & Deployment
**Load**: When packaging, releasing, or deploying Virsaitis
**Version**: 3.0.0
**Updated**: 2026-02-17

---

## 🎯 Purpose

Defines packaging, versioning, release procedures, and deployment strategies for Virsaitis portable distribution.

---

## 🤖 Machine Policy

```
[VERSIONING]
SCHEME=semantic_versioning (major.minor.patch)
VERSION_SYNC=all_components_match
TAG_FORMAT=v{major}.{minor}.{patch}

[PACKAGING]
DISTRIBUTION=portable_zip
SIZE_TARGET=<50MB
COMPONENTS=agent + mcp + extension + skills + docs + portable

[DEPLOYMENT]
TARGET=user_workspace
INSTALLATION=manual_or_scripted
CONFIGURATION=minimal_required
```

---

## 📦 Distribution Package Structure

### Virsaitis Portable v2.0.0

```
virsaitis-portable-v2.0.0/
├── README.md                           (Installation guide)
├── CHANGELOG.md                        (Release notes)
├── LICENSE                             (MIT or appropriate)
├── install.ps1                         (Windows installation script)
├── install.sh                          (Linux/Mac installation script)
│
├── .github/                            (To be copied to user workspace)
│   ├── copilot-instructions.md         (Hub)
│   ├── virsaitis-definition-library.md (Authoritative term definitions)
│   ├── copilot-modules/                (11 modules)
│   │   ├── core-policies.md
│   │   ├── agent-standards.md
│   │   ├── mcp-standards.md
│   │   ├── extension-standards.md
│   │   ├── skills-standards.md
│   │   ├── development-workflow.md
│   │   ├── security-controls.md
│   │   ├── requirements-engineering.md
│   │   ├── testing-quality.md
│   │   ├── integration-patterns.md
│   │   └── distribution-deployment.md
│   ├── agents/
│   │   └── Virsaitis-3.0.agent.md      (Atomic agent definition)
│   └── skills/                         (6 core skills)
│       ├── python-development/
│       │   └── SKILL.md
│       ├── security-controls/
│       │   └── SKILL.md
│       ├── requirements-engineering/
│       │   └── SKILL.md
│       ├── testing-validation/
│       │   └── SKILL.md
│       ├── governance-compliance/
│       │   └── SKILL.md
│       └── typescript-development/
│           └── SKILL.md
│
├── virsaitis-mcp/                      (MCP Server)
│   ├── package.json
│   ├── build/                          (Compiled TypeScript)
│   │   └── index.js
│   ├── README.md
│   └── LICENSE
│
├── virsaitis-extension/                (VS Code Extension)
│   ├── virsaitis-extension-2.0.0.vsix  (.vsix package)
│   ├── README.md
│   └── LICENSE
│
├── docs/                               (Documentation)
│   ├── QUICK-START.md
│   ├── CONFIGURATION.md
│   ├── TROUBLESHOOTING.md
│   ├── ARCHITECTURE.md
│   └── FAQ.md
│
└── templates/                          (Optional templates)
    ├── SKILL-TEMPLATE.md
    ├── SKILL-TEMPLATE-QUICK.md
    └── requirement-template.md
```

---

## 🔢 Semantic Versioning

### Version Structure

**FORMAT**: `MAJOR.MINOR.PATCH`

**EXAMPLES**:
- `1.0.0` - Initial release
- `1.1.0` - New feature (backward compatible)
- `1.1.1` - Bug fix (backward compatible)
- `2.0.0` - Breaking change

### When to Increment

**MAJOR** (breaking changes):
- Agent.md structure change (breaks existing integrations)
- MCP API breaking change
- Extension command removal
- Skill format change (not backward compatible)

**MINOR** (new features, backward compatible):
- New skill added
- New MCP tool added
- New extension command
- New copilot module

**PATCH** (bug fixes, backward compatible):
- Bug fix in MCP validation
- Extension UI fix
- Documentation correction
- Typo fix in Agent.md

### Version Synchronization

**ALL COMPONENTS MUST MATCH**:
- `package.json` (virsaitis-mcp, virsaitis-extension)
- `CHANGELOG.md` (root, per-component)
- Git tag (`v2.0.0`)
- Distribution filename (`virsaitis-portable-v2.0.0.zip`)
- Agent.md version header
- Skill metadata.framework-version

**VERIFY SYNC**:
```bash
# Check all versions match
grep -r '"version":' */package.json
grep -r '**Version**:' .github/*/
```

---

## 📝 Release Checklist

### Pre-Release (Development Complete)

- [ ] All features implemented
- [ ] All tests passing (100%)
- [ ] Coverage ≥70% overall
- [ ] Security tests 100% pass
- [ ] No TIER-0 violations
- [ ] Documentation updated
- [ ] CHANGELOG updated (all components)
- [ ] Version numbers synchronized

### Build & Package

> ⚡ CHECKPOINT — All three layers included in package? Agent + MCP + Extension. Missing one breaks governance.

- [ ] Clean build: `npm run clean && npm run build`
- [ ] MCP server compiled: `virsaitis-mcp/build/`
- [ ] Extension packaged: `vsce package` → `.vsix` file
- [ ] Agent.md validated (atomic structure)
- [ ] Skills validated: `skills-ref validate`
- [ ] Copy all components to distribution directory
- [ ] Create portable ZIP archive
- [ ] Verify archive contents
- [ ] Test archive extraction

### Testing (Clean Environment)

- [ ] Fresh VS Code installation
- [ ] Extract portable package
- [ ] Run installation script
- [ ] Verify file locations
- [ ] Start MCP server
- [ ] Install Extension (.vsix)
- [ ] Configure MCP server URL
- [ ] Test: Protected file modification (should block)
- [ ] Test: Skill activation (python-development)
- [ ] Test: Agent mode activation
- [ ] Test: Status bar shows "Active"
- [ ] Review: All integration points working

### Documentation

- [ ] README.md complete
- [ ] QUICK-START.md updated
- [ ] CHANGELOG.md finalized
- [ ] Known issues documented
- [ ] Migration guide (if breaking changes)
- [ ] API documentation up to date

### Release

- [ ] Commit all changes
- [ ] Tag release: `git tag -a v2.0.0 -m "Release v2.0.0"`
- [ ] Push tag: `git push origin v2.0.0`
- [ ] Create GitHub Release
- [ ] Upload portable ZIP to release
- [ ] Publish release notes
- [ ] Announce release

---

## 🛠️ Installation Scripts

### Windows Installation (install.ps1)

```powershell
# install.ps1 - Virsaitis Portable Installation for Windows

param(
    [string]$WorkspacePath = (Get-Location),
    [string]$MCPPort = "3000"
)

Write-Host "Virsaitis Portable v2.0.0 Installation" -ForegroundColor Cyan
Write-Host "=======================================" -ForegroundColor Cyan

# 1. Copy .github/ to workspace
Write-Host "`n[1/5] Copying governance files..."
Copy-Item -Path ".github" -Destination "$WorkspacePath/.github" -Recurse -Force
Write-Host "✓ Governance files copied" -ForegroundColor Green

# 2. Install MCP Server
Write-Host "`n[2/5] Installing MCP server..."
Set-Location virsaitis-mcp
npm install --production
Write-Host "✓ MCP server installed" -ForegroundColor Green

# 3. Install VS Code Extension
Write-Host "`n[3/5] Installing VS Code extension..."
$vsixPath = Get-ChildItem -Path "../virsaitis-extension/*.vsix" | Select-Object -First 1
code --install-extension $vsixPath.FullName
Write-Host "✓ Extension installed" -ForegroundColor Green

# 4. Configure Extension
Write-Host "`n[4/5] Configuring extension..."
$settingsPath = "$env:APPDATA/Code/User/settings.json"
if (Test-Path $settingsPath) {
    $settings = Get-Content $settingsPath | ConvertFrom-Json
    $settings.'virsaitis.enabled' = $true
    $settings.'virsaitis.mcpServerCommand' = "node"
    $settings.'virsaitis.mcpServerArgs' = @("build/index.js")
    $settings | ConvertTo-Json -Depth 10 | Set-Content $settingsPath
}
Write-Host "✓ Extension configured" -ForegroundColor Green

# 5. Start MCP Server
Write-Host "`n[5/5] Starting MCP server..."
Start-Process -NoNewWindow -FilePath "node" -ArgumentList "build/index.js", "--port", $MCPPort

Write-Host "`n✓ Installation complete!" -ForegroundColor Green
Write-Host "`nNext steps:"
Write-Host "1. Reload VS Code window (Ctrl+Shift+P → 'Developer: Reload Window')"
Write-Host "2. Verify Virsaitis status bar shows 'Active' (bottom right)"
Write-Host "3. Try editing .github/copilot-instructions.md (should be protected)"
Write-Host "`nDocumentation: docs/QUICK-START.md"
```

### Linux/Mac Installation (install.sh)

```bash
#!/bin/bash
# install.sh - Virsaitis Portable Installation for Linux/Mac

WORKSPACE_PATH=${1:-.}
MCP_PORT=${2:-3000}

echo "Virsaitis Portable v2.0.0 Installation"
echo "======================================="

# 1. Copy .github/ to workspace
echo -e "\n[1/5] Copying governance files..."
cp -r .github "$WORKSPACE_PATH/.github"
echo "✓ Governance files copied"

# 2. Install MCP Server
echo -e "\n[2/5] Installing MCP server..."
cd virsaitis-mcp
npm install --production
echo "✓ MCP server installed"

# 3. Install VS Code Extension
echo -e "\n[3/5] Installing VS Code extension..."
VSIX_FILE=$(ls ../virsaitis-extension/*.vsix | head -1)
code --install-extension "$VSIX_FILE"
echo "✓ Extension installed"

# 4. Configure Extension
echo -e "\n[4/5] Configuring extension..."
SETTINGS_PATH="$HOME/.config/Code/User/settings.json"
if [ -f "$SETTINGS_PATH" ]; then
    jq '. + {"virsaitis.enabled": true, "virsaitis.mcpServerCommand": "node", "virsaitis.mcpServerArgs": ["build/index.js"]}' \
       "$SETTINGS_PATH" > "$SETTINGS_PATH.tmp"
    mv "$SETTINGS_PATH.tmp" "$SETTINGS_PATH"
fi
echo "✓ Extension configured"

# 5. Start MCP Server
echo -e "\n[5/5] Starting MCP server..."
nohup node build/index.js --port $MCP_PORT > mcp.log 2>&1 &

echo -e "\n✓ Installation complete!"
echo -e "\nNext steps:"
echo "1. Reload VS Code window (Ctrl+Shift+P → 'Developer: Reload Window')"
echo "2. Verify Virsaitis status bar shows 'Active' (bottom right)"
echo "3. Try editing .github/copilot-instructions.md (should be protected)"
echo -e "\nDocumentation: docs/QUICK-START.md"
```

---

## 🎯 Deployment Strategies

### Strategy 1: Local Installation (Recommended)

**TARGET**: Single developer workspace
**METHOD**: Extract portable ZIP, run installation script
**BENEFITS**: Simple, complete control, no dependencies
**USE CASE**: Individual developers, project teams

### Strategy 2: Organization-Wide

**TARGET**: Multiple developers, shared governance
**METHOD**: Central MCP server, distributed Extension + Skills
**BENEFITS**: Consistent governance, centralized updates
**USE CASE**: Large teams, enterprise deployments

**ARCHITECTURE**:

> ⚡ CHECKPOINT — Installation scripts use mcpServerCommand/mcpServerArgs (stdio), not mcpServerUrl (HTTP).

```
Central MCP Server (virsaitis.company.com:3000)
        ↑
        │ HTTP
        ↓
Developer 1 (Extension → MCP)
Developer 2 (Extension → MCP)
Developer 3 (Extension → MCP)
  ...
Developer N (Extension → MCP)

.github/skills/ distributed via:
- GitHub Enterprise repository
- VS Code Settings Sync
- Organization policy deployment
```

### Strategy 3: Project Template

**TARGET**: New project creation
**METHOD**: Bootstrap new projects with Virsaitis pre-configured
**BENEFITS**: Governance from day one
**USE CASE**: Greenfield projects, standardized setup

---

## 🔧 Configuration Management

### Minimal Required Configuration

**USER MUST SET**:
```json
{
  "virsaitis.enabled": true,
  "virsaitis.mcpServerCommand": "node",
  "virsaitis.mcpServerArgs": ["build/index.js"]
}
```

**OPTIONAL CONFIGURATION**:
```json
{
  "virsaitis.showShieldIcons": true,
  "virsaitis.blockTier0": true,
  "virsaitis.auditLogPath": "./virsaitis-audit.log",
  "virsaitis.failOpen": false
}
```

### Environment Variables (MCP Server)

```bash
# MCP Server configuration
export VIRSAITIS_PORT=3000
export VIRSAITIS_AGENT_PATH=".github/agents/Virsaitis-3.0.agent.md"
export VIRSAITIS_AUDIT_LOG="./mcp-audit.log"
```

---

## 📊 Distribution Metrics

### Package Size Targets

| Component | Target Size | Actual (v2.0.0) |
|-----------|-------------|-----------------|
| **Agent** | <100 KB | ~50 KB |
| **Skills** | <500 KB | ~300 KB |
| **MCP Server** | <10 MB | ~8 MB |
| **Extension** | <5 MB | ~3 MB |
| **Documentation** | <5 MB | ~2 MB |
| **Total ZIP** | <50 MB | ~15 MB |

### Performance Targets

| Metric | Target | Measurement |
|--------|--------|-------------|
| **Installation time** | <5 minutes | Manual timing |
| **MCP startup** | <2 seconds | `time node build/index.js` |
| **Extension activation** | <200ms | VS Code telemetry |
| **Skill load time** | <50ms | Progressive disclosure |

---

## 🔄 Update Procedure

### Patch Update (2.0.0 → 2.0.1)

1. Download new portable ZIP
2. Extract to temporary location
3. Stop MCP server
4. Replace MCP server files
5. Replace Extension (.vsix), reinstall
6. Restart MCP server
7. Reload VS Code
8. Verify: Check status bar, test protected file
9. No .github/ changes needed (backward compatible)

### Minor Update (2.0.1 → 2.1.0)

1. Download new portable ZIP
2. Extract to temporary location
3. **Backup current .github/** (important!)
4. Stop MCP server
5. Replace MCP server files
6. Replace Extension, reinstall
7. **Selectively merge .github/ updates** (review changes)
8. Restart MCP server
9. Reload VS Code
10. Review: New features, configuration changes

### Major Update (2.x.x → 3.0.0)

1. **READ MIGRATION GUIDE** (critical!)
2. Backup entire workspace
3. Review breaking changes
4. Plan migration steps
5. Test in isolated environment first
6. Follow migration guide step-by-step
7. Verify all integration points
8. Update project dependencies if needed

---

## 💡 Best Practices

### Testing Before Release

**ALWAYS TEST IN CLEAN ENVIRONMENT**:
- Fresh OS install (VM recommended)
- Fresh VS Code install
- No existing configurations
- Follow installation guide exactly
- Document any issues

### Documentation

**MUST INCLUDE**:
- Installation instructions (step-by-step)
- Configuration guide
- Troubleshooting section
- Known issues
- Migration guide (for breaking changes)

### Backward Compatibility

**MAINTAIN WHEN POSSIBLE**:
- Keep old MCP tool names (add new, deprecate old)
- Support old configuration formats (warn, don't break)
- Provide migration scripts for data
- Document deprecations clearly

---

## 📚 Quick Reference

| Task | Command/Tool | Location |
|------|--------------|----------|
| **Build MCP** | `npm run build` | virsaitis-mcp/ |
| **Package Extension** | `vsce package` | virsaitis-extension/ |
| **Validate Skills** | `skills-ref validate` | .github/skills/ |
| **Create ZIP** | Archive utility | virsaitis-portable/ |
| **Install (Win)** | `.\install.ps1` | Extracted ZIP |
| **Install (Linux)** | `./install.sh` | Extracted ZIP |

---

*Distribution & Deployment Module v3.0.0*
*Portable packaging and deployment strategies*

---

## Key Rules From This Module

- Package all three layers together. Governance must survive deployment.
- Installation scripts configure stdio transport (mcpServerCommand + mcpServerArgs).
- Test installation scripts on clean machines before release.
- Verify governance enforcement works end-to-end after deployment.
- Definitions: `.github/virsaitis-definition-library.md`

Return to hub: `.github/copilot-instructions.md`