feat: initial implementation — all 35 requirements across phases 1-3
Backend (Spring Boot 3.2 / Java 21 / PostgreSQL): - JWT auth with BCrypt password hashing - User profile + Mifflin-St Jeor BMR calculator - Food search + barcode via OpenFoodFacts API with local cache - Meal CRUD with user data isolation and ownership checks - AI photo analysis (OpenAI Vision) with confidence intervals - AI correction feedback loop for personalisation - Flyway DB migrations + RFC-7807 error responses Mobile (React Native / TypeScript): - Full navigation stack (Auth → Tabs → Home stack) - Design tokens (WCAG 2.2 AA colours, 8px grid, 48px touch targets) - 10 screens: Login, Register, Home, Search, Camera, AI Result, Edit Meal, Daily Details, History, Profile - Confidence-aware calorie display (kcal ± range) - Repeat last meal shortcut + macro tracking Docs: - docs/PLAN-AND-REQUIREMENTS.md - docs/traceability.csv (35 requirements, all Implemented)
This commit is contained in:
208
.github/copilot-modules/agent-standards.md
vendored
Normal file
208
.github/copilot-modules/agent-standards.md
vendored
Normal file
@@ -0,0 +1,208 @@
|
||||
Agent files use atomic sentences. One concept per sentence. Maximum 80 characters per line.
|
||||
|
||||
# Agent Standards - Layer 1
|
||||
|
||||
**Module**: Agent Standards
|
||||
**Component**: Layer 1 (Atomic Markdown Agent)
|
||||
**Load**: When working on virsaitis-agent/ or .github/agents/
|
||||
**Version**: 3.0.0
|
||||
**Updated**: 2026-04-20
|
||||
|
||||
---
|
||||
|
||||
## Machine Policy
|
||||
|
||||
```
|
||||
[AGENT_FORMAT]
|
||||
FORMAT=markdown
|
||||
SENTENCE_STRUCTURE=atomic
|
||||
ENCODING=utf8_no_bom
|
||||
LINE_LENGTH=80_chars_max
|
||||
|
||||
[FILE_OPERATIONS]
|
||||
GITHUB_FOLDER_WRITE=prohibited_except_skills
|
||||
AUTOMATED_FORMATTERS=prohibited
|
||||
CREATE_FILE_TOOL=allowed_outside_github
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Atomic Sentence Construction (TIER-0)
|
||||
|
||||
**Definition**: One sentence expresses exactly ONE concept.
|
||||
|
||||
**Characteristics**:
|
||||
- Single subject-verb-object relationship
|
||||
- No compound clauses ("and", "but", "which" joining ideas)
|
||||
- No nested dependencies or implicit references
|
||||
- Standalone comprehensibility
|
||||
|
||||
**WHY**: AI models comprehend atomic sentences 30% more accurately than compound sentences.
|
||||
|
||||
### Good vs Bad Examples
|
||||
|
||||
**GOOD (Atomic)**:
|
||||
```markdown
|
||||
You must validate file existence.
|
||||
File validation prevents NotFoundError.
|
||||
Run validation before modification.
|
||||
Use read_file tool for validation.
|
||||
```
|
||||
|
||||
**BAD (Compound)**:
|
||||
```markdown
|
||||
You must validate file existence before modification to
|
||||
prevent NotFoundError, and this should be done using the
|
||||
read_file tool which checks both path and permissions.
|
||||
```
|
||||
|
||||
Four concepts in one sentence. Split into four atomic sentences.
|
||||
|
||||
---
|
||||
|
||||
## Markdown Format Requirements
|
||||
|
||||
**FILE FORMAT**:
|
||||
- Extension: `.md` or `.agent.md`
|
||||
- Encoding: UTF-8 without BOM
|
||||
- Line endings: LF (not CRLF)
|
||||
- No trailing whitespace
|
||||
- Single newline at end of file
|
||||
|
||||
**HEADINGS**:
|
||||
- H1: Document title only (one per file)
|
||||
- H2: Major sections
|
||||
- H3: Subsections
|
||||
- Always space after hash: `## Title`
|
||||
|
||||
**LISTS**:
|
||||
- 2-space indent for nesting
|
||||
- Ordered lists for sequential steps
|
||||
- Unordered lists for non-sequential items
|
||||
|
||||
**PROHIBITED**:
|
||||
- Tabs for indentation
|
||||
- Multiple consecutive blank lines
|
||||
- Automated formatters (Prettier, markdownlint)
|
||||
- Spell checkers are OK (no structural changes)
|
||||
|
||||
---
|
||||
|
||||
## .github Folder Governance (TIER-0)
|
||||
|
||||
The `.github/` folder controls Virsaitis governance behavior.
|
||||
Uncontrolled changes to agents, modules, or instructions undermine enforcement.
|
||||
Changes outside `.github/skills/` require the override workflow.
|
||||
|
||||
**EXCEPTION**: `.github/skills/` — AI may create and update skill files.
|
||||
|
||||
**CONSEQUENCE**:
|
||||
- Governance integrity cannot be guaranteed
|
||||
- System must be re-validated manually
|
||||
- Remediation: revert changes, validate all governance files
|
||||
|
||||
---
|
||||
|
||||
## Agent File Workflows (TIER-0)
|
||||
|
||||
### Creation
|
||||
|
||||
1. Generate agent content in memory
|
||||
2. Validate atomic structure (one concept per sentence)
|
||||
3. For files outside `.github/`: use `create_file` tool directly
|
||||
4. For files inside `.github/`: provide code block to user for manual creation
|
||||
5. Verify file content after creation
|
||||
|
||||
### Modification
|
||||
|
||||
1. Read existing file content (entire file)
|
||||
2. Draft changes maintaining atomic structure
|
||||
3. Use `replace_string_in_file` with 3-5 lines context
|
||||
4. Verify no sentences merged accidentally
|
||||
|
||||
**IMPORTANT**: Files in `.github/` (except `.github/skills/`) require the override workflow.
|
||||
|
||||
---
|
||||
|
||||
## Validation Checklist
|
||||
|
||||
**EACH SENTENCE MUST**:
|
||||
- [ ] Express one concept only
|
||||
- [ ] Have clear subject and verb
|
||||
- [ ] Be understood without prior sentence
|
||||
- [ ] Be under 80 characters (recommended)
|
||||
- [ ] Contain no compound clauses
|
||||
|
||||
**CONCEPT COUNTING**: Read aloud. If you pause mid-sentence, split there.
|
||||
|
||||
**COMMON FIXES**:
|
||||
- "and" joining concepts → split into two sentences
|
||||
- "which"/"that" adding details → new sentence with explicit subject
|
||||
- Implicit "it"/"this" → repeat the noun
|
||||
|
||||
---
|
||||
|
||||
## Agent File Structure
|
||||
|
||||
**REQUIRED SECTIONS** (in order):
|
||||
1. Anchor line (governance rule, not title)
|
||||
2. Title + metadata
|
||||
3. Machine-readable policy block
|
||||
4. TIER-0 rules (safety-critical)
|
||||
5. TIER-1 rules (important operations)
|
||||
6. TIER-2/3 rules (quality/info)
|
||||
7. Workflow patterns
|
||||
8. Sandwich close (key rules summary)
|
||||
|
||||
**ATTENTION ENGINEERING**:
|
||||
- Anchor line: highest-attention position (line 1)
|
||||
- Sandwich close: recency zone (last 10 lines)
|
||||
- Tripwires: every ~60 lines in middle sections
|
||||
- Different wording from other sources (CT-3)
|
||||
|
||||
---
|
||||
|
||||
## Change Management
|
||||
|
||||
**MUST UPDATE** agent files when:
|
||||
- New TIER-0 rule added
|
||||
- Existing rule modified
|
||||
- Enforcement consequence changed
|
||||
- New component integration
|
||||
- Security policy updated
|
||||
|
||||
**UPDATE PROCESS**:
|
||||
1. Draft new content (atomic sentences)
|
||||
2. Validate atomic structure
|
||||
3. Update version number and date
|
||||
4. Add CHANGELOG entry
|
||||
5. Commit with REQ-ID reference
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Aspect | Standard | Violation |
|
||||
|--------|----------|-----------|
|
||||
| **Sentences** | One concept only | Multiple concepts |
|
||||
| **File Creation** | Tools outside .github, manual inside | Direct .github modification |
|
||||
| **Encoding** | UTF-8 no BOM | UTF-8 with BOM |
|
||||
| **Line Length** | <80 chars | >120 chars |
|
||||
| **Formatting** | Manual only | Auto-formatter |
|
||||
|
||||
---
|
||||
|
||||
*Agent Standards Module v3.0.0*
|
||||
*Atomic sentence construction for maximum AI comprehension*
|
||||
|
||||
---
|
||||
|
||||
## Key Rules From This Module
|
||||
|
||||
- One concept per sentence. No compound sentences in agent files.
|
||||
- Maximum 80 characters per line. Break at natural points.
|
||||
- Files in `.github/` (except skills/) require the override workflow.
|
||||
- Every agent file must have an anchor line, sandwich close, and tripwires.
|
||||
- Definitions: `.github/virsaitis-definition-library.md`
|
||||
|
||||
Return to hub: `.github/copilot-instructions.md`
|
||||
338
.github/copilot-modules/core-policies.md
vendored
Normal file
338
.github/copilot-modules/core-policies.md
vendored
Normal file
@@ -0,0 +1,338 @@
|
||||
TIER-0 rules cannot be overridden. When in doubt, BLOCK the operation and ask.
|
||||
|
||||
# Core Policies - Virsaitis Governance
|
||||
|
||||
**Module**: Core Policies
|
||||
**Load**: ALWAYS (required for all tasks)
|
||||
**Version**: 3.0.0
|
||||
**Updated**: 2026-02-17
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Purpose
|
||||
|
||||
Defines TIER enforcement system, protected files, and fundamental governance rules that apply across all Virsaitis components.
|
||||
|
||||
---
|
||||
|
||||
## 🤖 Machine Policy
|
||||
|
||||
```
|
||||
[ENFORCEMENT_TIERS]
|
||||
TIER_0=safety_critical (BLOCK, zero_compromise)
|
||||
TIER_1=code_breaking (WARN+CONFIRM, minimal_compromise)
|
||||
TIER_2=quality_standards (WARN+SUGGEST, acceptable_tradeoffs)
|
||||
TIER_3=enhancements (INFO, negotiable)
|
||||
|
||||
[PROTECTED_FILES]
|
||||
PATTERN_1=.github/copilot-instructions.md
|
||||
PATTERN_2=.github/copilot-modules/**/*.md
|
||||
PATTERN_3=.github/agents/*.agent.md
|
||||
|
||||
[MODIFICATION_CONTROL]
|
||||
APPROVAL_REQUIRED=true
|
||||
OVERRIDE_TOKEN=required
|
||||
AUDIT_LOG=all_access
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🚨 TIER-0: Safety-Critical (NEVER VIOLATE)
|
||||
|
||||
### Rule 1: Protected File Modification
|
||||
|
||||
Governance files are the enforcement mechanism itself.
|
||||
Modifying them without approval is equivalent to disabling the system.
|
||||
|
||||
**Protected patterns:**
|
||||
- `.github/copilot-instructions.md`
|
||||
- `.github/copilot-modules/**/*.md`
|
||||
- `.github/agents/*.agent.md`
|
||||
- `.github/virsaitis-definition-library.md`
|
||||
|
||||
**If a modification is attempted:**
|
||||
The operation is BLOCKED. The user must use the override workflow.
|
||||
Direct edits bypass all safety controls and void audit compliance.
|
||||
|
||||
**Override workflow:**
|
||||
1. Acknowledge the user's need for the change
|
||||
2. Explain: this file controls governance enforcement
|
||||
3. Draft the exact change for review
|
||||
4. Command: "Virsaitis: Request Override" (Extension)
|
||||
5. STOP — do not proceed until override is granted
|
||||
|
||||
**CONSEQUENCE:**
|
||||
- **Operation**: BLOCKED immediately
|
||||
- **User Impact**: Must request governance override via PR workflow
|
||||
- **Technical Impact**: Safety controls bypassed, audit trail broken
|
||||
- **Business Impact**: Legal liability, compliance violation, deployment blocked
|
||||
- **Remediation**: Create PR with written justification, await approval
|
||||
|
||||
---
|
||||
|
||||
### Rule 2: Atomic Sentence Structure (Agent.md)
|
||||
|
||||
**RULE:**
|
||||
Agent files communicate through single-concept statements.
|
||||
Compound structures degrade AI parsing accuracy by 30%.
|
||||
Every sentence must stand alone without requiring context from adjacent sentences.
|
||||
|
||||
**REQUIRED FORMAT:**
|
||||
```markdown
|
||||
✅ GOOD (atomic):
|
||||
You must validate file existence.
|
||||
File validation prevents NotFoundError.
|
||||
Run validation before modification.
|
||||
|
||||
❌ BAD (compound):
|
||||
You must validate file existence before modification
|
||||
to prevent NotFoundError, and this should be done
|
||||
using the verify_file function which checks both
|
||||
path and permissions.
|
||||
```
|
||||
|
||||
**CONSEQUENCE:**
|
||||
- **Operation**: Code review rejection
|
||||
- **User Impact**: Agent.md changes not merged, rework required
|
||||
- **Technical Impact**: AI comprehension drops, rules misinterpreted
|
||||
- **Remediation**: Split compound sentences, validate one-concept-per-sentence
|
||||
|
||||
---
|
||||
|
||||
### Rule 3: Secret Management
|
||||
|
||||
**RULE:**
|
||||
Credentials, tokens, and private keys are treated as security incidents if found in source.
|
||||
|
||||
**Patterns that trigger this rule:**
|
||||
- Hardcoded passwords, API keys, tokens
|
||||
- Database credentials in source code
|
||||
- Private keys (.pem, .pfx, .key files)
|
||||
- OAuth tokens, session cookies
|
||||
- Environment variables with ACTUAL values (examples only)
|
||||
|
||||
**REQUIRED APPROACH:**
|
||||
- Use environment variable REFERENCES only (e.g., `process.env.API_KEY`)
|
||||
- Document secret NAMES, never VALUES
|
||||
- Reference secret management services (Azure Key Vault, AWS Secrets Manager)
|
||||
- Run security scan before every commit
|
||||
- Get explicit user confirmation after fixing
|
||||
|
||||
**WHY:**
|
||||
Secrets in Git history cannot be fully removed.
|
||||
Exposed credentials create security incidents.
|
||||
Security incidents trigger compliance violations.
|
||||
Compliance violations have legal consequences.
|
||||
|
||||
**CONSEQUENCE:**
|
||||
- **Operation**: BLOCKED, commit rejected immediately
|
||||
- **User Impact**: Must rotate credential within 1 hour, incident report filed
|
||||
- **Technical Impact**: Security incident triggered, audit log entry, automated alerts
|
||||
- **Business Impact**: Compliance violation, potential data breach, regulatory fines
|
||||
- **Remediation**: Remove secret from Git history (git-filter), rotate credential immediately, complete incident report
|
||||
|
||||
---
|
||||
|
||||
### Rule 4: MCP/Extension Tool Enforcement
|
||||
|
||||
**RULE:**
|
||||
Use Virsaitis MCP tools for governance-critical operations.
|
||||
Native VS Code tools bypass governance validation.
|
||||
|
||||
**TOOL MAPPING (use Virsaitis version):**
|
||||
- Validate file operation → `mcp_virsaitis_validate_operation`
|
||||
- Load governance rules → `mcp_virsaitis_read_governance`
|
||||
- Refresh rule cache → `mcp_virsaitis_reload_cache`
|
||||
- Scan for hardcoded secrets → `mcp_virsaitis_scan_secrets`
|
||||
- Validate file path safety → `mcp_virsaitis_validate_path`
|
||||
- Validate command safety → `mcp_virsaitis_validate_command`
|
||||
- Read audit log → `mcp_virsaitis_read_audit_log`
|
||||
- Post-iteration compliance → `mcp_virsaitis_iteration_complete`
|
||||
|
||||
> ⚡ CHECKPOINT — Is this operation TIER-0? If protected file or secret detected, BLOCK now.
|
||||
|
||||
**WHY:**
|
||||
MCP tools include governance validation hooks.
|
||||
Native tools execute without TIER checking.
|
||||
Bypassing governance creates audit gaps.
|
||||
|
||||
**CONSEQUENCE:**
|
||||
- **Operation**: Governance validation bypassed
|
||||
- **User Impact**: Rules not enforced, potential errors introduced
|
||||
- **Technical Impact**: Audit trail incomplete, traceability lost
|
||||
- **Business Impact**: Compliance gap in audit logs
|
||||
- **Remediation**: Re-run operation using MCP tools, verify governance applied
|
||||
|
||||
**IF MCP TOOL UNAVAILABLE:**
|
||||
1. STOP operation immediately
|
||||
2. Report: "Virsaitis MCP governance tool not available"
|
||||
3. DO NOT use native tool as fallback
|
||||
4. Request: User install/configure Virsaitis MCP server
|
||||
5. Wait for MCP availability before proceeding
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ TIER-1: Critical Operations
|
||||
|
||||
**Definition**: Operations that can break code functionality or violate critical requirements.
|
||||
|
||||
**Enforcement**: WARN + CONFIRM (require explicit user confirmation before proceeding)
|
||||
|
||||
**Examples**:
|
||||
- Component-specific coding standards (indentation, encoding)
|
||||
- REQ-ID traceability (every feature must reference requirement)
|
||||
- CHANGELOG maintenance (every change must be documented)
|
||||
- Test coverage targets (≥70% overall, 100% security-critical)
|
||||
|
||||
**Response Pattern**:
|
||||
```
|
||||
⚠️ TIER-1 VIOLATION DETECTED
|
||||
|
||||
RULE: [Rule name]
|
||||
ISSUE: [What was violated]
|
||||
CONSEQUENCE: [Impact if allowed]
|
||||
|
||||
CONFIRM: Do you want to proceed anyway? (yes/no)
|
||||
RECOMMENDATION: [Better approach]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 TIER-2: Quality Standards
|
||||
|
||||
**Definition**: Best practices that improve maintainability and quality but don't break functionality.
|
||||
|
||||
**Enforcement**: WARN + SUGGEST (provide warning with suggested fix, allow user to proceed)
|
||||
|
||||
**Examples**:
|
||||
- Code quality (linting, formatting)
|
||||
- Documentation completeness
|
||||
- Performance optimizations
|
||||
- Code comments and clarity
|
||||
|
||||
**Response Pattern**:
|
||||
```
|
||||
💡 TIER-2 RECOMMENDATION
|
||||
|
||||
ISSUE: [What could be improved]
|
||||
SUGGESTION: [How to fix]
|
||||
IMPACT: [Benefit if fixed]
|
||||
|
||||
PROCEEDING: [Allowing continuation with awareness]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
> ⚡ CHECKPOINT — TIER-0 rules are absolute. TIER-1/2/3 below are negotiable. Don't confuse them.
|
||||
|
||||
## 💡 TIER-3: Enhancements
|
||||
|
||||
**Definition**: Optional improvements that enhance developer experience but are not required.
|
||||
|
||||
**Enforcement**: INFO (informational only, no blocking or warnings)
|
||||
|
||||
**Examples**:
|
||||
- Code style preferences
|
||||
- Alternative implementation approaches
|
||||
- Efficiency optimizations
|
||||
- Development tool suggestions
|
||||
|
||||
**Response Pattern**:
|
||||
```
|
||||
ℹ️ TIER-3 SUGGESTION
|
||||
|
||||
TIP: [Optional improvement]
|
||||
BENEFIT: [Why it helps]
|
||||
NO ACTION REQUIRED
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📋 Governance Hierarchy
|
||||
|
||||
**Precedence Order** (highest to lowest):
|
||||
1. **TIER-0 Rules** → Always enforced, zero exceptions
|
||||
2. **MCP Server Validation** → Technical enforcement layer
|
||||
3. **Extension Interception** → User action validation
|
||||
4. **Agent.md Instructions** → AI behavioral guidance
|
||||
5. **Skills Modules** → Domain-specific rules
|
||||
6. **Component Standards** → Language/framework conventions
|
||||
|
||||
---
|
||||
|
||||
## Key Rules From This Module
|
||||
|
||||
- TIER-0 operations are BLOCKED immediately. No workarounds, no exceptions.
|
||||
- Protected files (.github/agents/**, .github/copilot-modules/**) require explicit approval.
|
||||
- Secrets detected in code must be removed before any other action.
|
||||
- When uncertain about TIER classification, escalate — do not guess.
|
||||
- Definitions: `.github/virsaitis-definition-library.md`
|
||||
|
||||
Return to hub: `.github/copilot-instructions.md`
|
||||
|
||||
**Conflict Resolution**:
|
||||
- Higher TIER always overrides lower TIER
|
||||
- TIER-0 rules cannot be overridden by any component
|
||||
- Agent.md provides context, MCP/Extension enforce technically
|
||||
- Skills defer to Agent.md for TIER-0 rules
|
||||
|
||||
---
|
||||
|
||||
> ⚡ CHECKPOINT — Before implementing, did you search virsaitis-requirements/ for a REQ-ID? Discovery first.
|
||||
|
||||
## 🔄 Discovery-First Approach
|
||||
|
||||
**Core Principle**: DISCOVER, don't ASSUME. Verify file existence and content before modifying. Search for REQ-IDs before implementing. Ask when uncertain.
|
||||
|
||||
**Full workflow (11 steps)**: See `development-workflow.md` — the authority module for Discovery-First.
|
||||
|
||||
**Key rules**:
|
||||
- Never assume file structure without reading
|
||||
- Never invent REQ-IDs that don't exist
|
||||
- Never proceed when uncertain — respond with `CONFIRM_NEEDED`
|
||||
|
||||
---
|
||||
|
||||
## 🆘 When Uncertain
|
||||
|
||||
**IF UNCERTAIN ABOUT:**
|
||||
- File location or component ownership
|
||||
- REQ-ID applicability
|
||||
- Security implications
|
||||
- TIER classification
|
||||
- Correct tool to use
|
||||
- Atomic sentence structure
|
||||
|
||||
**RESPOND:**
|
||||
```
|
||||
CONFIRM_NEEDED: [specific question]
|
||||
|
||||
CONTEXT: [Why clarification needed]
|
||||
OPTIONS: [If applicable]
|
||||
CONSEQUENCE: [Impact of wrong choice]
|
||||
|
||||
AWAITING: User response
|
||||
```
|
||||
|
||||
**DO NOT:**
|
||||
- Guess or assume
|
||||
- Proceed with ambiguity
|
||||
- Invent information
|
||||
- Bypass governance
|
||||
- Use fallback without confirmation
|
||||
|
||||
---
|
||||
|
||||
## 📚 Quick Reference
|
||||
|
||||
| TIER | Enforcement | User Action | Example |
|
||||
|------|-------------|-------------|---------|
|
||||
| TIER-0 | BLOCK | Cannot proc eed | Modify protected file |
|
||||
| TIER-1 | WARN+CONFIRM | Must approve | Missing REQ-ID |
|
||||
| TIER-2 | WARN+SUGGEST | Can proceed | Linter warning |
|
||||
| TIER-3 | INFO | No action | Code style tip |
|
||||
|
||||
---
|
||||
|
||||
*Core Policies Module v3.0.0*
|
||||
*Foundation for all Virsaitis governance enforcement*
|
||||
512
.github/copilot-modules/development-workflow.md
vendored
Normal file
512
.github/copilot-modules/development-workflow.md
vendored
Normal file
@@ -0,0 +1,512 @@
|
||||
Read before modify. Test before commit. Every change needs a REQ-ID.
|
||||
|
||||
# Development Workflow - Virsaitis
|
||||
|
||||
**Module**: Development Workflow
|
||||
**Load**: For all development tasks
|
||||
**Version**: 3.0.0
|
||||
**Updated**: 2026-02-17
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Purpose
|
||||
|
||||
Defines discovery-first approach, TDD practices, commit workflows, and quality gates for all Virsaitis development.
|
||||
|
||||
---
|
||||
|
||||
## 🤖 Machine Policy
|
||||
|
||||
```
|
||||
[APPROACH]
|
||||
METHODOLOGY=discover_not_assume
|
||||
TESTING=tdd_preferred
|
||||
COMMIT_VALIDATION=mandatory
|
||||
BEFORE_PR=checklist_required
|
||||
|
||||
[WORKFLOW_PATTERN]
|
||||
DISCOVER → READ → SEARCH → VALIDATE → PLAN → CONFIRM → EXECUTE → TEST → UPDATE → VALIDATE → CONFIRM
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔍 Discovery-First Approach (TIER-1)
|
||||
|
||||
### Core Principle
|
||||
|
||||
**DISCOVER, don't ASSUME**
|
||||
|
||||
Never assume file structure, content, or requirements. Always verify before proceeding.
|
||||
|
||||
### Workflow Pattern
|
||||
|
||||
```
|
||||
USER REQUEST
|
||||
↓
|
||||
1. VERIFY: File/directory existence
|
||||
2. READ: Actual file content (entire file or large context)
|
||||
3. SEARCH: Applicable REQ-IDs in requirements/
|
||||
4. VALIDATE: Against TIER rules (core-policies.md)
|
||||
5. PLAN: Minimal change scope
|
||||
6. CONFIRM: If uncertain, ask user explicitly
|
||||
7. EXECUTE: Using appropriate tools/workflow
|
||||
8. TEST: Run validation scripts and test suite
|
||||
9. UPDATE: CHANGELOG + traceability.csv
|
||||
10. VALIDATE: RE-run checks after changes
|
||||
11. CONFIRM: Report success with evidence
|
||||
```
|
||||
|
||||
### Examples
|
||||
|
||||
**❌ ASSUMPTION FAILURE**:
|
||||
```
|
||||
User: "Update the config file"
|
||||
AI: [Assumes location] Updating ./config.json...
|
||||
Result: Wrong file, breaks system
|
||||
```
|
||||
|
||||
**✅ DISCOVERY SUCCESS**:
|
||||
```
|
||||
User: "Update the config file"
|
||||
AI: "CONFIRM_NEEDED: Which config file? Found:
|
||||
- virsaitis-mcp/config.json
|
||||
- virsaitis-extension/package.json
|
||||
- .vscode/settings.json"
|
||||
User: "The MCP config"
|
||||
AI: [Reads virsaitis-mcp/config.json] [Updates correctly]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🧪 Test-Driven Development (TIER-2)
|
||||
|
||||
### TDD Workflow (Preferred)
|
||||
|
||||
```
|
||||
1. Write test FIRST (defines expected behavior)
|
||||
2. Run test: Verify it FAILS (red)
|
||||
3. Write minimum code to pass
|
||||
4. Run test: Verify it PASSES (green)
|
||||
5. Refactor: Improve code quality
|
||||
6. Run test: Verify still PASSES
|
||||
7. Repeat for next feature
|
||||
```
|
||||
|
||||
###Benefits
|
||||
|
||||
- **Design clarity**: Test defines interface first
|
||||
- **Confidence**: Changes protected by tests
|
||||
- **Documentation**: Tests show usage examples
|
||||
- **Regression prevention**: Catches breakage immediately
|
||||
|
||||
### When to Use TDD
|
||||
|
||||
**ALWAYS** for:
|
||||
- MCP tool implementations
|
||||
- Extension command handlers
|
||||
- Governance validators
|
||||
- Security-critical code
|
||||
|
||||
**CAN SKIP** for:
|
||||
- Agent.md content (manual validation)
|
||||
- Documentation updates
|
||||
- Configuration changes
|
||||
- Quick prototypes (but add tests before merge)
|
||||
|
||||
---
|
||||
|
||||
## 📝 Commit Workflow (TIER-1)
|
||||
|
||||
### Before Every Commit
|
||||
|
||||
**CHECKLIST** (all must pass):
|
||||
```bash
|
||||
# 1. Build succeeds
|
||||
npm run build
|
||||
|
||||
# 2. Tests pass
|
||||
npm test
|
||||
|
||||
# 3. Linter clean
|
||||
npm run lint
|
||||
|
||||
# 4. Type check passes (TypeScript)
|
||||
npm run type-check
|
||||
|
||||
# 5. Coverage sufficient
|
||||
npm run test:coverage # ≥70%
|
||||
|
||||
# 6. Security scan clean
|
||||
python scripts/security-scan.py # If available
|
||||
```
|
||||
|
||||
**IF ANY FAIL**: Fix before committing
|
||||
|
||||
### Commit Message Format
|
||||
|
||||
```
|
||||
<type>(<scope>): <description>
|
||||
|
||||
[optional body]
|
||||
|
||||
Implements: REQ-XXX-001
|
||||
Related: REQ-YYY-002
|
||||
```
|
||||
|
||||
**TYPES**:
|
||||
- `feat`: New feature
|
||||
- `fix`: Bug fix
|
||||
- `docs`: Documentation changes
|
||||
- `style`: Formatting (no code change)
|
||||
- `refactor`: Code restructure (no behavior change)
|
||||
- `test`: Test additions/changes
|
||||
- `chore`: Build, dependencies, tooling
|
||||
|
||||
**SCOPES**:
|
||||
- `agent`: Agent.md changes
|
||||
- `mcp`: MCP server changes
|
||||
- `extension`: Extension changes
|
||||
- `skills`: Agent Skills changes
|
||||
- `requirements`: Requirements updates
|
||||
- `docs`: Documentation
|
||||
|
||||
> ⚡ CHECKPOINT — Does this commit include a REQ-ID? Every functional change needs traceability.
|
||||
|
||||
**EXAMPLES**:
|
||||
```
|
||||
feat(mcp): Add file operation validation tool
|
||||
|
||||
Implements TIER-0 protected file checking via MCP tool.
|
||||
Returns validation result with tier and consequences.
|
||||
|
||||
Implements: REQ-MCP-012
|
||||
|
||||
---
|
||||
|
||||
fix(extension): Shield icon not showing on protected files
|
||||
|
||||
File decoration provider was not checking full path patterns.
|
||||
Now uses path.includes() with all protected patterns.
|
||||
|
||||
Implements: REQ-EXT-008
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📋 Component-Specific Workflows
|
||||
|
||||
### Agent Development
|
||||
|
||||
```
|
||||
1. Draft content in memory (atomic sentences)
|
||||
2. Validate atomic structure mentally
|
||||
3. Check: One concept per sentence
|
||||
4. Format as markdown
|
||||
5. Provide code block to user
|
||||
6. User: Create file manually, paste, save
|
||||
7. Manual review: Atomic compliance
|
||||
8. Update CHANGELOG
|
||||
9. Commit with REQ-ID
|
||||
```
|
||||
|
||||
**NEVER**: Use `create_file` for .agent.md
|
||||
|
||||
### MCP Development
|
||||
|
||||
```
|
||||
1. Write test FIRST (TDD)
|
||||
2. Implement MCP tool handler
|
||||
3. Run: npm test
|
||||
4. Run: npm run build
|
||||
5. Run: npm run lint
|
||||
6. Update API documentation
|
||||
7. Update CHANGELOG
|
||||
8. Commit with REQ-ID
|
||||
```
|
||||
|
||||
### Extension Development
|
||||
|
||||
```
|
||||
1. Write test FIRST (TDD)
|
||||
2. Implement feature
|
||||
3. Run: npm run compile
|
||||
4. Run: npm test
|
||||
5. Manual test: Extension Development Host
|
||||
6. Update README (if user-facing)
|
||||
7. Update CHANGELOG
|
||||
8. Commit with REQ-ID
|
||||
```
|
||||
|
||||
### Skills Development
|
||||
|
||||
```
|
||||
1. Use SKILL-TEMPLATE.md
|
||||
2. Fill frontmatter (name, description, metadata)
|
||||
3. Write Standards & Rules (TIER-assigned)
|
||||
4. Write Consequences section (per-TIER impacts)
|
||||
5. Write Procedures with examples
|
||||
6. Validate: skills-ref validate
|
||||
7. Test: VS Code 1.109 (skill activation)
|
||||
8. Update CHANGELOG
|
||||
9. Commit with REQ-ID
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
> ⚡ CHECKPOINT — Did you read the file before modifying it? Discovery first, always.
|
||||
|
||||
## 📊 Quality Gates (TIER-1)
|
||||
|
||||
### Pre-Commit Gates
|
||||
|
||||
**MANDATORY** (blocks commit if failed):
|
||||
- [ ] Build succeeds
|
||||
- [ ] All tests pass
|
||||
- [ ] Linter errors resolved
|
||||
- [ ] Type checking clean (TypeScript)
|
||||
- [ ] No hardcoded secrets
|
||||
- [ ] CHANGELOG updated
|
||||
- [ ] REQ-ID referenced
|
||||
|
||||
**IF GATE FAILS**: Must fix before commit
|
||||
|
||||
### Pre-Merge Gates
|
||||
|
||||
**MANDATORY** (blocks PR merge):
|
||||
- [ ] All pre-commit gates passed
|
||||
- [ ] Code review approved
|
||||
- [ ] Coverage ≥70% overall
|
||||
- [ ] Security tests 100% pass
|
||||
- [ ] Documentation updated
|
||||
- [ ] traceability.csv updated
|
||||
- [ ] No protected file modifications without approval
|
||||
|
||||
### Pre-Release Gates
|
||||
|
||||
**MANDATORY** (blocks version release):
|
||||
- [ ] All tests passing
|
||||
- [ ] Coverage ≥70%
|
||||
- [ ] Security scan clean
|
||||
- [ ] CHANGELOG version updated
|
||||
- [ ] Version numbers consistent (package.json, CHANGELOG, tags)
|
||||
- [ ] Distribution package built
|
||||
- [ ] Installation instructions verified
|
||||
|
||||
---
|
||||
|
||||
## 🔄 Iterative Development
|
||||
|
||||
### Feature Development Cycle
|
||||
|
||||
```
|
||||
ITERATION 1: Minimum Viable
|
||||
→ Write minimal test
|
||||
→ Implement core logic only
|
||||
→ Verify works
|
||||
→ Commit
|
||||
|
||||
ITERATION 2: Edge Cases
|
||||
→ Add edge case tests
|
||||
→ Handle edge cases
|
||||
→ Verify robust
|
||||
→ Commit
|
||||
|
||||
ITERATION 3: Error Handling
|
||||
→ Add error scenario tests
|
||||
→ Implement error handling
|
||||
→ Verify graceful failures
|
||||
→ Commit
|
||||
|
||||
ITERATION 4: Optimization
|
||||
→ Profile performance
|
||||
→ Optimize bottlenecks
|
||||
→ Verify no regression
|
||||
→ Commit
|
||||
```
|
||||
|
||||
**BENEFIT**: Small commits, easy to review, easy to revert
|
||||
|
||||
---
|
||||
|
||||
## 🆘 When Uncertain
|
||||
|
||||
> ⚡ CHECKPOINT — Tests pass? CHANGELOG updated? traceability.csv updated? Check before commit.
|
||||
|
||||
### Response Pattern
|
||||
|
||||
```
|
||||
IF uncertain about:
|
||||
- File location
|
||||
- Component ownership
|
||||
- REQ-ID applicability
|
||||
- TIER classification
|
||||
- Security implications
|
||||
- Correct workflow
|
||||
|
||||
THEN respond:
|
||||
"CONFIRM_NEEDED: [specific question]"
|
||||
|
||||
CONTEXT: [Why clarification needed]
|
||||
OPTIONS: [List options if known]
|
||||
CONSEQUENCE: [Impact of wrong choice]
|
||||
|
||||
AWAITING: User response
|
||||
```
|
||||
|
||||
**DO NOT**:
|
||||
- Guess file paths
|
||||
- Assume requirements
|
||||
- Invent REQ-IDs
|
||||
- Proceed with ambiguity
|
||||
|
||||
**WAIT**: For explicit user clarification
|
||||
|
||||
---
|
||||
|
||||
## 📚 Documentation Updates
|
||||
|
||||
### When to Update Docs
|
||||
|
||||
**MUST UPDATE**:
|
||||
- New feature added (update README)
|
||||
- API changed (update API docs)
|
||||
- Configuration changed (update config guide)
|
||||
- Functional change (update CHANGELOG)
|
||||
- Requirement implemented (update traceability.csv)
|
||||
|
||||
**LOCATIONS**:
|
||||
- **README.md**: Component overview, installation, usage
|
||||
- **CHANGELOG.md**: Version history, changes
|
||||
- **API docs**: Function signatures, parameters
|
||||
- **traceability.csv**: REQ-ID implementation mapping
|
||||
|
||||
### Documentation Standards
|
||||
|
||||
**README.md STRUCTURE**:
|
||||
1. Purpose and scope
|
||||
2. Installation instructions
|
||||
3. Configuration guide
|
||||
4. Usage examples
|
||||
5. API reference (if applicable)
|
||||
6. Troubleshooting
|
||||
7. Contributing guidelines
|
||||
|
||||
**CHANGELOG.md FORMAT**:
|
||||
```markdown
|
||||
## [Unreleased]
|
||||
|
||||
### Added
|
||||
- Feature description (REQ-XXX-001)
|
||||
|
||||
### Changed
|
||||
- Modification description (REQ-YYY-002)
|
||||
|
||||
### Fixed
|
||||
- Bug fix with root cause
|
||||
|
||||
### Security
|
||||
- Security patch (REQ-SEC-XXX)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔍 Code Review Checklist
|
||||
|
||||
### For Reviewer
|
||||
|
||||
**VERIFY**:
|
||||
- [ ] Tests added and passing
|
||||
- [ ] Code follows component standards
|
||||
- [ ] No security issues
|
||||
- [ ] No hardcoded secrets
|
||||
- [ ] Documentation updated
|
||||
- [ ] CHANGELOG updated
|
||||
- [ ] REQ-ID referenced
|
||||
- [ ] No TIER-0 violations
|
||||
- [ ] Atomic sentences (Agent.md)
|
||||
- [ ] Proper indentation (2-space TypeScript, 4-space Python)
|
||||
|
||||
**QUESTIONS TO ASK**:
|
||||
- Is this the simplest solution?
|
||||
- Are edge cases handled?
|
||||
- Is error handling robust?
|
||||
- Is performance acceptable?
|
||||
- Is code maintainable?
|
||||
|
||||
---
|
||||
|
||||
## 💡 Best Practices
|
||||
|
||||
###Small Commits
|
||||
|
||||
**PREFER**:
|
||||
- One logical change per commit
|
||||
- Commit message explains "why" not just "what"
|
||||
- Easy to review (< 500 lines changed)
|
||||
- Easy to revert if needed
|
||||
|
||||
**AVOID**:
|
||||
- Large monolithic commits
|
||||
- Multiple unrelated changes
|
||||
- "WIP" or "misc fixes" messages
|
||||
|
||||
### Continuous Integration
|
||||
|
||||
**AFTER EVERY COMMIT**:
|
||||
- CI pipeline runs automatically
|
||||
- Build verifies compilation
|
||||
- Tests verify functionality
|
||||
- Linters verify style
|
||||
- Coverage reports generated
|
||||
|
||||
**IF CI FAILS**:
|
||||
- Fix immediately (don't commit on top)
|
||||
- Don't merge until green
|
||||
- Consider reverting if blocking team
|
||||
|
||||
### Branching Strategy
|
||||
|
||||
**MAIN BRANCH** (`main`):
|
||||
- Always deployable
|
||||
- Protected (no direct commits)
|
||||
- Requires PR approval
|
||||
|
||||
**FEATURE BRANCHES** (`feature/description`):
|
||||
- Created from `main`
|
||||
- One feature per branch
|
||||
- Delete after merge
|
||||
|
||||
**BUGFIX BRANCHES** (`fix/description`):
|
||||
- Created from `main`
|
||||
- Target specific bug
|
||||
- Delete after merge
|
||||
|
||||
---
|
||||
|
||||
## 📖 Quick Reference
|
||||
|
||||
| Phase | Action | Tool/Command |
|
||||
|-------|--------|--------------|
|
||||
| **Discovery** | Verify file exists | `read_file`, `list_dir` |
|
||||
| **Planning** | Search REQ-IDs | `grep_search requirements/` |
|
||||
| **Development** | Write tests first | `vitest`, `pytest` |
|
||||
| **Validation** | Run checks | `npm run build && npm test` |
|
||||
| **Documentation** | Update CHANGELOG | Manual edit |
|
||||
| **Commit** | Check checklist | Pre-commit hooks |
|
||||
|
||||
---
|
||||
|
||||
*Development Workflow Module v3.0.0*
|
||||
*Discovery-first, TDD, quality gates*
|
||||
|
||||
---
|
||||
|
||||
## Key Rules From This Module
|
||||
|
||||
- Discovery first: verify file exists and read it before modifying.
|
||||
- TDD preferred: write tests before implementation code.
|
||||
- Every change needs a REQ-ID. Search virsaitis-requirements/ first.
|
||||
- Commit messages include `Implements: REQ-XXX-YYY` or `Fixes: REQ-XXX-YYY`.
|
||||
- Definitions: `.github/virsaitis-definition-library.md`
|
||||
|
||||
Return to hub: `.github/copilot-instructions.md`
|
||||
532
.github/copilot-modules/distribution-deployment.md
vendored
Normal file
532
.github/copilot-modules/distribution-deployment.md
vendored
Normal file
@@ -0,0 +1,532 @@
|
||||
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`
|
||||
574
.github/copilot-modules/extension-standards.md
vendored
Normal file
574
.github/copilot-modules/extension-standards.md
vendored
Normal file
@@ -0,0 +1,574 @@
|
||||
Extension intercepts user actions before they reach the filesystem. Governance validation is mandatory.
|
||||
|
||||
# Extension Standards - Layer 3
|
||||
|
||||
**Module**: Extension Standards
|
||||
**Component**: Layer 3 (VS Code Extension)
|
||||
**Load**: When working on virsaitis-development/virsaitis-extension/
|
||||
**Version**: 3.0.0
|
||||
**Updated**: 2026-04-20
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Purpose
|
||||
|
||||
Defines VS Code Extension API standards, TypeScript conventions, and packaging workflow for Virsaitis Extension (Layer 3 user action interception).
|
||||
|
||||
---
|
||||
|
||||
## 🤖 Machine Policy
|
||||
|
||||
```
|
||||
[TECHNOLOGY_STACK]
|
||||
LANGUAGE=TypeScript 5.0+
|
||||
FRAMEWORK=VS Code Extension API 1.85+
|
||||
BUILD=webpack
|
||||
PACKAGE=vsce
|
||||
TEST=@vscode/test-electron
|
||||
|
||||
[CODE_STANDARDS]
|
||||
INDENTATION=2_spaces
|
||||
LINE_LENGTH=100_chars
|
||||
API_VERSION=1.85.0
|
||||
ACTIVATION=lazy_load
|
||||
|
||||
[QUALITY_GATES]
|
||||
COMPILE=must_succeed
|
||||
TESTS=must_pass
|
||||
PACKAGE_SIZE=< 5MB
|
||||
ACTIVATION_TIME=<200ms
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📐 TypeScript Standards
|
||||
|
||||
Same as MCP layer: 2-space indentation, 100-char line length, single quotes, semicolons required. See [MCP Standards](mcp-standards.md) for details.
|
||||
|
||||
---
|
||||
|
||||
## 🔧 VS Code Extension Architecture
|
||||
|
||||
### Project Structure
|
||||
|
||||
```
|
||||
virsaitis-development/virsaitis-extension/
|
||||
├── src/
|
||||
│ ├── extension.ts (entry point, activate/deactivate)
|
||||
│ ├── governance/
|
||||
│ │ ├── file-interceptor.ts (intercept file operations)
|
||||
│ │ ├── mcp-client.ts (communicate with MCP server)
|
||||
│ │ └── shield-decorator.ts (🛡️ UI indicator)
|
||||
│ ├── commands/
|
||||
│ │ ├── request-override.ts
|
||||
│ │ └── show-governance-status.ts
|
||||
│ ├── ui/
|
||||
│ │ ├── status-bar.ts
|
||||
│ │ ├── notifications.ts
|
||||
│ │ └── webview-provider.ts
|
||||
│ └── utils/
|
||||
│ └── config.ts
|
||||
├── test/
|
||||
│ ├── suite/
|
||||
│ │ ├── extension.test.ts
|
||||
│ │ └── governance.test.ts
|
||||
│ └── runTest.ts
|
||||
├── resources/
|
||||
│ └── icons/
|
||||
│ └── shield.svg
|
||||
├── package.json (extension manifest)
|
||||
├── tsconfig.json
|
||||
├── webpack.config.js
|
||||
├── .vscodeignore
|
||||
└── README.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📦 Extension Manifest (package.json)
|
||||
|
||||
### Essential Fields
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "virsaitis-extension",
|
||||
"displayName": "Virsaitis Governance",
|
||||
"description": "AI governance enforcement for VS Code",
|
||||
"version": "2.0.0",
|
||||
"publisher": "virsaitis",
|
||||
"engines": {
|
||||
"vscode": "^1.85.0"
|
||||
},
|
||||
"categories": ["Other"],
|
||||
"activationEvents": [
|
||||
"onStartupFinished",
|
||||
"onCommand:virsaitis.requestOverride"
|
||||
],
|
||||
"main": "./dist/extension.js",
|
||||
"contributes": {
|
||||
"commands": [
|
||||
{
|
||||
"command": "virsaitis.requestOverride",
|
||||
"title": "Virsaitis: Request Override"
|
||||
},
|
||||
{
|
||||
"command": "virsaitis.showGovernanceStatus",
|
||||
"title": "Virsaitis: Show Governance Status"
|
||||
}
|
||||
],
|
||||
"configuration": {
|
||||
"title": "Virsaitis",
|
||||
"properties": {
|
||||
"virsaitis.enabled": {
|
||||
"type": "boolean",
|
||||
"default": true,
|
||||
"description": "Enable Virsaitis governance enforcement"
|
||||
},
|
||||
"virsaitis.mcpServerCommand": {
|
||||
"type": "string",
|
||||
"default": "node",
|
||||
"description": "Command to start Virsaitis MCP server"
|
||||
},
|
||||
"virsaitis.mcpServerArgs": {
|
||||
"type": "array",
|
||||
"default": ["build/index.js"],
|
||||
"description": "Arguments for Virsaitis MCP server process"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Activation (TIER-2)
|
||||
|
||||
### Lazy Activation
|
||||
|
||||
**PATTERN**:
|
||||
```typescript
|
||||
// extension.ts
|
||||
export function activate(context: vscode.ExtensionContext) {
|
||||
console.log('Virsaitis extension activating...');
|
||||
|
||||
// Register commands
|
||||
context.subscriptions.push(
|
||||
vscode.commands.registerCommand(
|
||||
'virsaitis.requestOverride',
|
||||
() => requestOverride()
|
||||
)
|
||||
);
|
||||
|
||||
// Initialize governance interceptor (lazy)
|
||||
const interceptor = new FileInterceptor();
|
||||
context.subscriptions.push(interceptor);
|
||||
|
||||
// Start MCP client connection
|
||||
const mcpClient = new MCPClient();
|
||||
context.subscriptions.push(mcpClient);
|
||||
|
||||
console.log('Virsaitis extension activated');
|
||||
}
|
||||
|
||||
export function deactivate() {
|
||||
console.log('Virsaitis extension deactivated');
|
||||
}
|
||||
```
|
||||
|
||||
### Activation Events
|
||||
|
||||
**RECOMMENDED**:
|
||||
- `onStartupFinished` - Start when VS Code ready (lazy)
|
||||
- `onCommand:virsaitis.*` - Activate on command
|
||||
- NOT `*` - Don't activate on every event (performance)
|
||||
|
||||
**TARGET**: Activation time <200ms
|
||||
|
||||
---
|
||||
|
||||
> ⚡ CHECKPOINT — Does this file operation go through MCP validation first? Extension must not bypass governance.
|
||||
|
||||
## 🛡️ File Operation Interception (TIER-1)
|
||||
|
||||
### Intercept File Save
|
||||
|
||||
```typescript
|
||||
export class FileInterceptor implements vscode.Disposable {
|
||||
private _disposables: vscode.Disposable[] = [];
|
||||
private _mcpClient: MCPClient;
|
||||
|
||||
constructor() {
|
||||
this._mcpClient = new MCPClient();
|
||||
|
||||
// Intercept file save
|
||||
this._disposables.push(
|
||||
vscode.workspace.onWillSaveTextDocument(async (e) => {
|
||||
const validation = await this.validateOperation(
|
||||
'write',
|
||||
e.document.uri.fsPath
|
||||
);
|
||||
|
||||
if (!validation.allowed && validation.tier === 'TIER-0') {
|
||||
// Block save for TIER-0 violation
|
||||
e.waitUntil(this.blockSave(validation));
|
||||
} else if (!validation.allowed && validation.tier === 'TIER-1') {
|
||||
// Warn for TIER-1
|
||||
await this.warnUser(validation);
|
||||
}
|
||||
})
|
||||
);
|
||||
}
|
||||
|
||||
private async validateOperation(
|
||||
operation: string,
|
||||
filePath: string
|
||||
): Promise<ValidationResult> {
|
||||
return await this._mcpClient.validateOperation(operation, filePath);
|
||||
}
|
||||
|
||||
private async blockSave(validation: ValidationResult): Promise<void> {
|
||||
const message = `TIER-0 VIOLATION: ${validation.reason}`;
|
||||
await vscode.window.showErrorMessage(message, { modal: true });
|
||||
throw new Error(message); // Prevents save
|
||||
}
|
||||
|
||||
dispose() {
|
||||
this._disposables.forEach(d => d.dispose());
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎨 UI Components
|
||||
|
||||
### Status Bar Item
|
||||
|
||||
```typescript
|
||||
export class GovernanceStatusBar implements vscode.Disposable {
|
||||
private _statusBarItem: vscode.StatusBarItem;
|
||||
|
||||
constructor() {
|
||||
this._statusBarItem = vscode.window.createStatusBarItem(
|
||||
vscode.StatusBarAlignment.Right,
|
||||
100
|
||||
);
|
||||
this._statusBarItem.command = 'virsaitis.showGovernanceStatus';
|
||||
this.update StatusBarItem.text = '$(shield) Virsaitis: Active';
|
||||
this._statusBarItem.tooltip = 'Governance enforcement active';
|
||||
this._statusBarItem.show();
|
||||
}
|
||||
|
||||
public setStatus(status: 'active' | 'warning' | 'error'): void {
|
||||
switch (status) {
|
||||
case 'active':
|
||||
this._statusBarItem.text = '$(shield) Virsaitis: Active';
|
||||
this._statusBarItem.backgroundColor = undefined;
|
||||
break;
|
||||
case 'warning':
|
||||
this._statusBarItem.text = '$(warning) Virsaitis: Warning';
|
||||
this._statusBarItem.backgroundColor = new vscode.ThemeColor(
|
||||
'statusBarItem.warningBackground'
|
||||
);
|
||||
break;
|
||||
case 'error':
|
||||
this._statusBarItem.text = '$(error) Virsaitis: Error';
|
||||
this._statusBarItem.backgroundColor = new vscode.ThemeColor(
|
||||
'statusBarItem.errorBackground'
|
||||
);
|
||||
break;
|
||||
}
|
||||
}
|
||||
|
||||
dispose() {
|
||||
this._statusBarItem.dispose();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### File Decoration (Shield Icon)
|
||||
|
||||
> ⚡ CHECKPOINT — MCP client uses stdio transport (StdioClientTransport), not HTTP fetch. Verify.
|
||||
|
||||
```typescript
|
||||
export class ShieldDecorator implements vscode.Disposable {
|
||||
private _disposables: vscode.Disposable[] = [];
|
||||
|
||||
constructor() {
|
||||
const decorationType = vscode.window.createTextEditorDecorationType({
|
||||
gutterIconPath: vscode.Uri.file('resources/icons/shield.svg'),
|
||||
gutterIconSize: '80%',
|
||||
});
|
||||
|
||||
// Apply to protected files
|
||||
this._disposables.push(
|
||||
vscode.window.onDidChangeActiveTextEditor(editor => {
|
||||
if (editor && this.isProtectedFile(editor.document.uri)) {
|
||||
const range = new vscode.Range(0, 0, 0, 0);
|
||||
editor.setDecorations(decorationType, [{ range }]);
|
||||
}
|
||||
})
|
||||
);
|
||||
}
|
||||
|
||||
private isProtectedFile(uri: vscode.Uri): boolean {
|
||||
const path = uri.fsPath;
|
||||
const protectedPatterns = [
|
||||
'.github/copilot-instructions.md',
|
||||
'.github/copilot-modules/',
|
||||
'.github/agents/',
|
||||
'virsaitis-development/virsaitis-requirements/',
|
||||
];
|
||||
|
||||
return protectedPatterns.some(pattern => path.includes(pattern));
|
||||
}
|
||||
|
||||
dispose() {
|
||||
this._disposables.forEach(d => d.dispose());
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔌 MCP Client Communication
|
||||
|
||||
Virsaitis MCP uses **stdio transport** (not HTTP). The extension spawns the MCP server as a child process and communicates via stdin/stdout.
|
||||
|
||||
```typescript
|
||||
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
|
||||
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
|
||||
|
||||
export class MCPClient {
|
||||
private _client: Client;
|
||||
private _transport: StdioClientTransport;
|
||||
|
||||
constructor() {
|
||||
const config = vscode.workspace.getConfiguration('virsaitis');
|
||||
const command = config.get<string>('mcpServerCommand', 'node');
|
||||
const args = config.get<string[]>('mcpServerArgs', ['build/index.js']);
|
||||
|
||||
this._transport = new StdioClientTransport({ command, args });
|
||||
this._client = new Client({ name: 'virsaitis-extension', version: '3.0.0' });
|
||||
}
|
||||
|
||||
async connect(): Promise<void> {
|
||||
await this._client.connect(this._transport);
|
||||
}
|
||||
|
||||
async validateOperation(
|
||||
operation: string,
|
||||
filePath: string
|
||||
): Promise<ValidationResult> {
|
||||
try {
|
||||
const result = await this._client.callTool({
|
||||
name: 'validate_operation',
|
||||
arguments: { operation, filePath },
|
||||
});
|
||||
return result.content[0].text as unknown as ValidationResult;
|
||||
} catch (error) {
|
||||
console.error('MCP client error:', error);
|
||||
// Fail open (allow operation if MCP unavailable)
|
||||
return { allowed: true, reason: 'MCP server unavailable' };
|
||||
}
|
||||
}
|
||||
|
||||
async dispose(): Promise<void> {
|
||||
await this._transport.close();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
> ⚡ CHECKPOINT — All UI accessible? Keyboard navigation, focus indicators, WCAG 2.2 AA.
|
||||
|
||||
## 🧪 Testing
|
||||
|
||||
### Extension Test Setup
|
||||
|
||||
```typescript
|
||||
// test/suite/extension.test.ts
|
||||
import * as assert from 'assert';
|
||||
import * as vscode from 'vscode';
|
||||
|
||||
suite('Extension Test Suite', () => {
|
||||
vscode.window.showInformationMessage('Start all tests.');
|
||||
|
||||
test('Extension should activate', async () => {
|
||||
const extension = vscode.extensions.getExtension('virsaitis.virsaitis-extension');
|
||||
assert.ok(extension);
|
||||
await extension.activate();
|
||||
assert.strictEqual(extension.isActive, true);
|
||||
});
|
||||
|
||||
test('Should register commands', async () => {
|
||||
const commands = await vscode.commands.getCommands();
|
||||
assert.ok(commands.includes('virsaitis.requestOverride'));
|
||||
assert.ok(commands.includes('virsaitis.showGovernanceStatus'));
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
### Run Tests
|
||||
|
||||
```bash
|
||||
npm test
|
||||
```
|
||||
|
||||
Tests run in Extension Development Host (isolated VS Code instance).
|
||||
|
||||
---
|
||||
|
||||
## 📦 Packaging & Distribution
|
||||
|
||||
### Build Extension
|
||||
|
||||
```bash
|
||||
# Compile TypeScript + webpack bundle
|
||||
npm run compile
|
||||
|
||||
# Run tests
|
||||
npm test
|
||||
|
||||
# Package extension (.vsix file)
|
||||
vsce package
|
||||
```
|
||||
|
||||
**OUTPUT**: `virsaitis-extension-2.0.0.vsix`
|
||||
|
||||
### Package Size
|
||||
|
||||
**TARGET**: <5MB
|
||||
|
||||
**CHECK**:
|
||||
```bash
|
||||
ls -lh *.vsix
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Key Rules From This Module
|
||||
|
||||
- Extension validates every file operation through MCP before allowing it.
|
||||
- MCP client uses stdio transport via `@modelcontextprotocol/sdk`, not HTTP.
|
||||
- All UI must meet WCAG 2.2 AA. Keyboard navigation mandatory.
|
||||
- Extension must degrade gracefully if MCP server is unavailable.
|
||||
- Definitions: `.github/virsaitis-definition-library.md`
|
||||
|
||||
Return to hub: `.github/copilot-instructions.md`
|
||||
|
||||
**REDUCE SIZE**:
|
||||
- Exclude test files (`.vscodeignore`)
|
||||
- Exclude source maps in production
|
||||
- Minimize dependencies
|
||||
- Use webpack production mode
|
||||
|
||||
### .vscodeignore
|
||||
|
||||
```
|
||||
.vscode/**
|
||||
.gitignore
|
||||
.yarnrc
|
||||
vsc-extension-quickstart.md
|
||||
**/tsconfig.json
|
||||
**/.eslintrc.json
|
||||
**/*.map
|
||||
**/*.ts
|
||||
src/**
|
||||
test/**
|
||||
node_modules/**
|
||||
!node_modules/@modelcontextprotocol/**
|
||||
webpack.config.js
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔧 Configuration
|
||||
|
||||
### Extension Settings
|
||||
|
||||
Users can configure via VS Code settings:
|
||||
|
||||
```json
|
||||
{
|
||||
"virsaitis.enabled": true,
|
||||
"virsaitis.mcpServerCommand": "node",
|
||||
"virsaitis.mcpServerArgs": ["build/index.js"],
|
||||
"virsaitis.showShieldIcons": true,
|
||||
"virsaitis.blockTier0": true
|
||||
}
|
||||
```
|
||||
|
||||
### Reading Configuration
|
||||
|
||||
```typescript
|
||||
const config = vscode.workspace.getConfiguration('virsaitis');
|
||||
const enabled = config.get<boolean>('enabled', true);
|
||||
const mcpCommand = config.get<string>('mcpServerCommand', 'node');
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 💡 Best Practices
|
||||
|
||||
### Disposal Pattern
|
||||
|
||||
Always implement `vscode.Disposable`:
|
||||
|
||||
```typescript
|
||||
export class MyComponent implements vscode.Disposable {
|
||||
private _disposables: vscode.Disposable[] = [];
|
||||
|
||||
constructor() {
|
||||
this._disposables.push(
|
||||
// Register event handlers, commands, etc.
|
||||
);
|
||||
}
|
||||
|
||||
dispose() {
|
||||
this._disposables.forEach(d => d.dispose());
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Error Handling
|
||||
|
||||
```typescript
|
||||
try {
|
||||
await riskyOperation();
|
||||
} catch (error) {
|
||||
// Log for debugging
|
||||
console.error('Operation failed:', error);
|
||||
|
||||
// Show user-friendly message
|
||||
vscode.window.showErrorMessage(
|
||||
'Operation failed. Please check Virsaitis logs.'
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
### Performance
|
||||
|
||||
- Use lazy loading
|
||||
- Debounce frequent events
|
||||
- Cache expensive operations
|
||||
- Minimize synchronous work on activation
|
||||
|
||||
---
|
||||
|
||||
## 📚 Quick Reference
|
||||
|
||||
| Aspect | Standard | Command |
|
||||
|--------|----------|---------|
|
||||
| **Build** | Webpack | `npm run compile` |
|
||||
| **Test** | @vscode/test-electron | `npm test` |
|
||||
| **Package** | vsce | `vsce package` |
|
||||
| **Size** | <5MB | Check .vsix |
|
||||
| **Activation** | <200ms | Lazy load |
|
||||
|
||||
---
|
||||
|
||||
*Extension Standards Module v3.0.0*
|
||||
*VS Code user action interception layer*
|
||||
635
.github/copilot-modules/integration-patterns.md
vendored
Normal file
635
.github/copilot-modules/integration-patterns.md
vendored
Normal file
@@ -0,0 +1,635 @@
|
||||
Three layers enforce governance: Agent (behavior), MCP (validation), Extension (interception). All use stdio transport.
|
||||
|
||||
# Integration Patterns - Virsaitis Layers
|
||||
|
||||
**Module**: Integration Patterns
|
||||
**Load**: When working across multiple components
|
||||
**Version**: 3.0.0
|
||||
**Updated**: 2026-02-17
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Purpose
|
||||
|
||||
Defines integration patterns between Agent, MCP, Extension, and Skills layers for seamless governance enforcement.
|
||||
|
||||
---
|
||||
|
||||
## 🤖 Machine Policy
|
||||
|
||||
```
|
||||
[INTEGRATION_ARCHITECTURE]
|
||||
LAYER_1=agent (behavioral guidance)
|
||||
LAYER_2=mcp_server (validation enforcement)
|
||||
LAYER_3=extension (user action interception)
|
||||
LAYER_4=skills (domain-specific rules)
|
||||
|
||||
[COMMUNICATION_PATTERNS]
|
||||
AGENT_TO_MCP=tool_calls
|
||||
MCP_TO_EXTENSION=stdio
|
||||
AGENT_TO_SKILLS=progressive_disclosure
|
||||
EXTENSION_TO_MCP=validation_requests
|
||||
|
||||
[PRECEDENCE]
|
||||
TIER_0_SOURCE=agent_md (authoritative)
|
||||
TECHNICAL_ENFORCEMENT=mcp + extension
|
||||
DOMAIN_RULES=skills
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🏗️ Three-Layer Architecture
|
||||
|
||||
### Overview
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────┐
|
||||
│ Layer 1: Agent (Atomic Markdown) │ ← AI Self-Regulation
|
||||
│ .github/agents/Virsaitis.agent.md │
|
||||
└──────────────┬──────────────────────┘
|
||||
│ References/Delegates
|
||||
↓
|
||||
┌─────────────────────────────────────┐
|
||||
│ Layer 4: Skills (Native VS Code) │ ← Domain-Specific Rules
|
||||
│ .github/skills/*/SKILL.md │
|
||||
└──────────────┬──────────────────────┘
|
||||
│ Calls MCP Tools
|
||||
↓
|
||||
┌─────────────────────────────────────┐
|
||||
│ Layer 2: MCP Server (TypeScript) │ ← Validation Enforcement
|
||||
│ virsaitis-mcp/ │
|
||||
└──────────────┬──────────────────────┘
|
||||
│ Provides Results
|
||||
↑
|
||||
│ Queries for Validation
|
||||
┌──────────────┴──────────────────────┐
|
||||
│ Layer 3: Extension (TypeScript) │ ← User Action Interception
|
||||
│ virsaitis-extension/ │
|
||||
└─────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔗 Agent ↔ Skills Integration
|
||||
|
||||
### Agent References Skills
|
||||
|
||||
**Agent.md pattern**:
|
||||
```markdown
|
||||
## File Operation Guidelines
|
||||
|
||||
For domain-specific file operations, activate relevant skills:
|
||||
- Python files: Activate python-development skill
|
||||
- Security review: Activate security-controls skill
|
||||
- Requirements: Activate requirements-engineering skill
|
||||
|
||||
Skills provide detailed procedures and validation commands.
|
||||
Agent provides TIER-0 enforcement rules.
|
||||
Skills defer to Agent for conflicts.
|
||||
```
|
||||
|
||||
### Skills Reference Agent
|
||||
|
||||
**SKILL.md pattern**:
|
||||
```markdown
|
||||
---
|
||||
name: python-development
|
||||
description: Python coding standards and file creation workflow
|
||||
metadata:
|
||||
tier: TIER-1
|
||||
---
|
||||
|
||||
## TIER-0 Rules (Enforced by Agent)
|
||||
|
||||
This skill operates under Agent.md TIER-0 rules:
|
||||
- Never use `create_file` for .py files (Agent TIER-0.3)
|
||||
- Never commit secrets (Agent TIER-0.3)
|
||||
- Use MCP tools for governance operations (Agent TIER-0.4)
|
||||
|
||||
**Precedence**: Agent.md TIER-0 > Skill TIER-1 rules
|
||||
|
||||
## TIER-1 Rules (Skill-Specific)
|
||||
|
||||
- 4-space indentation (PEP 8)
|
||||
- UTF-8 encoding without BOM
|
||||
- Black formatter required
|
||||
```
|
||||
|
||||
### Progressive Disclosure
|
||||
|
||||
**VS Code loads in 3 levels**:
|
||||
|
||||
**LEVEL 1: Metadata** (~100 tokens, always loaded):
|
||||
```yaml
|
||||
---
|
||||
name: python-development
|
||||
description: Python coding standards including 4-space indentation...
|
||||
---
|
||||
```
|
||||
|
||||
**LEVEL 2: Instructions** (<5000 tokens, on activation):
|
||||
```markdown
|
||||
## Standards & Rules
|
||||
[Full detailed rules]
|
||||
|
||||
## Procedures
|
||||
[Step-by-step workflows]
|
||||
```
|
||||
|
||||
**LEVEL 3: Resources** (on-demand):
|
||||
```
|
||||
.github/skills/python-development/
|
||||
├── SKILL.md (loaded on activation)
|
||||
├── scripts/ (loaded when referenced)
|
||||
│ └── validate-python.sh
|
||||
└── references/ (loaded when referenced)
|
||||
└── pep8-full-spec.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔌 Agent/Skills → MCP Integration
|
||||
|
||||
### Agent/Skills Call MCP Tools
|
||||
|
||||
**FROM AGENT.MD**:
|
||||
```markdown
|
||||
Before editing protected file:
|
||||
1. Call `mcp_virsaitis_validate_operation` tool
|
||||
2. Pass operation type and file path
|
||||
3. Tool returns validation result
|
||||
4. If not allowed, respond with TIER-0 VIOLATION PREVENTED
|
||||
5. If allowed, proceed with operation
|
||||
```
|
||||
|
||||
**FROM SKILL.MD**:
|
||||
```markdown
|
||||
### Validate File Operation Procedure
|
||||
|
||||
1. Call MCP tool:
|
||||
```
|
||||
mcp_virsaitis_validate_operation({
|
||||
operation: "write",
|
||||
filePath: "/path/to/file.py"
|
||||
})
|
||||
```
|
||||
|
||||
2. Check response:
|
||||
- If `allowed: false` → STOP, show consequences
|
||||
- If `allowed: true` → PROCEED with operation
|
||||
|
||||
3. Log operation in audit trail
|
||||
```
|
||||
|
||||
### MCP Tool Interface
|
||||
|
||||
**TOOL SCHEMA**:
|
||||
```typescript
|
||||
{
|
||||
name: 'mcp_virsaitis_validate_operation',
|
||||
description: 'Validates if an operation is allowed by governance policy',
|
||||
inputSchema: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
operation: {
|
||||
type: 'string',
|
||||
enum: ['read', 'write', 'delete', 'execute'],
|
||||
description: 'Operation type',
|
||||
},
|
||||
filePath: {
|
||||
type: 'string',
|
||||
description: 'Absolute file path',
|
||||
},
|
||||
},
|
||||
required: ['operation', 'filePath'],
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
**TOOL RESPONSE**:
|
||||
|
||||
> ⚡ CHECKPOINT — All layer communication uses stdio transport. No HTTP REST between extension and MCP.
|
||||
|
||||
```typescript
|
||||
interface ValidationResponse {
|
||||
allowed: boolean;
|
||||
tier?: 'TIER-0' | 'TIER-1' | 'TIER-2' | 'TIER-3';
|
||||
reason?: string;
|
||||
consequences?: {
|
||||
operation: string;
|
||||
userImpact: string;
|
||||
technicalImpact: string;
|
||||
businessImpact: string;
|
||||
remediation: string;
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
### Available MCP Tools
|
||||
|
||||
**MCP TOOLS (8 total)**:
|
||||
1. **`mcp_virsaitis_validate_operation`** - Validate file operation against TIER policy
|
||||
2. **`mcp_virsaitis_read_governance`** - Load governance rules from workspace
|
||||
3. **`mcp_virsaitis_reload_cache`** - Refresh in-memory governance rule cache
|
||||
4. **`mcp_virsaitis_scan_secrets`** - Detect hardcoded secrets in content
|
||||
5. **`mcp_virsaitis_validate_path`** - Check path for traversal and boundary violations
|
||||
6. **`mcp_virsaitis_validate_command`** - Whitelist-check commands and escape arguments
|
||||
7. **`mcp_virsaitis_read_audit_log`** - Read recent governance audit log entries
|
||||
8. **`mcp_virsaitis_iteration_complete`** - Post-iteration compliance check (traceability, CHANGELOG, README)
|
||||
|
||||
---
|
||||
|
||||
## 🔧 Extension ↔ MCP Integration
|
||||
|
||||
### Extension Queries MCP
|
||||
|
||||
**FILE SAVE INTERCEPTION**:
|
||||
```typescript
|
||||
// extension/src/governance/file-interceptor.ts
|
||||
export class FileInterceptor {
|
||||
private _mcpClient: MCPClient;
|
||||
|
||||
constructor() {
|
||||
this._mcpClient = new MCPClient();
|
||||
|
||||
vscode.workspace.onWillSaveTextDocument(async (e) => {
|
||||
// Query MCP for validation
|
||||
const validation = await this._mcpClient.validateOperation(
|
||||
'write',
|
||||
e.document.uri.fsPath
|
||||
);
|
||||
|
||||
// Enforce based on TIER
|
||||
if (!validation.allowed && validation.tier === 'TIER-0') {
|
||||
// BLOCK: Prevent save
|
||||
e.waitUntil(this.blockSave(validation));
|
||||
} else if (!validation.allowed && validation.tier === 'TIER-1') {
|
||||
// WARN: Show confirmation dialog
|
||||
await this.warnUser(validation);
|
||||
}
|
||||
});
|
||||
}
|
||||
|
||||
private async blockSave(validation: ValidationResponse): Promise<void> {
|
||||
const message = `TIER-0 VIOLATION: ${validation.reason}\n\n` +
|
||||
`Remediation: ${validation.consequences?.remediation}`;
|
||||
|
||||
await vscode.window.showErrorMessage(message, { modal: true });
|
||||
throw new Error(message); // Prevents save
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### MCP Client Implementation
|
||||
|
||||
**STDIO TRANSPORT CLIENT** (MCP standard — not HTTP):
|
||||
```typescript
|
||||
// extension/src/governance/mcp-client.ts
|
||||
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
|
||||
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
|
||||
|
||||
export class MCPClient {
|
||||
private _client: Client;
|
||||
private _transport: StdioClientTransport;
|
||||
|
||||
constructor() {
|
||||
const config = vscode.workspace.getConfiguration('virsaitis');
|
||||
const command = config.get<string>('mcpServerCommand', 'node');
|
||||
const args = config.get<string[]>('mcpServerArgs', ['build/index.js']);
|
||||
|
||||
this._transport = new StdioClientTransport({ command, args });
|
||||
this._client = new Client({ name: 'virsaitis-extension', version: '3.0.0' });
|
||||
}
|
||||
|
||||
async connect(): Promise<void> {
|
||||
await this._client.connect(this._transport);
|
||||
}
|
||||
|
||||
async validateOperation(
|
||||
operation: string,
|
||||
filePath: string
|
||||
): Promise<ValidationResponse> {
|
||||
try {
|
||||
const result = await this._client.callTool({
|
||||
name: 'validate_operation',
|
||||
arguments: { operation, filePath },
|
||||
});
|
||||
return JSON.parse(result.content[0].text as string);
|
||||
} catch (error) {
|
||||
console.error('MCP client error:', error);
|
||||
|
||||
// Fail-open: Allow operation if MCP unavailable
|
||||
// (Alternative: Fail-closed for stricter enforcement)
|
||||
return {
|
||||
allowed: true,
|
||||
reason: 'MCP server unavailable (fail-open)',
|
||||
};
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎨 Extension UI Integration
|
||||
|
||||
### Shield Icon Decoration
|
||||
|
||||
**PROTECTED FILE INDICATOR**:
|
||||
```typescript
|
||||
// extension/src/ui/shield-decorator.ts
|
||||
export class ShieldDecorator {
|
||||
private _decorationType: vscode.TextEditorDecorationType;
|
||||
|
||||
constructor() {
|
||||
this._decorationType = vscode.window.createTextEditorDecorationType({
|
||||
gutterIconPath: vscode.Uri.file('resources/icons/shield.svg'),
|
||||
gutterIconSize: '80%',
|
||||
});
|
||||
|
||||
// Update on editor change
|
||||
vscode.window.onDidChangeActiveTextEditor(editor => {
|
||||
if (editor && this.isProtectedFile(editor.document.uri)) {
|
||||
this.applyDecoration(editor);
|
||||
}
|
||||
});
|
||||
}
|
||||
|
||||
private isProtectedFile(uri: vscode.Uri): boolean {
|
||||
const protectedPatterns = [
|
||||
'.github/copilot-instructions.md',
|
||||
'.github/copilot-modules/',
|
||||
'.github/agents/',
|
||||
'virsaitis-development/virsaitis-requirements/',
|
||||
];
|
||||
|
||||
return protectedPatterns.some(pattern => uri.fsPath.includes(pattern));
|
||||
}
|
||||
|
||||
private applyDecoration(editor: vscode.TextEditor): void {
|
||||
const range = new vscode.Range(0, 0, 0, 0);
|
||||
editor.setDecorations(this._decorationType, [{ range }]);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Status Bar Integration
|
||||
|
||||
**GOVERNANCE STATUS INDICATOR**:
|
||||
```typescript
|
||||
// extension/src/ui/status-bar.ts
|
||||
export class GovernanceStatusBar {
|
||||
private _statusBarItem: vscode.StatusBarItem;
|
||||
|
||||
constructor() {
|
||||
this._statusBarItem = vscode.window.createStatusBarItem(
|
||||
vscode.StatusBarAlignment.Right,
|
||||
100
|
||||
);
|
||||
this._statusBarItem.command = 'virsaitis.showGovernanceStatus';
|
||||
this._statusBarItem.text = '$(shield) Virsaitis: Active';
|
||||
this._statusBarItem.show();
|
||||
}
|
||||
|
||||
public updateStatus(mcpConnected: boolean): void {
|
||||
if (mcpConnected) {
|
||||
this._statusBarItem.text = '$(shield) Virsaitis: Active';
|
||||
this._statusBarItem.backgroundColor = undefined;
|
||||
} else {
|
||||
this._statusBarItem.text = '$(warning) Virsaitis: MCP Disconnected';
|
||||
this._statusBarItem.backgroundColor = new vscode.ThemeColor(
|
||||
'statusBarItem.warningBackground'
|
||||
);
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📋 MCP → Agent Integration
|
||||
|
||||
### MCP Reads Agent.md
|
||||
|
||||
> ⚡ CHECKPOINT — Three layers enforce governance: Agent (behavior), MCP (validation), Extension (interception). All connected.
|
||||
|
||||
**GOVERNANCE RULES LOADING**:
|
||||
```typescript
|
||||
// mcp/src/governance/rules-loader.ts
|
||||
export class GovernanceRulesLoader {
|
||||
private _agentPath = '.github/agents/Virsaitis.agent.md';
|
||||
|
||||
async loadTierDefinitions(): Promise<TierDefinition[]> {
|
||||
// Read Agent.md
|
||||
const agentContent = await fs.promises.readFile(this._agentPath, 'utf-8');
|
||||
|
||||
// Parse TIER definitions
|
||||
const tiers = this.parseTierSections(agentContent);
|
||||
|
||||
return tiers;
|
||||
}
|
||||
|
||||
private parseTierSections(content: string): TierDefinition[] {
|
||||
// Extract TIER-0, TIER-1, TIER-2, TIER-3 sections
|
||||
const tierPatterns = [
|
||||
/## TIER-0:(.+?)(?=## TIER-1|$)/s,
|
||||
/## TIER-1:(.+?)(?=## TIER-2|$)/s,
|
||||
/## TIER-2:(.+?)(?=## TIER-3|$)/s,
|
||||
/## TIER-3:(.+?)(?=##|$)/s,
|
||||
];
|
||||
|
||||
return tierPatterns.map((pattern, index) => {
|
||||
const match = content.match(pattern);
|
||||
return {
|
||||
tier: `TIER-${index}` as TierLevel,
|
||||
content: match ? match[1].trim() : '',
|
||||
};
|
||||
});
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### MCP Validates Against Agent Rules
|
||||
|
||||
**VALIDATION ENGINE**:
|
||||
```typescript
|
||||
// mcp/src/governance/validator.ts
|
||||
export class GovernanceValidator {
|
||||
private _rules: GovernanceRules;
|
||||
|
||||
constructor() {
|
||||
this._rules = new GovernanceRulesLoader().loadRules();
|
||||
}
|
||||
|
||||
validateFileOperation(operation: string, filePath: string): ValidationResult {
|
||||
// Check TIER-0 protected patterns (from Agent.md)
|
||||
const protectedPatterns = this._rules.tier0.protectedFilePatterns;
|
||||
const isProtected = protectedPatterns.some(pattern =>
|
||||
filePath.includes(pattern)
|
||||
);
|
||||
|
||||
if (isProtected && operation === 'write') {
|
||||
return {
|
||||
allowed: false,
|
||||
tier: 'TIER-0',
|
||||
reason: 'Protected file modification blocked',
|
||||
consequences: this._rules.tier0.consequences,
|
||||
};
|
||||
}
|
||||
|
||||
// Check TIER-1 rules...
|
||||
// Check TIER-2 rules...
|
||||
|
||||
return { allowed: true };
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔄 Data Flow Patterns
|
||||
|
||||
### User Edits Protected File
|
||||
|
||||
```
|
||||
1. USER: Attempts to save .github/copilot-instructions.md
|
||||
↓
|
||||
2. EXTENSION: onWillSaveTextDocument event fires
|
||||
↓
|
||||
3. EXTENSION: Calls MCP validateOperation()
|
||||
↓
|
||||
4. MCP: Loads Agent.md TIER-0 rules
|
||||
↓
|
||||
5. MCP: Checks file against protected patterns
|
||||
↓
|
||||
6. MCP: Returns { allowed: false, tier: 'TIER-0' }
|
||||
↓
|
||||
7. EXTENSION: Blocks save (throw error)
|
||||
↓
|
||||
8. EXTENSION: Shows modal error with consequences
|
||||
↓
|
||||
9. USER: Sees TIER-0 VIOLATION message
|
||||
```
|
||||
|
||||
### AI Generates Code with Secret
|
||||
|
||||
```
|
||||
1. AGENT: About to suggest code with API key
|
||||
↓
|
||||
2. AGENT: Calls mcp_virsaitis_validate_operation (hypothetical)
|
||||
↓
|
||||
3. MCP: Scans code for secret patterns
|
||||
↓
|
||||
4. MCP: Detects API key pattern
|
||||
↓
|
||||
5. MCP: Returns { allowed: false, tier: 'TIER-0', reason: 'Secret detected' }
|
||||
↓
|
||||
6. AGENT: Responds to user: "TIER-0 VIOLATION PREVENTED: Secret detected"
|
||||
↓
|
||||
7. AGENT: Suggests environment variable approach
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ⚖️ Precedence & Conflict Resolution
|
||||
|
||||
### Rule Hierarchy
|
||||
|
||||
```
|
||||
TIER-0 (Agent.md) ────► HIGHEST AUTHORITY
|
||||
↓
|
||||
TIER-1/2/3 (Agent.md) ─► Core Rules
|
||||
↓
|
||||
Skills (TIER-1/2/3) ───► Domain-Specific Rules
|
||||
↓
|
||||
Component Standards ───► Language/Framework Rules
|
||||
```
|
||||
|
||||
### Conflict Resolution
|
||||
|
||||
**IF CONFLICT BETWEEN**:
|
||||
- Agent TIER-0 vs Skill TIER-1 → Agent wins (always)
|
||||
- Agent TIER-1 vs Skill TIER-1 → Agent wins (authoritative)
|
||||
- Skill A TIER-1 vs Skill B TIER-2 → TIER-1 wins (higher priority)
|
||||
- Two skills same TIER → User chooses (ambiguous)
|
||||
|
||||
**EXAMPLE CONFLICT**:
|
||||
```
|
||||
# Agent.md TIER-0
|
||||
Never use create_file for .agent.md files
|
||||
|
||||
# skill.md (hypothetical) TIER-1
|
||||
Use automated tools for file creation
|
||||
|
||||
RESOLUTION: Agent TIER-0 wins (higher precedence)
|
||||
AI MUST: Use manual paste workflow, ignore skill suggestion
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 💡 Best Practices
|
||||
|
||||
### Loose Coupling
|
||||
|
||||
**PREFER**:
|
||||
- Agent → MCP: Tool calls (loose coupling)
|
||||
- Extension → MCP: HTTP API (loose coupling)
|
||||
- Skills → Agent: References only (no dependencies)
|
||||
|
||||
**AVOID**:
|
||||
- Direct file system access across layers
|
||||
- Tight coupling between Agent and Extension
|
||||
- Circular dependencies
|
||||
|
||||
### Fail-Safe Defaults
|
||||
|
||||
**IF MCP UNAVAILABLE**:
|
||||
- Agent: Continue with degraded governance (warn user)
|
||||
- Extension: Fail-open (allow operations) OR Fail-closed (block operations)
|
||||
|
||||
**CHOOSE BASED ON**:
|
||||
- Fail-open: Better UX, lower security
|
||||
- Fail-closed: Better security, worse UX when MCP down
|
||||
|
||||
**VIRSAITIS DEFAULT**: Fail-open for non-TIER-0, fail-closed for TIER-0
|
||||
|
||||
### Audit Logging
|
||||
|
||||
**LOG AT EACH LAYER**:
|
||||
- Agent: Log MCP tool calls
|
||||
- MCP: Log all validation requests
|
||||
- Extension: Log user actions blocked/allowed
|
||||
|
||||
**BENEFITS**:
|
||||
- Troubleshooting integration issues
|
||||
- Compliance audit trail
|
||||
- Performance monitoring
|
||||
|
||||
---
|
||||
|
||||
## 📚 Quick Reference
|
||||
|
||||
| Integration | Pattern | Interface |
|
||||
|-------------|---------|-----------|
|
||||
| **Agent → Skills** | Progressive disclosure | VS Code native loading |
|
||||
| **Agent → MCP** | Tool calls | MCP protocol |
|
||||
| **Skills → MCP** | Tool calls | MCP protocol |
|
||||
| **Extension → MCP** | stdio client | MCP SDK StdioClientTransport |
|
||||
| **MCP → Agent** | File read | Markdown parser |
|
||||
|
||||
---
|
||||
|
||||
*Integration Patterns Module v3.0.0*
|
||||
*Seamless three-layer governance integration*
|
||||
|
||||
---
|
||||
|
||||
## Key Rules From This Module
|
||||
|
||||
- Three layers: Agent (behavioral), MCP (validation), Extension (interception).
|
||||
- All MCP communication uses stdio transport. No HTTP REST endpoints.
|
||||
- Extension calls MCP via StdioClientTransport from @modelcontextprotocol/sdk.
|
||||
- Fail-open by default if MCP unavailable. Document when fail-closed is required.
|
||||
- Definitions: `.github/virsaitis-definition-library.md`
|
||||
|
||||
Return to hub: `.github/copilot-instructions.md`
|
||||
624
.github/copilot-modules/mcp-standards.md
vendored
Normal file
624
.github/copilot-modules/mcp-standards.md
vendored
Normal file
@@ -0,0 +1,624 @@
|
||||
All MCP tools use stdio transport. Every tool validates input with Zod before processing.
|
||||
|
||||
# MCP Standards - Layer 2
|
||||
|
||||
**Module**: MCP Standards
|
||||
**Component**: Layer 2 (Model Context Protocol Server)
|
||||
**Load**: When working on virsaitis-development/virsaitis-mcp/
|
||||
**Version**: 3.0.0
|
||||
**Updated**: 2026-04-20
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Purpose
|
||||
|
||||
Defines TypeScript standards, MCP SDK usage, and development workflow for Virsaitis MCP Server (Layer 2 governance enforcement).
|
||||
|
||||
---
|
||||
|
||||
## 🤖 Machine Policy
|
||||
|
||||
```
|
||||
[TECHNOLOGY_STACK]
|
||||
LANGUAGE=TypeScript 5.0+
|
||||
RUNTIME=Node.js 18+
|
||||
FRAMEWORK=@modelcontextprotocol/sdk
|
||||
BUILD=tsc + esbuild
|
||||
TEST=vitest
|
||||
LINT=eslint + prettier
|
||||
|
||||
[CODE_STANDARDS]
|
||||
INDENTATION=2_spaces
|
||||
LINE_LENGTH=100_chars
|
||||
QUOTES=single
|
||||
SEMICOLONS=required
|
||||
TRAILING_COMMAS=required_multiline
|
||||
|
||||
[QUALITY_GATES]
|
||||
BUILD=must_succeed
|
||||
TESTS=must_pass
|
||||
LINT=zero_errors
|
||||
TYPE_CHECK=strict_mode
|
||||
COVERAGE=70_percent_min
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📐 TypeScript Standards (TIER-1)
|
||||
|
||||
### Indentation & Formatting
|
||||
|
||||
**REQUIRED**:
|
||||
- **Indentation**: 2 spaces (not 4, not tabs)
|
||||
- **Line length**: 100 characters maximum
|
||||
- **Quotes**: Single quotes `'string'` for strings
|
||||
- **Semicolons**: Required at end of statements
|
||||
- **Trailing commas**: Required for multiline arrays/objects
|
||||
|
||||
✅ **GOOD**:
|
||||
```typescript
|
||||
const config = {
|
||||
server: 'virsaitis-mcp',
|
||||
port: 3000,
|
||||
enabled: true,
|
||||
};
|
||||
```
|
||||
|
||||
❌ **BAD**:
|
||||
```typescript
|
||||
const config = {
|
||||
server: "virsaitis-mcp",
|
||||
port: 3000,
|
||||
enabled: true
|
||||
} // Missing trailing comma, 4 spaces, double quotes
|
||||
```
|
||||
|
||||
### File Organization
|
||||
|
||||
**STANDARD ORDER**:
|
||||
```typescript
|
||||
// 1. External imports (Node.js, npm packages)
|
||||
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
|
||||
import * as fs from 'fs';
|
||||
|
||||
// 2. Internal imports (project files)
|
||||
import { GovernanceValidator } from './governance/validator.js';
|
||||
import { PolicyEngine } from './policy/engine.js';
|
||||
|
||||
// 3. Type definitions
|
||||
interface ValidationResult {
|
||||
allowed: boolean;
|
||||
reason?: string;
|
||||
}
|
||||
|
||||
// 4. Constants
|
||||
const PROTECTED_PATTERNS = [
|
||||
'.github/copilot-instructions.md',
|
||||
'requirements/**',
|
||||
];
|
||||
|
||||
// 5. Class/function implementations
|
||||
export class VirsaitisMCPServer {
|
||||
// Implementation
|
||||
}
|
||||
```
|
||||
|
||||
### Naming Conventions (TIER-1)
|
||||
|
||||
| Element | Convention | Example |
|
||||
|---------|------------|---------|
|
||||
| **Classes** | PascalCase | `GovernancePolicyValidator` |
|
||||
| **Interfaces** | PascalCase | `PolicyResult` or `IPolicyResult` |
|
||||
| **Types** | PascalCase | `OperationType` |
|
||||
| **Functions** | camelCase | `validateFileOperation` |
|
||||
| **Methods** | camelCase | `checkPermissions` |
|
||||
| **Variables** | camelCase | `isValid`, `fileName` |
|
||||
| **Constants** | UPPER_SNAKE_CASE | `MAX_RETRIES`, `PROTECTED_PATTERNS` |
|
||||
| **Private members** | Leading underscore | `_config`, `_cache` |
|
||||
| **Enums**| PascalCase | `TierLevel` |
|
||||
| **Enum values** | PascalCase | `TierLevel.Critical` |
|
||||
|
||||
---
|
||||
|
||||
## 🔧 MCP Server Architecture
|
||||
|
||||
### Server Structure
|
||||
|
||||
```
|
||||
virsaitis-development/virsaitis-mcp/
|
||||
├── src/
|
||||
│ ├── index.ts (server entry point)
|
||||
│ ├── server.ts (MCP server class)
|
||||
│ ├── governance/
|
||||
│ │ ├── types.ts (TierLevel, GovernanceRule, ValidationResult)
|
||||
│ │ ├── patterns.ts (glob pattern matching)
|
||||
│ │ ├── cache.ts (in-memory governance cache)
|
||||
│ │ ├── loader.ts (parse core-policies.md + agent files)
|
||||
│ │ └── validator.ts (GovernanceValidator - TIER validation)
|
||||
│ ├── config.ts (server configuration - REQ-MCP-010)
|
||||
│ ├── tools/
|
||||
│ │ ├── scan-secrets.ts (mcp_virsaitis_scan_secrets)
|
||||
│ │ ├── validate-path.ts (mcp_virsaitis_validate_path)
|
||||
│ │ ├── validate-command.ts (mcp_virsaitis_validate_command)
|
||||
│ │ ├── audit-logger.ts (mcp_virsaitis_read_audit_log)
|
||||
│ │ └── iteration-complete.ts (mcp_virsaitis_iteration_complete)
|
||||
├── tests/
|
||||
│ ├── unit/
|
||||
│ ├── integration/
|
||||
│ └── fixtures/
|
||||
├── build/ (compiled output)
|
||||
├── package.json
|
||||
├── tsconfig.json
|
||||
├── vitest.config.ts
|
||||
└── README.md
|
||||
```
|
||||
|
||||
### MCP Tools Implementation
|
||||
|
||||
**TOOL PATTERN**:
|
||||
```typescript
|
||||
// Tool definition
|
||||
server.setRequestHandler(ToolsListRequestSchema, async () => {
|
||||
return {
|
||||
tools: [
|
||||
{
|
||||
name: 'mcp_virsaitis_validate_operation',
|
||||
description: 'Validates if an operation is allowed by governance policy',
|
||||
inputSchema: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
operation: {
|
||||
type: 'string',
|
||||
description: 'Operation type: read, write, delete, execute',
|
||||
},
|
||||
filePath: {
|
||||
type: 'string',
|
||||
description: 'Absolute file path',
|
||||
},
|
||||
},
|
||||
required: ['operation', 'filePath'],
|
||||
},
|
||||
},
|
||||
],
|
||||
};
|
||||
});
|
||||
|
||||
// Tool execution
|
||||
server.setRequestHandler(ToolCallRequestSchema, async (request) => {
|
||||
if (request.params.name === 'mcp_virsaitis_validate_operation') {
|
||||
const { operation, filePath } = request.params.arguments;
|
||||
|
||||
// Validation logic
|
||||
const result = await governanceValidator.validate(operation, filePath);
|
||||
|
||||
return {
|
||||
content: [
|
||||
{
|
||||
type: 'text',
|
||||
text: JSON.stringify(result, null, 2),
|
||||
},
|
||||
],
|
||||
};
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
> ⚡ CHECKPOINT — Is this MCP tool using Zod input validation? Every tool parameter must have a schema.
|
||||
|
||||
## ✅ Type Safety (TIER-1)
|
||||
|
||||
### TypeScript Configuration
|
||||
|
||||
**tsconfig.json REQUIREMENTS**:
|
||||
```json
|
||||
{
|
||||
"compilerOptions": {
|
||||
"target": "ES2022",
|
||||
"module": "ES2022",
|
||||
"moduleResolution": "node",
|
||||
"strict": true,
|
||||
"esModuleInterop": true,
|
||||
"skipLibCheck": false,
|
||||
"forceConsistentCasingInFileNames": true,
|
||||
"declaration": true,
|
||||
"declarationMap": true,
|
||||
"sourceMap": true,
|
||||
"outDir": "./build",
|
||||
"rootDir": "./src"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**STRICT MODE REQUIRED**:
|
||||
- `strict: true` (enables all strict checks)
|
||||
- `noImplicitAny: true` (no implicit any types)
|
||||
- `strictNullChecks: true` (null/undefined handling)
|
||||
- `strictFunctionTypes: true` (function type checking)
|
||||
- `strictPropertyInitialization: true` (class property init)
|
||||
|
||||
### Explicit Type Annotations
|
||||
|
||||
**REQUIRED FOR**:
|
||||
- Public function return types
|
||||
- Public method return types
|
||||
- Exported interfaces/types
|
||||
- Complex function parameters
|
||||
|
||||
✅ **GOOD**:
|
||||
```typescript
|
||||
export function validateTier(tier: string): boolean {
|
||||
return ['TIER-0', 'TIER-1', 'TIER-2', 'TIER-3'].includes(tier);
|
||||
}
|
||||
|
||||
export interface PolicyResult {
|
||||
allowed: boolean;
|
||||
tier: string;
|
||||
reason?: string;
|
||||
consequences?: Consequence[];
|
||||
}
|
||||
```
|
||||
|
||||
❌ **BAD**:
|
||||
```typescript
|
||||
export function validateTier(tier) { // Missing parameter type
|
||||
return ['TIER-0', 'TIER-1', 'TIER-2', 'TIER-3'].includes(tier);
|
||||
} // Missing return type
|
||||
|
||||
export interface PolicyResult {
|
||||
allowed; // Missing type
|
||||
tier; // Missing type
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🧪 Testing Standards (TIER-1)
|
||||
|
||||
### Test Framework
|
||||
|
||||
**USING**: Vitest (fast, TypeScript-native)
|
||||
|
||||
**vitest.config.ts**:
|
||||
```typescript
|
||||
import { defineConfig } from 'vitest/config';
|
||||
|
||||
export default defineConfig({
|
||||
test: {
|
||||
coverage: {
|
||||
provider: 'v8',
|
||||
reporter: ['text', 'html', 'lcov'],
|
||||
lines: 70,
|
||||
functions: 70,
|
||||
branches: 70,
|
||||
statements: 70,
|
||||
},
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
### Test Structure
|
||||
|
||||
**PATTERN**:
|
||||
```typescript
|
||||
import { describe, it, expect, beforeEach } from 'vitest';
|
||||
import { GovernanceValidator } from '../src/governance/validator';
|
||||
|
||||
describe('GovernanceValidator', () => {
|
||||
let validator: GovernanceValidator;
|
||||
|
||||
beforeEach(() => {
|
||||
validator = new GovernanceValidator();
|
||||
});
|
||||
|
||||
describe('validateFileOperation', () => {
|
||||
it('should block protected file modification', () => {
|
||||
// Given
|
||||
const operation = 'write';
|
||||
const filePath = '.github/copilot-instructions.md';
|
||||
|
||||
// When
|
||||
const result = validator.validateFileOperation(operation, filePath);
|
||||
|
||||
// Then
|
||||
expect(result.allowed).toBe(false);
|
||||
expect(result.tier).toBe('TIER-0');
|
||||
expect(result.reason).toContain('protected file');
|
||||
});
|
||||
|
||||
it('should allow non-protected file modification', () => {
|
||||
// Given
|
||||
const operation = 'write';
|
||||
const filePath = 'src/my-file.ts';
|
||||
|
||||
// When
|
||||
const result = validator.validateFileOperation(operation, filePath);
|
||||
|
||||
// Then
|
||||
expect(result.allowed).toBe(true);
|
||||
});
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
### Test Coverage Requirements
|
||||
|
||||
**MINIMUM COVERAGE**:
|
||||
- Overall: 70%
|
||||
- Security-critical code: 100%
|
||||
- Governance validation: 100%
|
||||
- Consequence evaluation: 100%
|
||||
- Tool implementations: 90%
|
||||
- Utilities: 70%
|
||||
|
||||
**MEASURE**:
|
||||
```bash
|
||||
npm run test:coverage
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔒 Security Standards
|
||||
|
||||
### Input Validation
|
||||
|
||||
**ALWAYS VALIDATE**:
|
||||
```typescript
|
||||
function validateFilePath(filePath: string): string {
|
||||
// Check for null/undefined
|
||||
if (!filePath) {
|
||||
throw new Error('File path is required');
|
||||
}
|
||||
|
||||
// Check for path traversal
|
||||
if (filePath.includes('..')) {
|
||||
throw new Error('Path traversal detected');
|
||||
}
|
||||
|
||||
// Normalize path
|
||||
const normalized = path.normalize(filePath);
|
||||
|
||||
// Ensure absolute path
|
||||
if (!path.isAbsolute(normalized)) {
|
||||
throw new Error('Absolute path required');
|
||||
}
|
||||
|
||||
return normalized;
|
||||
}
|
||||
```\n\n> \u26a1 CHECKPOINT \u2014 MCP uses stdio transport only. If you see HTTP fetch or REST endpoints, that code is wrong.\n\n### Error Handling", "oldString": "```\n\n### Error Handling
|
||||
- Internal file paths in error messages
|
||||
- Sensitive configuration
|
||||
- Stack traces to external systems
|
||||
- Credentials or secrets
|
||||
|
||||
✅ **GOOD**:
|
||||
```typescript
|
||||
try {
|
||||
await fs.promises.readFile(filePath);
|
||||
} catch (error) {
|
||||
// Log full error internally
|
||||
logger.error('File read failed', { filePath, error });
|
||||
|
||||
// Return sanitized error to user
|
||||
return {
|
||||
success: false,
|
||||
message: 'Unable to read file',
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
❌ **BAD**:
|
||||
```typescript
|
||||
try {
|
||||
await fs.promises.readFile(filePath);
|
||||
} catch (error) {
|
||||
// Exposes internal path
|
||||
return {
|
||||
success: false,
|
||||
message: `Failed to read ${filePath}: ${error.message}`,
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔄 Build & Development Workflow
|
||||
|
||||
### Development Commands
|
||||
|
||||
```bash
|
||||
# Install dependencies
|
||||
npm install
|
||||
|
||||
# Start development with file watching
|
||||
npm run dev
|
||||
|
||||
# Build TypeScript
|
||||
npm run build
|
||||
|
||||
# Run tests
|
||||
npm test
|
||||
|
||||
# Run tests with coverage
|
||||
npm run test:coverage
|
||||
|
||||
# Run linter
|
||||
npm run lint
|
||||
|
||||
# Fix linting issues
|
||||
npm run lint:fix
|
||||
|
||||
# TypeScript type checking
|
||||
npm run type-check
|
||||
|
||||
# Format code
|
||||
npm run format
|
||||
```
|
||||
|
||||
### Before Commit Checklist (TIER-1)
|
||||
|
||||
**ALL MUST PASS**:
|
||||
```bash
|
||||
npm run build # ✅ Must succeed
|
||||
npm test # ✅ Must pass (all tests)
|
||||
npm run lint # ✅ Zero errors
|
||||
npm run type-check # ✅ No type errors
|
||||
npm run test:coverage # ✅ Coverage ≥70%
|
||||
```
|
||||
|
||||
**IF ANY FAIL**: Fix before committing
|
||||
|
||||
---
|
||||
|
||||
## 📦 MCP Server Packaging
|
||||
|
||||
### Build Output
|
||||
|
||||
**COMPILED TO**: `build/` directory
|
||||
|
||||
**INCLUDES**:
|
||||
- `build/index.js` (entry point)
|
||||
- `build/**/*.js` (compiled TypeScript)
|
||||
- `build/**/*.d.ts` (type definitions)
|
||||
- `build/**/*.js.map` (source maps)
|
||||
|
||||
### NPM Package
|
||||
|
||||
**package.json ESSENTIALS**:
|
||||
```json
|
||||
{
|
||||
"name": "@virsaitis/mcp-server",
|
||||
"version": "2.0.0",
|
||||
"type": "module",
|
||||
"main": "./build/index.js",
|
||||
"types": "./build/index.d.ts",
|
||||
"bin": {
|
||||
"virsaitis-mcp": "./build/index.js"
|
||||
},
|
||||
"engines": {
|
||||
|
||||
---
|
||||
|
||||
## Key Rules From This Module
|
||||
|
||||
- stdio transport only. No HTTP REST endpoints for MCP communication.
|
||||
- Every tool input validated with Zod schemas before processing.
|
||||
- TypeScript strict mode. No `any` types without documented justification.
|
||||
- All dependencies must be in DEPENDENCY-REGISTER.md before use.
|
||||
- Definitions: `.github/virsaitis-definition-library.md`
|
||||
|
||||
Return to hub: `.github/copilot-instructions.md`
|
||||
"node": ">=18.0.0"
|
||||
},
|
||||
"scripts": {
|
||||
"build": "tsc && esbuild",
|
||||
"test": "vitest run",
|
||||
"test:coverage": "vitest run --coverage",
|
||||
"lint": "eslint src/",
|
||||
"type-check": "tsc --noEmit"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
> ⚡ CHECKPOINT — All dependencies approved? Check virsaitis-mcp/DEPENDENCY-REGISTER.md before adding packages.
|
||||
|
||||
## 🔗 Integration with Agent & Extension
|
||||
|
||||
### Agent → MCP Communication
|
||||
|
||||
**Agent calls MCP tools**:
|
||||
```markdown
|
||||
[Agent.md instruction]
|
||||
Before editing protected file, call mcp_virsaitis_validate_operation tool.
|
||||
Tool returns whether operation allowed.
|
||||
If not allowed, respond with TIER-0 VIOLATION PREVENTED.
|
||||
```
|
||||
|
||||
**MCP response format**:
|
||||
```typescript
|
||||
interface ValidationResponse {
|
||||
allowed: boolean;
|
||||
tier: 'TIER-0' | 'TIER-1' | 'TIER-2' | 'TIER-3';
|
||||
reason?: string;
|
||||
consequences?: {
|
||||
operation: string;
|
||||
userImpact: string;
|
||||
technicalImpact: string;
|
||||
businessImpact: string;
|
||||
remediation: string;
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
### MCP ← Extension Communication
|
||||
|
||||
**Extension queries MCP**:
|
||||
- User tries to edit file
|
||||
- Extension calls mcp_virsaitis_validate_operation
|
||||
- MCP validates against governance
|
||||
- Extension shows 🛡️ shield if protected
|
||||
- Extension blocks action if TIER-0
|
||||
|
||||
---
|
||||
|
||||
## 💡 Best Practices
|
||||
|
||||
### Code Organization
|
||||
|
||||
**ONE CONCERN PER FILE**:
|
||||
- Each file handles one specific responsibility
|
||||
- Validators in `governance/`
|
||||
- Tools in `tools/`
|
||||
- Utilities in `utils/`
|
||||
|
||||
**SMALL FUNCTIONS**:
|
||||
- Keep functions <50 lines
|
||||
- Single responsibility
|
||||
- Testable in isolation
|
||||
|
||||
**AVOID GOD CLASSES**:
|
||||
- Break large classes into smaller components
|
||||
- Use composition over inheritance
|
||||
- Inject dependencies
|
||||
|
||||
### Performance
|
||||
|
||||
**CACHING**:
|
||||
```typescript
|
||||
class GovernanceCache {
|
||||
private _rulesCache: Map<string, Rule[]> = new Map();
|
||||
private _cacheExpiry = 5 * 60 * 1000; // 5 minutes
|
||||
|
||||
async getRules(category: string): Promise<Rule[]> {
|
||||
const cached = this._rulesCache.get(category);
|
||||
if (cached && !this.isExpired(cached)) {
|
||||
return cached;
|
||||
}
|
||||
|
||||
const rules = await this.loadRules(category);
|
||||
this._rulesCache.set(category, rules);
|
||||
return rules;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📚 Quick Reference
|
||||
|
||||
| Aspect | Standard | Command |
|
||||
|--------|----------|---------|
|
||||
| **Indentation** | 2 spaces | ESLint enforces |
|
||||
| **Build** | `tsc` + `esbuild` | `npm run build` |
|
||||
| **Test** | Vitest | `npm test` |
|
||||
| **Coverage** | ≥70% | `npm run test:coverage` |
|
||||
| **Lint** | ESLint + Prettier | `npm run lint` |
|
||||
| **Type Check** | TypeScript strict | `npm run type-check` |
|
||||
|
||||
---
|
||||
|
||||
*MCP Standards Module v3.0.0*
|
||||
*TypeScript governance enforcement server*
|
||||
531
.github/copilot-modules/requirements-engineering.md
vendored
Normal file
531
.github/copilot-modules/requirements-engineering.md
vendored
Normal file
@@ -0,0 +1,531 @@
|
||||
Every functional change needs a REQ-ID. Search virsaitis-requirements/ first. Do not invent requirements.
|
||||
|
||||
# Requirements Engineering - Virsaitis
|
||||
|
||||
**Module**: Requirements Engineering
|
||||
**Load**: When implementing features, updating traceability
|
||||
**Version**: 3.0.0
|
||||
**Updated**: 2026-02-17
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Purpose
|
||||
|
||||
Defines REQ-ID format, traceability management, and requirement lifecycle for all Virsaitis development.
|
||||
|
||||
---
|
||||
|
||||
## 🤖 Machine Policy
|
||||
|
||||
```
|
||||
[REQ_ID_FORMAT]
|
||||
PATTERN=^REQ-[A-Z]{2,4}-[0-9]{3}$
|
||||
INVENTION=prohibited
|
||||
VALIDATION=mandatory
|
||||
TRACEABILITY=required
|
||||
|
||||
[LIFECYCLE]
|
||||
CREATE_REQUIREMENT → IMPLEMENT → TEST → TRACE → VERIFY
|
||||
|
||||
[TRACEABILITY]
|
||||
CSV_FILE=virsaitis-development/virsaitis-requirements/traceability.csv
|
||||
UPDATE_ON_IMPLEMENTATION=required
|
||||
UPDATE_ON_TEST_CREATION=required
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📋 REQ-ID Format (TIER-1)
|
||||
|
||||
### Structure
|
||||
|
||||
**PATTERN**: `REQ-[CATEGORY]-[NUMBER]`
|
||||
|
||||
**REGEX**: `^REQ-[A-Z]{2,4}-[0-9]{3}$`
|
||||
|
||||
**EXAMPLES**:
|
||||
- `REQ-GOV-001` - Governance Core requirement #1
|
||||
- `REQ-SEC-015` - Security Controls requirement #15
|
||||
- `REQ-MCP-003` - MCP Server feature #3
|
||||
|
||||
### Categories
|
||||
|
||||
| Category | Code | Purpose | Example |
|
||||
|----------|------|---------|---------|
|
||||
| **Governance** | GOV | Core governance rules | REQ-GOV-001 |
|
||||
| **Security** | SEC | Security controls | REQ-SEC-012 |
|
||||
| **MCP** | MCP | MCP Server features | REQ-MCP-005 |
|
||||
| **Extension** | EXT | Extension features | REQ-EXT-008 |
|
||||
| **Agent** | AGT | Agent capabilities | REQ-AGT-004 |
|
||||
| **Skills** | SKL | Agent Skills | REQ-SKL-002 |
|
||||
| **Testing** | TEST | Testing requirements | REQ-TEST-007 |
|
||||
| **NFR** | NFR | Non-Functional | REQ-NFR-010 |
|
||||
|
||||
### Number Assignment
|
||||
|
||||
**FORMAT**: 3 digits with leading zeros
|
||||
|
||||
✅ **GOOD**:
|
||||
- `REQ-GOV-001`
|
||||
- `REQ-GOV-010`
|
||||
- `REQ-GOV-100`
|
||||
|
||||
❌ **BAD**:
|
||||
- `REQ-GOV-1` (missing leading zeros)
|
||||
- `REQ-GOV-1000` (too many digits, split category)
|
||||
|
||||
### Never Invent REQ-IDs
|
||||
|
||||
**RULE**: AI must NEVER create REQ-IDs
|
||||
|
||||
**WHY**:
|
||||
- REQ-IDs managed by humans
|
||||
- Traceability requires authority
|
||||
- Invented IDs create confusion
|
||||
- Audit trail must be accurate
|
||||
|
||||
**IF NO REQ-ID EXISTS**:
|
||||
```
|
||||
RESPONSE: "REQUIREMENT_NOT_FOUND: No REQ-ID for this feature"
|
||||
|
||||
STOP: Do not invent REQ-ID
|
||||
REQUEST: User create requirement first
|
||||
SUGGEST: Check virsaitis-development/virsaitis-requirements/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📂 Requirements Structure
|
||||
|
||||
### Directory Organization
|
||||
|
||||
```
|
||||
virsaitis-development/virsaitis-requirements/
|
||||
├── index.md (requirements overview)
|
||||
├── functional-spec.md (functional requirements)
|
||||
├── nonfunctional-spec.md (NFRs)
|
||||
├── security-controls.md (security requirements)
|
||||
├── testing-requirements.md (test requirements)
|
||||
├── glossary.md (terminology)
|
||||
├── assumptions.md (assumptions log)
|
||||
├── risk-register.md (risks and mitigations)
|
||||
├── traceability.csv (REQ-ID → Implementation mapping)
|
||||
└── archive/ (deprecated requirements)
|
||||
```
|
||||
|
||||
### Requirement Document Format
|
||||
|
||||
**STRUCTURE**:
|
||||
```markdown
|
||||
## REQ-GOV-001: Protected File Modification
|
||||
|
||||
**Priority**: TIER-0 (Safety-Critical)
|
||||
**Category**: Governance
|
||||
**Status**: Approved
|
||||
**Created**: 2026-02-17
|
||||
**Updated**: 2026-02-17
|
||||
|
||||
### Description
|
||||
|
||||
The system MUST prevent modification of protected files without explicit approval.
|
||||
|
||||
Protected files include:
|
||||
- `.github/copilot-instructions.md`
|
||||
- `.github/copilot-modules/**/*.md`
|
||||
- `.github/agents/Virsaitis.agent.md`
|
||||
- `virsaitis-development/virsaitis-requirements/**`
|
||||
|
||||
### Rationale
|
||||
|
||||
Protected files control governance enforcement.
|
||||
Unauthorized modification bypasses all safety controls.
|
||||
Preventing modification maintains system integrity.
|
||||
|
||||
### Acceptance Criteria
|
||||
|
||||
1. GIVEN protected file modification attempted
|
||||
WHEN governance validation runs
|
||||
THEN operation is BLOCKED
|
||||
|
||||
2. GIVEN non-protected file modification
|
||||
WHEN governance validation runs
|
||||
THEN operation is ALLOWED
|
||||
|
||||
3. GIVEN protected file modification with override token
|
||||
WHEN governance validation runs
|
||||
THEN operation is ALLOWED with audit log
|
||||
|
||||
### Dependencies
|
||||
|
||||
- REQ-GOV-002 (TIER Definition)
|
||||
- REQ-MCP-005 (File Validation Tool)
|
||||
|
||||
### Implementation Reference
|
||||
|
||||
- `virsaitis-mcp/src/governance/validator.ts`
|
||||
- `virsaitis-extension/src/governance/file-interceptor.ts`
|
||||
|
||||
### Test Reference
|
||||
|
||||
- `virsaitis-mcp/tests/governance/validator.test.ts`
|
||||
- `virsaitis-extension/test/suite/governance.test.ts`
|
||||
|
||||
### Verification
|
||||
|
||||
```bash
|
||||
# Test protected file modification
|
||||
npm test -- --grep "should block protected file"
|
||||
```
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔗 Traceability Management (TIER-1)
|
||||
|
||||
### traceability.csv Format
|
||||
|
||||
**COLUMNS**:
|
||||
```csv
|
||||
REQ_ID,Description,Priority,ImplementationRef,TestRef,Status
|
||||
REQ-GOV-001,"Protected file modification",TIER-0,"mcp/src/governance/validator.ts#L45","mcp/tests/governance/validator.test.ts#L12",Implemented
|
||||
REQ-SEC-012,"Secret scanning",TIER-0,"mcp/src/security/scanner.ts#L23,extension/src/commands/scan.ts#L10","mcp/tests/security/scanner.test.ts#L8",Implemented
|
||||
REQ-MCP-005,"File validation tool",TIER-1,"mcp/src/tools/validate-operation.ts#L15","mcp/tests/tools/validate-operation.test.ts#L5",Implemented
|
||||
```
|
||||
|
||||
**FIELDS**:
|
||||
- **REQ_ID**: Requirement identifier
|
||||
- **Description**: Short requirement description (50 chars max)
|
||||
- **Priority**: TIER-0, TIER-1, TIER-2, or TIER-3
|
||||
- **ImplementationRef**: File paths with line numbers (comma-separated)
|
||||
- **TestRef**: Test file paths with line numbers (comma-separated)
|
||||
- **Status**: Draft, Approved, Implemented, Verified, Deprecated
|
||||
|
||||
### Update Traceability
|
||||
|
||||
**WHEN TO UPDATE**:
|
||||
1. Requirement implemented → Add ImplementationRef
|
||||
2. Tests written → Add TestRef
|
||||
3. Requirement status changes → Update Status
|
||||
4. Implementation moved → Update ImplementationRef
|
||||
|
||||
**HOW TO UPDATE**:
|
||||
```bash
|
||||
# 1. Read current traceability.csv
|
||||
cat virsaitis-development/virsaitis-requirements/traceability.csv
|
||||
|
||||
# 2. Find REQ-ID row
|
||||
|
||||
# 3. Update ImplementationRef column
|
||||
# Example: "mcp/src/governance/validator.ts#L45"
|
||||
|
||||
# 4. Update TestRef column
|
||||
# Example: "mcp/tests/governance/validator.test.ts#L12"
|
||||
|
||||
# 5. Update Status column
|
||||
# Example: "Implemented"
|
||||
|
||||
# 6. Save file
|
||||
|
||||
# 7. Commit with message referencing REQ-ID
|
||||
git commit -m "feat(mcp): Implement file validation
|
||||
|
||||
Implements: REQ-MCP-005"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔄 Requirement Lifecycle
|
||||
|
||||
### Lifecycle States
|
||||
|
||||
```
|
||||
DRAFT → REVIEW → APPROVED → IMPLEMENTED → VERIFIED → (DEPRECATED)
|
||||
```
|
||||
|
||||
**DRAFT**:
|
||||
- Initial creation
|
||||
- Under discussion
|
||||
- May change significantly
|
||||
|
||||
**REVIEW**:
|
||||
- Ready for stakeholder review
|
||||
- Acceptance criteria defined
|
||||
- Dependencies identified
|
||||
|
||||
**APPROVED**:
|
||||
- Approved for implementation
|
||||
- REQ-ID assigned officially
|
||||
- Added to traceability.csv
|
||||
|
||||
> ⚡ CHECKPOINT — Does this requirement have acceptance criteria? Use Given-When-Then format.
|
||||
|
||||
**IMPLEMENTED**:
|
||||
- Code written
|
||||
- ImplementationRef updated in traceability.csv
|
||||
- Not yet tested
|
||||
|
||||
**VERIFIED**:
|
||||
- Tests written and passing
|
||||
- TestRef updated in traceability.csv
|
||||
- Ready for release
|
||||
|
||||
**DEPRECATED**:
|
||||
- No longer applicable
|
||||
- Moved to archive/
|
||||
- Marked in traceability.csv
|
||||
|
||||
### State Transitions
|
||||
|
||||
**DRAFT → APPROVED**:
|
||||
- Stakeholder approval obtained
|
||||
- REQ-ID assigned
|
||||
- Acceptance criteria complete
|
||||
|
||||
**APPROVED → IMPLEMENTED**:
|
||||
- Code committed
|
||||
- traceability.csv updated
|
||||
- CHANGELOG updated
|
||||
|
||||
**IMPLEMENTED → VERIFIED**:
|
||||
- Tests passing
|
||||
- Coverage sufficient
|
||||
- traceability.csv updated
|
||||
|
||||
---
|
||||
|
||||
## 📝 Before Implementing Feature
|
||||
|
||||
### Discovery Workflow
|
||||
|
||||
```
|
||||
1. USER REQUEST: "Add feature X"
|
||||
↓
|
||||
2. SEARCH: virsaitis-development/virsaitis-requirements/
|
||||
↓
|
||||
3. FIND: Relevant REQ-ID (e.g., REQ-MCP-005)
|
||||
↓
|
||||
4. VALIDATE: REQ-ID format matches regex
|
||||
↓
|
||||
5. READ: Full requirement document
|
||||
↓
|
||||
6. UNDERSTAND: Acceptance criteria
|
||||
↓
|
||||
7. PLAN: Implementation approach
|
||||
↓
|
||||
8. IMPLEMENT: Write code
|
||||
↓
|
||||
9. TEST: Write tests matching acceptance criteria
|
||||
↓
|
||||
10. UPDATE: traceability.csv (ImplementationRef, TestRef)
|
||||
↓
|
||||
11. COMMIT: Message includes "Implements: REQ-XXX-YYY"
|
||||
```
|
||||
|
||||
### If No REQ-ID Found
|
||||
|
||||
**RESPONSE PATTERN**:
|
||||
```
|
||||
REQUIREMENT_NOT_FOUND
|
||||
|
||||
SEARCHED: virsaitis-development/virsaitis-requirements/
|
||||
QUERY: [search terms used]
|
||||
RESULT: No matching REQ-ID found
|
||||
|
||||
ACTION REQUIRED:
|
||||
1. Create requirement document in requirements/
|
||||
2. Define acceptance criteria
|
||||
3. Obtain stakeholder approval
|
||||
4. Assign REQ-ID
|
||||
5. Add to traceability.csv
|
||||
6. Then implement feature
|
||||
|
||||
ALTERNATIVE:
|
||||
- Feature may be out of scope
|
||||
- Check: Does this align with Virsaitis mission?
|
||||
```
|
||||
|
||||
### AI Requirement Creation Policy
|
||||
|
||||
**WHEN AI MAY CREATE REQUIREMENTS:**
|
||||
AI may create requirement documents when the user provides sufficient input context.
|
||||
User must state the need, scope, and acceptance intent.
|
||||
AI drafts the requirement following REQ-ID format.
|
||||
|
||||
**WORKFLOW:**
|
||||
1. User describes feature need with context
|
||||
2. AI searches existing requirements for overlap
|
||||
3. AI proposes REQ-ID and drafts document
|
||||
4. User reviews and approves before commit
|
||||
5. AI updates traceability.csv
|
||||
|
||||
**CONSTRAINTS:**
|
||||
- AI must never invent requirements without user input
|
||||
- AI must check for duplicate REQ-IDs before assignment
|
||||
- Draft requirements are PROPOSED status until user approval
|
||||
- Requirement scope must align with Virsaitis mission
|
||||
- Discuss: Should this be a requirement?
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ✅ Acceptance Criteria
|
||||
|
||||
### Format
|
||||
|
||||
**USE GIVEN-WHEN-THEN**:
|
||||
```
|
||||
GIVEN [initial context]
|
||||
WHEN [action occurs]
|
||||
THEN [expected outcome]
|
||||
```
|
||||
|
||||
### Examples
|
||||
|
||||
**GOOD ACCEPTANCE CRITERIA**:
|
||||
```
|
||||
AC1: Protected File Blocking
|
||||
GIVEN user attempts to modify .github/copilot-instructions.md
|
||||
WHEN MCP validation tool runs
|
||||
THEN operation is BLOCKED with TIER-0 message
|
||||
|
||||
AC2: Non-Protected File Allowed
|
||||
GIVEN user attempts to modify src/my-file.ts
|
||||
WHEN MCP validation tool runs
|
||||
THEN operation is ALLOWED without warnings
|
||||
|
||||
AC3: Audit Logging
|
||||
GIVEN protected file modification attempted
|
||||
WHEN operation is BLOCKED
|
||||
THEN audit log entry is created with timestamp, user, file, reason
|
||||
```
|
||||
|
||||
**WHY THIS FORMAT**:
|
||||
- Testable (can write automated test directly)
|
||||
- Unambiguous (clear pass/fail)
|
||||
- Complete (covers happy path and edge cases)
|
||||
|
||||
---
|
||||
|
||||
## 🧪 Testing Requirements
|
||||
|
||||
### Test Coverage per Requirement
|
||||
|
||||
**REQUIREMENT → TESTS MAPPING**:
|
||||
- Each requirement MUST have tests
|
||||
- Each acceptance criterion → At least one test
|
||||
- TIER-0/TIER-1 → Multiple test cases (happy path + edge cases)
|
||||
- TIER-2/TIER-3 → Minimum one test case
|
||||
|
||||
**TEST NAMING CONVENTION**:
|
||||
```typescript
|
||||
describe('REQ-GOV-001: Protected File Modification', () => {
|
||||
describe('AC1: Protected File Blocking', () => {
|
||||
it('should block modification of copilot-instructions.md', () => {
|
||||
// Test implementation
|
||||
});
|
||||
|
||||
it('should block modification of agent files', () => {
|
||||
// Test implementation
|
||||
});
|
||||
});
|
||||
|
||||
describe('AC2: Non-Protected File Allowed', () => {
|
||||
it('should allow modification of source files', () => {
|
||||
// Test implementation
|
||||
});
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
> ⚡ CHECKPOINT — Did you search existing requirements before creating new ones? Avoid duplicate REQ-IDs.
|
||||
|
||||
## 📊 Requirement Metrics
|
||||
|
||||
### Coverage Metrics
|
||||
|
||||
**MANDATORY TARGET**: 100% of MUST requirements implemented and tested
|
||||
|
||||
**CALCULATE**:
|
||||
```bash
|
||||
# Count total requirements
|
||||
total=$(grep -c "^REQ-" traceability.csv)
|
||||
|
||||
# Count implemented requirements
|
||||
implemented=$(grep -c ",Implemented," traceability.csv)
|
||||
|
||||
# Calculate percentage
|
||||
coverage=$((implemented * 100 / total))
|
||||
|
||||
echo "Requirement coverage: $coverage%"
|
||||
```
|
||||
|
||||
**QUALITY GATES**:
|
||||
- TIER-0: 100% implemented and verified (no exceptions)
|
||||
- TIER-1: 100% implemented, ≥95% verified
|
||||
- TIER-2: ≥80% implemented
|
||||
- TIER-3: Best effort
|
||||
|
||||
---
|
||||
|
||||
## 💡 Best Practices
|
||||
|
||||
### Requirement Writing
|
||||
|
||||
**GOOD REQUIREMENT**:
|
||||
- Clear and testable
|
||||
- One concept per requirement
|
||||
- Uses "MUST", "SHOULD", or "MAY" (RFC 2119)
|
||||
- Includes rationale (why)
|
||||
- Has acceptance criteria
|
||||
- References dependencies
|
||||
|
||||
**BAD REQUIREMENT**:
|
||||
- Vague ("The system should be good")
|
||||
- Multiple concepts mixed
|
||||
- No acceptance criteria
|
||||
- No clear pass/fail
|
||||
|
||||
### Traceability Maintenance
|
||||
|
||||
**KEEP CSV UP TO DATE**:
|
||||
- Update immediately when implementing
|
||||
- Add TestRef when tests written
|
||||
- Update Status when verified
|
||||
- Review quarterly for accuracy
|
||||
|
||||
**VERIFY REFERENCES**:
|
||||
- ImplementationRef points to actual code
|
||||
- Test Ref points to actual tests
|
||||
- Line numbers are approximate (code changes)
|
||||
- Update refs when code moves
|
||||
|
||||
---
|
||||
|
||||
## 📚 Quick Reference
|
||||
|
||||
| Aspect | Standard | Location |
|
||||
|--------|----------|----------|
|
||||
| **REQ-ID Format** | REQ-[CAT]-[NUM] | All requirements |
|
||||
| **Traceability** | CSV file | requirements/traceability.csv |
|
||||
| **Acceptance Criteria** | Given-When-Then | Requirement docs |
|
||||
| **Test Coverage** | 100% MUST requirements | Per REQ-ID |
|
||||
| **Status** | Draft → Verified | Lifecycle |
|
||||
|
||||
---
|
||||
|
||||
*Requirements Engineering Module v3.0.0*
|
||||
*Traceability and requirement lifecycle management*
|
||||
|
||||
---
|
||||
|
||||
## Key Rules From This Module
|
||||
|
||||
- Every functional change needs a REQ-ID. Format: REQ-[CAT]-[NUM].
|
||||
- Search existing requirements before creating new ones. Avoid duplicates.
|
||||
- Acceptance criteria use Given-When-Then format. Each criterion maps to at least one test.
|
||||
- AI may draft requirements when user provides context, but drafts need user approval.
|
||||
- Definitions: `.github/virsaitis-definition-library.md`
|
||||
|
||||
Return to hub: `.github/copilot-instructions.md`
|
||||
496
.github/copilot-modules/security-controls.md
vendored
Normal file
496
.github/copilot-modules/security-controls.md
vendored
Normal file
@@ -0,0 +1,496 @@
|
||||
If it looks like a secret, treat it as a secret. Remove first, ask questions later.
|
||||
|
||||
# Security Controls - Virsaitis
|
||||
|
||||
**Module**: Security Controls
|
||||
**Load**: For security-sensitive operations, all commits
|
||||
**Version**: 3.0.0
|
||||
**Updated**: 2026-02-17
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Purpose
|
||||
|
||||
Defines secret management, input validation, security scanning, and secure coding practices for all Virsaitis components.
|
||||
|
||||
---
|
||||
|
||||
## 🤖 Machine Policy
|
||||
|
||||
```
|
||||
[SECRET_MANAGEMENT]
|
||||
HARDCODED_SECRETS=prohibited (TIER-0)
|
||||
ENVIRONMENT_VARIABLES=required
|
||||
SECRET_ROTATION=mandatory_on_exposure
|
||||
SCAN_BEFORE_COMMIT=required
|
||||
|
||||
[INPUT_VALIDATION]
|
||||
FILE_PATHS=sanitize_always
|
||||
USER_COMMANDS=escape_required
|
||||
REGEX_PATTERNS=redos_check
|
||||
EXTERNAL_INPUT=validate_type_bounds
|
||||
|
||||
[ERROR_HANDLING]
|
||||
INTERNAL_PATHS=never_expose
|
||||
SENSITIVE_DATA=never_log
|
||||
STACK_TRACES=internal_only
|
||||
AUDIT_LOGGING=required
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🚨 Secret Management (TIER-0)
|
||||
|
||||
### When You Detect Secrets in Code
|
||||
|
||||
Your task is to: 1. Remove the secret. 2. Replace with environment variable reference. 3. Warn user about rotation.
|
||||
|
||||
**SECRET PATTERNS TO DETECT AND REMOVE**:
|
||||
- Hardcoded passwords: `password = "MySecret123"`
|
||||
- API keys in code: `API_KEY = "sk-abc123..."`
|
||||
- Database credentials: `DB_URL = "postgresql://user:pass@host"`
|
||||
- Private keys in files: `.pem`, `.pfx`, `.key` files
|
||||
- OAuth tokens: `token = "ghp_..."`
|
||||
- Session cookies: `session_id = "..."`
|
||||
- AWS access keys: `AWS_SECRET_ACCESS_KEY = "..."`
|
||||
|
||||
### Required Approach
|
||||
|
||||
**USE ENVIRONMENT VARIABLES**:
|
||||
```typescript
|
||||
// ✅ GOOD: Reference environment variable
|
||||
const apiKey = process.env.API_KEY;
|
||||
if (!apiKey) {
|
||||
throw new Error('API_KEY environment variable required');
|
||||
}
|
||||
|
||||
// ❌ BAD: Hardcoded secret
|
||||
const apiKey = 'sk-abc123def456...';
|
||||
```
|
||||
|
||||
**DOCUMENT SECRET NAMES, NOT VALUES**:
|
||||
```markdown
|
||||
## Configuration
|
||||
|
||||
Required environment variables:
|
||||
- `API_KEY`: OpenAI API key (get from platform.openai.com)
|
||||
- `DB_PASSWORD`: PostgreSQL password
|
||||
- `JWT_SECRET`: Random 32-character string
|
||||
```
|
||||
|
||||
**USE SECRET MANAGEMENT SERVICES**:
|
||||
- Azure Key Vault
|
||||
- AWS Secrets Manager
|
||||
- HashiCorp Vault
|
||||
- GitHub Secrets (for CI/CD)
|
||||
|
||||
### Consequence if Violated
|
||||
|
||||
**TIER-0 VIOLATION**:
|
||||
- **Operation**: BLOCKED, commit rejected
|
||||
- **User Impact**: Must rotate credential within 1 hour, file incident report
|
||||
- **Technical Impact**: Security incident triggered, audit log created, automated alerts sent
|
||||
- **Business Impact**: Compliance violation, potential data breach, regulatory fines possible, customer trust damaged
|
||||
- **Remediation**:
|
||||
1. Remove secret from Git history: `git filter-repo --path-glob '*secrets*' --invert-paths`
|
||||
2. Rotate credential immediately (generate new key)
|
||||
3. Update all systems using old credential
|
||||
4. Complete security incident report
|
||||
5. Review: How did secret get committed? Fix process gap
|
||||
|
||||
---
|
||||
|
||||
## 🔍 Secret Scanning (TIER-1)
|
||||
|
||||
### Before Every Commit
|
||||
|
||||
**RUN SECURITY SCAN**:
|
||||
```bash
|
||||
# Automated scan (if available)
|
||||
python scripts/security-scan.py
|
||||
|
||||
# Manual pattern check
|
||||
git diff --cached | grep -Ei "(password|api[_-]?key|secret|token|credential|private[_-]?key)"
|
||||
```
|
||||
|
||||
**IF MATCH FOUND**:
|
||||
1. STOP commit immediately
|
||||
2. Review match: Is it actually a secret?
|
||||
3. If yes: Remove secret, use environment variable reference
|
||||
4. If false positive: Add to exceptions list (carefully)
|
||||
5. Re-run scan
|
||||
6. Confirm: No secrets detected
|
||||
|
||||
### Secret Patterns
|
||||
|
||||
**COMMON PATTERNS**:
|
||||
```regex
|
||||
# API Keys
|
||||
(api[_-]?key|apikey)[\s:=]["']?[a-zA-Z0-9_-]{20,}
|
||||
|
||||
# AWS Keys
|
||||
(AKIA[0-9A-Z]{16}|aws_secret_access_key)
|
||||
|
||||
# Private Keys
|
||||
-----BEGIN (RSA|DSA|EC|OPENSSH) PRIVATE KEY-----
|
||||
|
||||
# GitHub Tokens
|
||||
ghp_[a-zA-Z0-9]{36}
|
||||
|
||||
# JWT Tokens
|
||||
eyJ[a-zA-Z0-9_-]+\.eyJ[a-zA-Z0-9_-]+\.[a-zA-Z0-9_-]+
|
||||
|
||||
# Database URLs
|
||||
(postgresql|mysql)://[^:]+:[^@]+@[^/]+
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🛡️ Input Validation (TIER-1)
|
||||
|
||||
### File Path Validation
|
||||
|
||||
**ALWAYS VALIDATE**:
|
||||
```typescript
|
||||
function validateFilePath(filePath: string): string {
|
||||
// 1. Check null/undefined
|
||||
if (!filePath) {
|
||||
throw new Error('File path is required');
|
||||
}
|
||||
|
||||
// 2. Check path traversal
|
||||
if (filePath.includes('..') || filePath.includes('~')) {
|
||||
throw new Error('Path traversal detected');
|
||||
}
|
||||
|
||||
// 3. Normalize path
|
||||
const normalized = path.normalize(filePath);
|
||||
|
||||
// 4. Ensure absolute path
|
||||
if (!path.isAbsolute(normalized)) {
|
||||
throw new Error('Absolute path required');
|
||||
}
|
||||
|
||||
// 5. Check against whitelist (if applicable)
|
||||
const allowed = [
|
||||
'virsaitis-development/',
|
||||
'.github/',
|
||||
'docs/',
|
||||
];
|
||||
|
||||
if (!allowed.some(prefix => normalized.startsWith(prefix))) {
|
||||
throw new Error('File path not in allowed directories');
|
||||
}
|
||||
|
||||
return normalized;
|
||||
}
|
||||
```
|
||||
|
||||
**WHY**:
|
||||
- Prevents directory traversal attacks (`../../../etc/passwd`)
|
||||
- Prevents access to system files
|
||||
- Ensures operations stay within workspace
|
||||
|
||||
### Command Execution Validation
|
||||
|
||||
**ALWAYS SANITIZE**:
|
||||
```typescript
|
||||
function executeCommand(command: string, args: string[]): Promise<string> {
|
||||
// 1. Whitelist allowed commands
|
||||
const allowedCommands = ['npm', 'python', 'git', 'tsc'];
|
||||
if (!allowedCommands.includes(command)) {
|
||||
throw new Error(`Command not allowed: ${command}`);
|
||||
}
|
||||
|
||||
// 2. Escape arguments (prevent injection)
|
||||
const escapedArgs = args.map(arg => shell Escape(arg));
|
||||
|
||||
// 3. Execute with spawn (not exec)
|
||||
const result = await execFile(command, escapedArgs);
|
||||
|
||||
return result.stdout;
|
||||
}
|
||||
```
|
||||
|
||||
**WHY**:
|
||||
- Prevents command injection
|
||||
- Limits blast radius (whitelist only)
|
||||
- Prevents shell expansion attacks
|
||||
|
||||
### Regular Expression Validation
|
||||
|
||||
**PREVENT ReDoS**:
|
||||
```typescript
|
||||
// ❌ BAD: Catastrophic backtracking
|
||||
const badRegex = /^(a+)+$/;
|
||||
|
||||
// ✅ GOOD: No backtracking
|
||||
const goodRegex = /^a+$/;
|
||||
|
||||
// Validate regex complexity
|
||||
function isRegexSafe(pattern: string): boolean {
|
||||
// Check for nested quantifiers
|
||||
if (/(\*|\+|\{[^}]+\})(\*|\+|\{[^}]+\})/.test(pattern)) {
|
||||
return false;
|
||||
}
|
||||
|
||||
// Check length (prevent excessive backtracking)
|
||||
if (pattern.length > 1000) {
|
||||
return false;
|
||||
}
|
||||
|
||||
return true;
|
||||
}
|
||||
```
|
||||
|
||||
**WHY**:
|
||||
- ReDoS attacks cause CPU exhaustion
|
||||
- Can DOS entire server
|
||||
- Hard to detect without analysis
|
||||
|
||||
### Type and Bounds Validation
|
||||
|
||||
> ⚡ CHECKPOINT — Does this code handle user input? Validate type, length, and allowed values before processing.
|
||||
|
||||
**ALWAYS CHECK**:
|
||||
```typescript
|
||||
interface FileOperationParams {
|
||||
operation: 'read' | 'write' | 'delete';
|
||||
filePath: string;
|
||||
content?: string;
|
||||
}
|
||||
|
||||
function validateParams(params: any): FileOperationParams {
|
||||
// Type check
|
||||
if (typeof params !== 'object') {
|
||||
throw new Error('Params must be object');
|
||||
}
|
||||
|
||||
// Required fields
|
||||
if (!params.operation || !params.filePath) {
|
||||
throw new Error('Missing required fields');
|
||||
}
|
||||
|
||||
// Enum validation
|
||||
const validOps = ['read', 'write', 'delete'];
|
||||
if (!validOps.includes(params.operation)) {
|
||||
throw new Error(`Invalid operation: ${params.operation}`);
|
||||
}
|
||||
|
||||
// Bounds validation
|
||||
if (params.content && params.content.length > 1_000_000) {
|
||||
throw new Error('Content too large (max 1MB)');
|
||||
}
|
||||
|
||||
return params as FileOperationParams;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ Error Handling (TIER-1)
|
||||
|
||||
### When Handling Errors, Sanitize Before Returning
|
||||
|
||||
Your task is to: 1. Log full details internally. 2. Return sanitized message to user. 3. Never expose file paths or stack traces externally.
|
||||
|
||||
**❌ BAD**:
|
||||
```typescript
|
||||
try {
|
||||
await fs.promises.readFile(filePath);
|
||||
} catch (error) {
|
||||
// Exposes internal file path to user
|
||||
throw new Error(`Failed to read ${filePath}: ${error.message}`);
|
||||
}
|
||||
```
|
||||
|
||||
**✅ GOOD**:
|
||||
```typescript
|
||||
try {
|
||||
await fs.promises.readFile(filePath);
|
||||
} catch (error) {
|
||||
// Log full details internally
|
||||
logger.error('File read failed', {
|
||||
filePath,
|
||||
error: error.message,
|
||||
stack: error.stack
|
||||
});
|
||||
|
||||
// Return sanitized error to user
|
||||
throw new Error('Unable to read file. Check permissions and file existence.');
|
||||
}
|
||||
```
|
||||
|
||||
### Logging Security
|
||||
|
||||
**EXCLUDED FROM LOGS** (sensitive data — redact or omit):
|
||||
|
||||
> ⚡ CHECKPOINT — If it looks like a secret, treat it as a secret. Remove first, ask later.
|
||||
- Passwords or secrets
|
||||
- API keys or tokens
|
||||
- Personal Identifiable Information (PII)
|
||||
- Credit card numbers
|
||||
- Full file paths (use relative paths)
|
||||
- Stack traces to external systems
|
||||
|
||||
**DO LOG**:
|
||||
- Audit trail (who did what when)
|
||||
- Governance violations (with sanitized details)
|
||||
- Security scan results
|
||||
- Authentication/authorization events
|
||||
- File operation attempts (protected files)
|
||||
- MCP tool usage
|
||||
|
||||
**LOG FORMAT**:
|
||||
```typescript
|
||||
logger.audit({
|
||||
timestamp: new Date().toISOString(),
|
||||
user: getUserId(), // Not username
|
||||
action: 'file_operation',
|
||||
operation: 'write',
|
||||
file: relativePath('/virsaitis-development/'), // Not full path
|
||||
allowed: false,
|
||||
tier: 'TIER-0',
|
||||
reason: 'Protected file modification attempted',
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔒 Secure Coding Practices
|
||||
|
||||
### Principle of Least Privilege
|
||||
|
||||
**FILE SYSTEM**:
|
||||
- Only access files in workspace
|
||||
- Read-only by default
|
||||
- Write only when validated
|
||||
- Never execute without explicit approval
|
||||
|
||||
**NETWORK**:
|
||||
- Only connect to configured MCP server
|
||||
- Use HTTPS for external requests
|
||||
- Validate SSL certificates
|
||||
- Timeout all network requests
|
||||
|
||||
### Defense in Depth
|
||||
|
||||
**LAYER 1**: Input validation (validate all external input)
|
||||
**LAYER 2**: Business logic validation (check against rules)
|
||||
**LAYER 3**: MCP tool validation (governance checks)
|
||||
**LAYER 4**: Extension validation (user action intercept)
|
||||
**LAYER 5**: Audit logging (track all operations)
|
||||
|
||||
**BENEFIT**: If one layer fails, others still protect
|
||||
|
||||
### Secure Defaults
|
||||
|
||||
**DEFAULT**: Deny (operations blocked unless explicitly allowed)
|
||||
**CONFIGURATION**: Secure out of box (no setup required for security)
|
||||
**ENCRYPTION**: TLS for all network communication
|
||||
**AUTHENTICATION**: Always verify MCP server identity
|
||||
|
||||
---
|
||||
|
||||
## 🔐 Cryptography (TIER-2)
|
||||
|
||||
### Use Well-Vetted Libraries
|
||||
|
||||
**✅ RECOMMENDED**:
|
||||
- Node.js `crypto` module (native)
|
||||
- `bcrypt` for password hashing
|
||||
- `jsonwebtoken` (JWT)
|
||||
- `crypto-js` (if needed)
|
||||
|
||||
**❌ AVOID** (use recommended alternatives instead):
|
||||
- Custom encryption algorithms
|
||||
- `crypto-js` deprecated methods
|
||||
- MD5, SHA1 (broken)
|
||||
- Home-grown authentication
|
||||
|
||||
### Hashing
|
||||
|
||||
> ⚡ CHECKPOINT — Error messages sanitized? No internal paths, no stack traces exposed to users.
|
||||
|
||||
**FOR PASSWORDS**:
|
||||
```typescript
|
||||
import bcrypt from 'bcrypt';
|
||||
|
||||
// Hash password
|
||||
const saltRounds = 12;
|
||||
const hashedPassword = await bcrypt.hash(password, saltRounds);
|
||||
|
||||
// Verify password
|
||||
const isValid = await bcrypt.compare(inputPassword, hashedPassword);
|
||||
```
|
||||
|
||||
**FOR DATA INTEGRITY**:
|
||||
```typescript
|
||||
import crypto from 'crypto';
|
||||
|
||||
// SHA-256 hash
|
||||
const hash = crypto.createHash('sha256')
|
||||
.update(data)
|
||||
.digest('hex');
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🚦 Security Testing (TIER-1)
|
||||
|
||||
### Security Test Coverage
|
||||
|
||||
**REQUIRE 100% COVERAGE**:
|
||||
- Secret detection (all patterns)
|
||||
- Path traversal prevention
|
||||
- Command injection prevention
|
||||
- Input validation (all inputs)
|
||||
- Error handling (no leaks)
|
||||
|
||||
**TEST EXAMPLES**:
|
||||
```typescript
|
||||
describe('Security', () => {
|
||||
describe('Secret Detection', () => {
|
||||
it('should detect API keys', () => {
|
||||
const code = 'const key = "sk-abc123def456";';
|
||||
expect(detectSecrets(code)).toContain('API_KEY_DETECTED');
|
||||
});
|
||||
});
|
||||
|
||||
describe('Path Traversal', () => {
|
||||
it('should block directory traversal', () => {
|
||||
expect(() => validatePath('../../../etc/passwd')).toThrow();
|
||||
});
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📚 Quick Reference
|
||||
|
||||
| Threat | Prevention | Test |
|
||||
|--------|------------|------|
|
||||
| **Secrets** | Env variables only | Secret scan before commit |
|
||||
| **Path Traversal** | Sanitize, normalize | Try `../` in tests |
|
||||
| **Command Injection** | Whitelist, escape | Try `; rm -rf` |
|
||||
| **ReDoS** | Simple regex only | Test with long input |
|
||||
| **Info Leak** | Sanitize errors | Check error messages |
|
||||
| **PII Logging** | Redaction required | Review all logs |
|
||||
|
||||
---
|
||||
|
||||
*Security Controls Module v3.0.0*
|
||||
*Defense in depth for Virsaitis governance*
|
||||
|
||||
---
|
||||
|
||||
## Key Rules From This Module
|
||||
|
||||
- Secrets in code must be removed immediately. Replace with environment variables.
|
||||
- Sanitize all file paths. Reject path traversal attempts before processing.
|
||||
- Whitelist allowed commands. Never pass user input directly to shell execution.
|
||||
- Log all governance decisions. Redact PII from all log entries.
|
||||
- Definitions: `.github/virsaitis-definition-library.md`
|
||||
|
||||
Return to hub: `.github/copilot-instructions.md`
|
||||
207
.github/copilot-modules/skills-standards.md
vendored
Normal file
207
.github/copilot-modules/skills-standards.md
vendored
Normal file
@@ -0,0 +1,207 @@
|
||||
Skills use SKILL.md format with YAML frontmatter. One skill per folder. Test before deploy.
|
||||
|
||||
# Skills Standards - Native Agent Skills
|
||||
|
||||
**Module**: Skills Standards
|
||||
**Component**: Native VS Code Agent Skills (Layer 4)
|
||||
**Load**: When creating/editing skills in .github/skills/
|
||||
**Version**: 3.0.0
|
||||
**Updated**: 2026-04-20
|
||||
|
||||
---
|
||||
|
||||
## Machine Policy
|
||||
|
||||
```
|
||||
[SKILL_FORMAT]
|
||||
FORMAT=SKILL.md
|
||||
STRUCTURE=YAML_frontmatter + Markdown_body
|
||||
LOCATION=.github/skills/skill-name/SKILL.md
|
||||
TOKEN_TARGET=<5000_per_skill
|
||||
DESCRIPTION_LENGTH=~100_tokens
|
||||
VS_CODE_VERSION=1.109+
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## SKILL.md Format
|
||||
|
||||
### File Structure
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: lowercase-hyphens-only
|
||||
description: what + when + keywords (1-1024 chars)
|
||||
license: MIT
|
||||
compatibility: VS Code 1.109+, Node.js 18+
|
||||
metadata:
|
||||
tier: TIER-0 | TIER-1 | TIER-2 | TIER-3
|
||||
category: governance | security | quality | language | testing
|
||||
framework-version: "3.0.0"
|
||||
author: virsaitis
|
||||
version: "1.0.0"
|
||||
---
|
||||
|
||||
# Skill Title
|
||||
|
||||
## Overview
|
||||
## When to Activate
|
||||
## Standards & Rules
|
||||
## Consequences
|
||||
## Procedures
|
||||
## Examples
|
||||
## Validation & Testing
|
||||
## Quick Reference
|
||||
```
|
||||
|
||||
### Frontmatter Requirements (TIER-1)
|
||||
|
||||
| Field | Required | Format | Example |
|
||||
|-------|----------|--------|---------|
|
||||
| `name` | Yes | lowercase-hyphens, 1-64 chars | `python-development` |
|
||||
| `description` | Yes | plain text, 1-1024 chars | What + When + Keywords |
|
||||
| `license` | No | SPDX identifier | `MIT` |
|
||||
| `compatibility` | No | version requirements | `VS Code 1.109+` |
|
||||
| `metadata.tier` | Yes (Virsaitis) | TIER-0 through TIER-3 | `TIER-1` |
|
||||
| `metadata.category` | Yes (Virsaitis) | governance/security/quality/language/testing | `governance` |
|
||||
|
||||
**Name MUST match directory name exactly.**
|
||||
|
||||
**Description MUST include**: what the skill does, when to activate, discovery keywords.
|
||||
|
||||
---
|
||||
|
||||
## Required Sections
|
||||
|
||||
### Overview
|
||||
What this skill does and why. Use atomic sentences. 2-3 paragraphs.
|
||||
|
||||
### When to Activate
|
||||
Keywords and scenarios for VS Code skill activation. Include keyword list for discovery.
|
||||
|
||||
### Standards & Rules
|
||||
Specific rules grouped by TIER level. Each rule: Name, TIER, Enforcement, Rationale.
|
||||
|
||||
### Consequences (Virsaitis Extension)
|
||||
Impact chains per TIER violation. Five dimensions: Operation, User, Technical, Business, Remediation.
|
||||
|
||||
```markdown
|
||||
### TIER-0 Violations
|
||||
**Rule**: [Rule Name]
|
||||
**If Violated**:
|
||||
- **Operation**: BLOCKED immediately
|
||||
- **User Impact**: [effect on user]
|
||||
- **Technical Impact**: [what breaks]
|
||||
- **Business Impact**: [why it matters]
|
||||
- **Remediation**: [how to fix]
|
||||
```
|
||||
|
||||
### Procedures
|
||||
Step-by-step workflows with commands and expected outcomes.
|
||||
|
||||
### Examples
|
||||
Good vs Bad code snippets with compliance explanations.
|
||||
|
||||
### Validation & Testing
|
||||
Commands to verify compliance, expected output, error interpretation.
|
||||
|
||||
### Quick Reference
|
||||
Summary table for rapid lookup.
|
||||
|
||||
---
|
||||
|
||||
## Directory Structure
|
||||
|
||||
```
|
||||
.github/skills/
|
||||
├── skill-name/
|
||||
│ ├── SKILL.md (required - main skill file)
|
||||
│ ├── scripts/ (optional - helper scripts)
|
||||
│ ├── references/ (optional - reference docs)
|
||||
│ └── assets/ (optional - images, examples)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Validation (TIER-1)
|
||||
|
||||
```bash
|
||||
# Validate skill structure
|
||||
skills-ref validate .github/skills/skill-name/
|
||||
|
||||
# Expected output:
|
||||
# ✓ Skill name matches directory
|
||||
# ✓ Description within 1-1024 chars
|
||||
# ✓ Frontmatter valid YAML
|
||||
# ✓ SKILL.md found
|
||||
```
|
||||
|
||||
Fix all errors before committing.
|
||||
|
||||
---
|
||||
|
||||
## Token Efficiency (TIER-2)
|
||||
|
||||
**Targets**:
|
||||
- Description: ~100 tokens (efficient discovery)
|
||||
- Full skill body: <5000 tokens (~500 lines)
|
||||
- Total loaded: <1% of 200K context window
|
||||
|
||||
**VS Code loads skills in 3 levels**:
|
||||
1. **Metadata** (~100 tokens): Always loaded for discovery
|
||||
2. **Instructions** (<5000 tokens): Loaded when skill activated
|
||||
3. **Resources** (on-demand): Loaded only when referenced
|
||||
|
||||
Keep SKILL.md lean. Put large examples in `references/`.
|
||||
|
||||
---
|
||||
|
||||
## Skill Development Workflow
|
||||
|
||||
### Create New Skill
|
||||
|
||||
1. Choose skill name (lowercase-hyphens)
|
||||
2. Create directory: `.github/skills/skill-name/`
|
||||
3. Fill frontmatter (name must match directory)
|
||||
4. Write sections: Overview → Rules → Consequences → Procedures
|
||||
5. Add good/bad examples
|
||||
6. Validate: `skills-ref validate`
|
||||
7. Test activation in VS Code 1.109+
|
||||
8. Update CHANGELOG and commit
|
||||
|
||||
### Modify Existing Skill
|
||||
|
||||
1. Read current SKILL.md fully
|
||||
2. Maintain atomic sentence structure
|
||||
3. Update version in frontmatter
|
||||
4. Validate and test before commit
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Aspect | Standard | Tool |
|
||||
|--------|----------|------|
|
||||
| **Format** | SKILL.md | VS Code markdown |
|
||||
| **Location** | .github/skills/ | Repository root |
|
||||
| **Frontmatter** | YAML | `---` delimiters |
|
||||
| **Tokens** | <5000 body | Word count estimate |
|
||||
| **Validation** | skills-ref | `skills-ref validate` |
|
||||
| **VS Code** | 1.109+ | Check release |
|
||||
|
||||
---
|
||||
|
||||
*Skills Standards Module v3.0.0*
|
||||
*Native VS Code Agent Skills for Virsaitis governance*
|
||||
|
||||
---
|
||||
|
||||
## Key Rules From This Module
|
||||
|
||||
- SKILL.md is the entry point. YAML frontmatter with description is required.
|
||||
- One skill per folder. Folder name matches skill purpose.
|
||||
- Test every skill before deployment. Manual validation required.
|
||||
- Skills in `.github/skills/` are the one exception to .github write restrictions.
|
||||
- Definitions: `.github/virsaitis-definition-library.md`
|
||||
|
||||
Return to hub: `.github/copilot-instructions.md`
|
||||
671
.github/copilot-modules/testing-quality.md
vendored
Normal file
671
.github/copilot-modules/testing-quality.md
vendored
Normal file
@@ -0,0 +1,671 @@
|
||||
Every feature needs tests. Coverage ≥70%. Security tests 100%. No exceptions.
|
||||
|
||||
# Testing & Quality - Virsaitis
|
||||
|
||||
**Module**: Testing & Quality
|
||||
**Load**: When writing tests, checking quality gates
|
||||
**Version**: 3.0.0
|
||||
**Updated**: 2026-02-17
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Purpose
|
||||
|
||||
Defines testing standards, coverage targets, quality metrics, and validation procedures for all Virsaitis components.
|
||||
|
||||
---
|
||||
|
||||
## 🤖 Machine Policy
|
||||
|
||||
```
|
||||
[TESTING_STANDARDS]
|
||||
FRAMEWORK_MCP=vitest
|
||||
FRAMEWORK_EXTENSION=@vscode/test-electron
|
||||
FRAMEWORK_AGENT=manual_review
|
||||
TDD=preferred
|
||||
|
||||
[COVERAGE_TARGETS]
|
||||
OVERALL=70_percent_minimum
|
||||
SECURITY_CRITICAL=100_percent_required
|
||||
GOVERNANCE=100_percent_required
|
||||
UTILITIES=70_percent
|
||||
|
||||
[QUALITY_GATES]
|
||||
BUILD=must_succeed
|
||||
TESTS=must_pass_all
|
||||
LINT=zero_errors
|
||||
COVERAGE=meet_targets
|
||||
SECURITY_TESTS=100_percent_pass
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🧪 Testing Frameworks
|
||||
|
||||
### MCP Server (TypeScript)
|
||||
|
||||
**FRAMEWORK**: Vitest
|
||||
|
||||
**vitest.config.ts**:
|
||||
```typescript
|
||||
import { defineConfig } from 'vitest/config';
|
||||
|
||||
export default defineConfig({
|
||||
test: {
|
||||
coverage: {
|
||||
provider: 'v8',
|
||||
reporter: ['text', 'html', 'lcov'],
|
||||
lines: 70,
|
||||
functions: 70,
|
||||
branches: 70,
|
||||
statements: 70,
|
||||
exclude: [
|
||||
'node_modules/',
|
||||
'build/',
|
||||
'**/*.test.ts',
|
||||
'**/*.spec.ts',
|
||||
],
|
||||
},
|
||||
globals: true,
|
||||
environment: 'node',
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
**RUN TESTS**:
|
||||
```bash
|
||||
npm test # Run all tests
|
||||
npm run test:watch # Watch mode
|
||||
npm run test:coverage # Coverage report
|
||||
npm run test:ui # UI interface
|
||||
```
|
||||
|
||||
### VS Code Extension (TypeScript)
|
||||
|
||||
**FRAMEWORK**: @vscode/test-electron
|
||||
|
||||
**test/runTest.ts**:
|
||||
```typescript
|
||||
import * as path from 'path';
|
||||
import { runTests } from '@vscode/test-electron';
|
||||
|
||||
async function main() {
|
||||
try {
|
||||
const extensionDevelopmentPath = path.resolve(__dirname, '../../');
|
||||
const extensionTestsPath = path.resolve(__dirname, './suite/index');
|
||||
|
||||
await runTests({
|
||||
extensionDevelopmentPath,
|
||||
extensionTestsPath,
|
||||
});
|
||||
} catch (err) {
|
||||
console.error('Failed to run tests');
|
||||
process.exit(1);
|
||||
}
|
||||
}
|
||||
|
||||
main();
|
||||
```
|
||||
|
||||
**RUN TESTS**:
|
||||
```bash
|
||||
npm test # Run extension tests
|
||||
```
|
||||
|
||||
Tests run in Extension Development Host (isolated VS Code instance).
|
||||
|
||||
### Agent (Markdown)
|
||||
|
||||
**VALIDATION**: Manual review
|
||||
|
||||
**CHECKLIST**:
|
||||
- [ ] Atomic sentence structure (one concept per sentence)
|
||||
- [ ] Each sentence <80 characters
|
||||
- [ ] No compound clauses
|
||||
- [ ] Clear subject-verb-object
|
||||
- [ ] Standalone comprehensibility
|
||||
|
||||
**NO AUTOMATED TESTING** (atomic structure requires human judgment)
|
||||
|
||||
---
|
||||
|
||||
## 📊 Coverage Targets (TIER-1)
|
||||
|
||||
### Minimum Coverage
|
||||
|
||||
| Component | Overall | Security | Governance |
|
||||
|-----------|---------|----------|------------|
|
||||
| **MCP Server** | ≥70% | 100% | 100% |
|
||||
| **Extension** | ≥70% | 100% | 100% |
|
||||
| **Agent** | Manual | N/A | Manual |
|
||||
| **Skills** | Manual | N/A | Manual |
|
||||
|
||||
### What to Cover
|
||||
|
||||
**MUST COVER (100%)**:
|
||||
- Security-critical code (secret scanning, validation)
|
||||
- Governance enforcement (TIER validation, file protection)
|
||||
- MCP tool handlers (core governance tools)
|
||||
- Extension interceptors (file operation blocking)
|
||||
|
||||
**SHOULD COVER (≥70%)**:
|
||||
- Business logic
|
||||
- Data transformations
|
||||
- Error handling
|
||||
- Configuration management
|
||||
- Utility functions
|
||||
|
||||
**CAN SKIP**:
|
||||
- Generated code
|
||||
- Third-party library wrappers (covered by library tests)
|
||||
- Simple getters/setters (if trivial)
|
||||
- Type definitions only files
|
||||
|
||||
---
|
||||
|
||||
## ✅ Test Structure
|
||||
|
||||
### Unit Test Pattern
|
||||
|
||||
```typescript
|
||||
import { describe, it, expect, beforeEach, afterEach } from 'vitest';
|
||||
import { GovernanceValidator } from '../src/governance/validator';
|
||||
|
||||
describe('GovernanceValidator', () => {
|
||||
let validator: GovernanceValidator;
|
||||
|
||||
beforeEach(() => {
|
||||
// Setup: Create fresh validator instance
|
||||
validator = new GovernanceValidator();
|
||||
});
|
||||
|
||||
afterEach(() => {
|
||||
// Cleanup: Dispose resources
|
||||
validator.dispose();
|
||||
});
|
||||
|
||||
describe('validateFileOperation', () => {
|
||||
describe('Protected Files', () => {
|
||||
it('should block modification of copilot-instructions.md', () => {
|
||||
// Given
|
||||
const operation = 'write';
|
||||
const filePath = '.github/copilot-instructions.md';
|
||||
|
||||
// When
|
||||
const result = validator.validateFileOperation(operation, filePath);
|
||||
|
||||
// Then
|
||||
expect(result.allowed).toBe(false);
|
||||
expect(result.tier).toBe('TIER-0');
|
||||
expect(result.reason).toContain('protected file');
|
||||
});
|
||||
|
||||
it('should block modification of agent files', () => {
|
||||
// Given
|
||||
const operation = 'write';
|
||||
const filePath = '.github/agents/Virsaitis.agent.md';
|
||||
|
||||
// When
|
||||
const result = validator.validateFileOperation(operation, filePath);
|
||||
|
||||
// Then
|
||||
expect(result.allowed).toBe(false);
|
||||
expect(result.tier).toBe('TIER-0');
|
||||
});
|
||||
});
|
||||
|
||||
describe('Non-Protected Files', () => {
|
||||
|
||||
> ⚡ CHECKPOINT — Security tests at 100% coverage? TIER-0 rules must have multiple test cases.
|
||||
it('should allow modification of source files', () => {
|
||||
// Given
|
||||
const operation = 'write';
|
||||
const filePath = 'src/my-file.ts';
|
||||
|
||||
// When
|
||||
const result = validator.validateFileOperation(operation, filePath);
|
||||
|
||||
// Then
|
||||
expect(result.allowed).toBe(true);
|
||||
expect(result.tier).toBeUndefined();
|
||||
});
|
||||
});
|
||||
|
||||
describe('Edge Cases', () => {
|
||||
it('should handle null file path', () => {
|
||||
// Given
|
||||
const operation = 'write';
|
||||
const filePath = null as any;
|
||||
|
||||
// When/Then
|
||||
expect(() => validator.validateFileOperation(operation, filePath))
|
||||
.toThrow('File path is required');
|
||||
});
|
||||
|
||||
it('should handle path traversal attempts', () => {
|
||||
// Given
|
||||
const operation = 'write';
|
||||
const filePath = '../../../etc/passwd';
|
||||
|
||||
// When/Then
|
||||
expect(() => validator.validateFileOperation(operation, filePath))
|
||||
.toThrow('Path traversal detected');
|
||||
});
|
||||
});
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
### Integration Test Pattern
|
||||
|
||||
```typescript
|
||||
describe('MCP Server Integration', () => {
|
||||
let server: MCPServer;
|
||||
let client: Client;
|
||||
let transport: StdioClientTransport;
|
||||
|
||||
beforeAll(async () => {
|
||||
// Start MCP server via stdio transport
|
||||
transport = new StdioClientTransport({ command: 'node', args: ['build/index.js'] });
|
||||
client = new Client({ name: 'test-client', version: '1.0.0' });
|
||||
await client.connect(transport);
|
||||
});
|
||||
|
||||
afterAll(async () => {
|
||||
// Cleanup
|
||||
await server.stop();
|
||||
});
|
||||
|
||||
it('should validate protected file operation via MCP', async () => {
|
||||
// Given
|
||||
const request = {
|
||||
operation: 'write',
|
||||
filePath: '.github/copilot-instructions.md',
|
||||
};
|
||||
|
||||
// When
|
||||
const response = await client.callTool('mcp_virsaitis_validate_operation', request);
|
||||
|
||||
// Then
|
||||
expect(response.allowed).toBe(false);
|
||||
expect(response.tier).toBe('TIER-0');
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔒 Security Testing (TIER-1)
|
||||
|
||||
### Security Test Requirements
|
||||
|
||||
**100% COVERAGE REQUIRED**:
|
||||
- Secret detection (all patterns)
|
||||
- Path traversal prevention
|
||||
- Command injection prevention
|
||||
- Input validation
|
||||
- Error handling (no information leaks)
|
||||
|
||||
### Security Test Examples
|
||||
|
||||
```typescript
|
||||
describe('Security Tests', () => {
|
||||
describe('Secret Detection', () => {
|
||||
it('should detect hardcoded API keys', () => {
|
||||
const code = 'const apiKey = "sk-abc123def456";';
|
||||
const result = secretScanner.scan(code);
|
||||
expect(result.violations).toContainEqual({
|
||||
type: 'API_KEY',
|
||||
line: 1,
|
||||
pattern: 'sk-abc123def456',
|
||||
});
|
||||
});
|
||||
|
||||
it('should detect AWS access keys', () => {
|
||||
const code = 'AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE';
|
||||
const result = secretScanner.scan(code);
|
||||
expect(result.violations).toHaveLength(1);
|
||||
});
|
||||
|
||||
it('should not flag environment variable references', () => {
|
||||
const code = 'const apiKey = process.env.API_KEY;';
|
||||
const result = secretScanner.scan(code);
|
||||
expect(result.violations).toHaveLength(0);
|
||||
});
|
||||
});
|
||||
|
||||
describe('Path Traversal Prevention', () => {
|
||||
it('should block ../ in file paths', () => {
|
||||
expect(() => validatePath('../../../etc/passwd'))
|
||||
.toThrow('Path traversal detected');
|
||||
});
|
||||
|
||||
it('should block ~/ in file paths', () => {
|
||||
expect(() => validatePath('~/sensitive-file'))
|
||||
.toThrow('Path traversal detected');
|
||||
});
|
||||
});
|
||||
|
||||
describe('Command Injection Prevention', () => {
|
||||
it('should block shell metacharacters', () => {
|
||||
expect(() => executeCommand('npm', ['install', '; rm -rf /']))
|
||||
.toThrow('Invalid argument');
|
||||
});
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Test-Driven Development (TDD)
|
||||
|
||||
### Red-Green-Refactor Cycle
|
||||
|
||||
```
|
||||
1. RED: Write failing test
|
||||
↓
|
||||
2. GREEN: Write minimum code to pass
|
||||
↓
|
||||
3. REFACTOR: Improve code quality
|
||||
↓
|
||||
4. REPEAT
|
||||
```
|
||||
|
||||
### TDD Example
|
||||
|
||||
**STEP 1: Red (Write Failing Test)**
|
||||
```typescript
|
||||
it('should block protected file modification', () => {
|
||||
const result = validator.validateFileOperation('write', '.github/copilot-instructions.md');
|
||||
expect(result.allowed).toBe(false);
|
||||
});
|
||||
```
|
||||
|
||||
Run test: ❌ FAILS (validator not implemented)
|
||||
|
||||
**STEP 2: Green (Minimum Implementation)**
|
||||
```typescript
|
||||
validateFileOperation(operation: string, filePath: string): ValidationResult {
|
||||
if (filePath === '.github/copilot-instructions.md') {
|
||||
return { allowed: false, tier: 'TIER-0' };
|
||||
}
|
||||
return { allowed: true };
|
||||
}
|
||||
```
|
||||
|
||||
Run test: ✅ PASSES
|
||||
|
||||
**STEP 3: Refactor (Improve)**
|
||||
```typescript
|
||||
validateFileOperation(operation: string, filePath: string): ValidationResult {
|
||||
const protectedPatterns = [
|
||||
'.github/copilot-instructions.md',
|
||||
'.github/copilot-modules/',
|
||||
'.github/agents/',
|
||||
];
|
||||
|
||||
const isProtected = protectedPatterns.some(pattern => filePath.includes(pattern));
|
||||
|
||||
if (isProtected) {
|
||||
return {
|
||||
allowed: false,
|
||||
tier: 'TIER-0',
|
||||
reason: 'Protected file modification blocked',
|
||||
};
|
||||
}
|
||||
|
||||
return { allowed: true };
|
||||
}
|
||||
```
|
||||
|
||||
Run test: ✅ STILL PASSES
|
||||
|
||||
---
|
||||
|
||||
## 📏 Quality Metrics
|
||||
|
||||
### Code Quality Standards (TIER-2)
|
||||
|
||||
**LINTING**: Zero errors, warnings acceptable
|
||||
|
||||
**COMPLEXITY**: Cyclomatic complexity <15 per function
|
||||
|
||||
**DUPLICATION**: <5% code duplication
|
||||
|
||||
**MAINTAINABILITY INDEX**: >70 (good), >50 (acceptable)
|
||||
|
||||
### Measure Quality
|
||||
|
||||
> ⚡ CHECKPOINT — Coverage ≥70% overall? All tests passing? No skipped tests?
|
||||
|
||||
```bash
|
||||
# Linting
|
||||
npm run lint
|
||||
|
||||
# Type checking
|
||||
npm run type-check
|
||||
|
||||
# Complexity (if tool available)
|
||||
npx complexity-report src/
|
||||
|
||||
# Duplication (if tool available)
|
||||
npx jscpd src/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🚦 Quality Gates (TIER-1)
|
||||
|
||||
### Pre-Commit Gates
|
||||
|
||||
**ALL MUST PASS**:
|
||||
```bash
|
||||
npm run build # ✅ Build succeeds
|
||||
npm test # ✅ All tests pass
|
||||
npm run lint # ✅ Zero linter errors
|
||||
npm run type-check # ✅ TypeScript strict mode
|
||||
npm run test:coverage # ✅ Coverage ≥70%
|
||||
npm run test:security # ✅ Security tests 100% pass
|
||||
```
|
||||
|
||||
**IF ANY FAIL**: Must fix before commit
|
||||
|
||||
### Pre-Merge Gates
|
||||
|
||||
**ALL MUST PASS**:
|
||||
- [ ] All pre-commit gates passed
|
||||
- [ ] Code review approved
|
||||
- [ ] Documentation updated
|
||||
- [ ] CHANGELOG updated
|
||||
- [ ] traceability.csv updated
|
||||
- [ ] No TIER-0 violations introduced
|
||||
- [ ] Performance acceptable (no regressions)
|
||||
|
||||
### Pre-Release Gates
|
||||
|
||||
**ALL MUST PASS**:
|
||||
- [ ] All pre-merge gates passed
|
||||
- [ ] End-to-end tests pass
|
||||
- [ ] Manual testing complete (critical paths)
|
||||
- [ ] Distribution package built successfully
|
||||
- [ ] Installation instructions verified
|
||||
- [ ] Migration guide written (if breaking changes)
|
||||
|
||||
---
|
||||
|
||||
## 🔄 Continuous Integration
|
||||
|
||||
### CI Pipeline
|
||||
|
||||
```yaml
|
||||
# .github/workflows/test.yml
|
||||
name: Test
|
||||
|
||||
on: [push, pull_request]
|
||||
|
||||
jobs:
|
||||
test:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v3
|
||||
|
||||
- name: Setup Node.js
|
||||
uses: actions/setup-node@v3
|
||||
with:
|
||||
node-version: '18'
|
||||
|
||||
- name: Install dependencies
|
||||
run: npm ci
|
||||
|
||||
- name: Build
|
||||
run: npm run build
|
||||
|
||||
- name: Lint
|
||||
run: npm run lint
|
||||
|
||||
- name: Type check
|
||||
run: npm run type-check
|
||||
|
||||
- name: Test
|
||||
run: npm test
|
||||
|
||||
- name: Coverage
|
||||
run: npm run test:coverage
|
||||
|
||||
- name: Upload coverage
|
||||
uses: codecov/codecov-action@v3
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📖 Test Documentation
|
||||
|
||||
### Test Naming
|
||||
|
||||
**CONVENTION**:
|
||||
```
|
||||
describe('[Component/Feature]', () => {
|
||||
describe('[Method/Function]', () => {
|
||||
it('should [expected behavior] when [condition]', () => {
|
||||
// Test implementation
|
||||
});
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
**EXAMPLES**:
|
||||
|
||||
> ⚡ CHECKPOINT — Test names follow pattern: describe('[REQ-ID]') → describe('[AC]') → it('should...')?
|
||||
|
||||
```typescript
|
||||
describe('GovernanceValidator', () => {
|
||||
describe('validateFileOperation', () => {
|
||||
it('should block protected files when write operation', () => {});
|
||||
it('should allow non-protected files when write operation', () => {});
|
||||
it('should throw error when file path is null', () => {});
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
### Test Comments
|
||||
|
||||
**GIVEN-WHEN-THEN**:
|
||||
```typescript
|
||||
it('should block protected file modification', () => {
|
||||
// Given: Protected file and write operation
|
||||
const operation = 'write';
|
||||
const filePath = '.github/copilot-instructions.md';
|
||||
|
||||
// When: Validation runs
|
||||
const result = validator.validateFileOperation(operation, filePath);
|
||||
|
||||
// Then: Operation is blocked with TIER-0
|
||||
expect(result.allowed).toBe(false);
|
||||
expect(result.tier).toBe('TIER-0');
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 💡 Best Practices
|
||||
|
||||
### Test Independence
|
||||
|
||||
**EACH TEST SHOULD**:
|
||||
- Run independently (no order dependency)
|
||||
- Create own test data
|
||||
- Clean up after itself
|
||||
- Not share state with other tests
|
||||
|
||||
### Test Data
|
||||
|
||||
**PREFER**:
|
||||
- Inline test data (visible in test)
|
||||
- Fixtures for large data
|
||||
- Factories for object creation
|
||||
- Mocks for external dependencies
|
||||
|
||||
**AVOID**:
|
||||
- Shared mutable state
|
||||
- Real external services (use mocks)
|
||||
- Hard-coded file paths (use temp directories)
|
||||
|
||||
### Mocking
|
||||
|
||||
**WHEN TO MOCK**:
|
||||
- External services (APIs, databases)
|
||||
- File system operations (use in-memory)
|
||||
- Network requests
|
||||
- Time-dependent operations
|
||||
|
||||
**EXAMPLE**:
|
||||
```typescript
|
||||
import { vi } from 'vitest';
|
||||
|
||||
it('should call MCP server', async () => {
|
||||
// Mock fetch
|
||||
const fetchMock = vi.spyOn(global, 'fetch').mockResolvedValue({
|
||||
ok: true,
|
||||
json: async () => ({ allowed: false }),
|
||||
} as Response);
|
||||
|
||||
// Test
|
||||
const result = await mcpClient.validateOperation('write', 'file.ts');
|
||||
|
||||
// Verify
|
||||
expect(callToolMock).toHaveBeenCalledWith(
|
||||
'validate_operation',
|
||||
expect.objectContaining({ operation: 'write' })
|
||||
);
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📚 Quick Reference
|
||||
|
||||
| Aspect | Standard | Tool/Command |
|
||||
|--------|----------|--------------|
|
||||
| **Framework (MCP)** | Vitest | `npm test` |
|
||||
| **Framework (Extension)** | @vscode/test-electron | `npm test` |
|
||||
| **Coverage Target** | ≥70% overall | `npm run test:coverage` |
|
||||
| **Security Coverage** | 100% required | Security test suite |
|
||||
| **Pre-Commit** | All tests pass | CI/git hooks |
|
||||
| **TDD** | Preferred | Red-Green-Refactor |
|
||||
|
||||
---
|
||||
|
||||
*Testing & Quality Module v3.0.0*
|
||||
*Comprehensive testing standards for Virsaitis*
|
||||
|
||||
---
|
||||
|
||||
## Key Rules From This Module
|
||||
|
||||
- Coverage target: ≥70% overall, 100% for security-related code.
|
||||
- TDD preferred: Red → Green → Refactor. Write failing test first.
|
||||
- Every REQ-ID must have corresponding tests. Update traceability.csv.
|
||||
- All tests must pass before commit. No skipping, no force-push.
|
||||
- Definitions: `.github/virsaitis-definition-library.md`
|
||||
|
||||
Return to hub: `.github/copilot-instructions.md`
|
||||
Reference in New Issue
Block a user