@massu/core 0.1.2 → 0.4.0

package/commands/massu-deps.md

@@ -0,0 +1,374 @@
+---
+name: massu-deps
+description: Dependency audit covering security vulnerabilities, updates, and compatibility analysis
+allowed-tools: Bash(*), Read(*), Grep(*), Glob(*)
+---
+name: massu-deps
+
+> **Shared rules apply.** Read `.claude/commands/_shared-preamble.md` before proceeding. CR-9 enforced.
+
+# Massu Deps: Dependency Audit Protocol
+
+## Objective
+
+Audit project dependencies for **security vulnerabilities**, outdated packages, and compatibility issues. Maintain a healthy, secure dependency tree.
+
+---
+
+## NON-NEGOTIABLE RULES
+
+- **Security first** - Critical/high vulnerabilities block deployment
+- **Compatibility check** - Verify updates don't break build
+- **Incremental updates** - Don't update everything at once
+- **Test after updates** - Build and type check required
+- **Document changes** - Track what was updated and why
+
+---
+
+## ZERO-GAP AUDIT LOOP
+
+**Dependency updates do NOT complete until a SINGLE COMPLETE AUDIT finds ZERO issues.**
+
+### The Rule
+
+```
+DEPENDENCY AUDIT LOOP:
+  1. Run ALL security and compatibility checks
+  2. Count vulnerabilities and issues found
+  3. IF issues > 0:
+       - Fix/update to address issues
+       - Re-run ENTIRE audit from Step 1
+  4. IF issues == 0:
+       - DEPENDENCIES VERIFIED
+```
+
+### Completion Requirement
+
+| Scenario | Action |
+|----------|--------|
+| Audit finds 3 vulnerabilities | Fix all 3, re-run ENTIRE audit |
+| Update breaks build | Fix compatibility, re-run ENTIRE audit |
+| Re-audit finds 0 issues | **NOW** dependencies verified |
+
+**Partial re-checks are NOT valid. The ENTIRE dependency audit must pass in a SINGLE run.**
+
+---
+
+## AUDIT SECTION 1: SECURITY VULNERABILITIES
+
+### 1.1 npm Audit (Root)
+```bash
+# Run full audit from root
+npm audit
+
+# Check for critical/high only
+npm audit --audit-level=high
+
+# Check packages/core specifically
+cd packages/core && npm audit
+```
+
+### 1.2 npm Audit (Website, if applicable)
+```bash
+# Website dependencies
+cd website && npm audit 2>/dev/null || echo "No website package"
+```
+
+### 1.3 Vulnerability Matrix
+```markdown
+### Security Vulnerabilities
+
+| Package | Location | Severity | Vulnerability | Fix Available | Action |
+|---------|----------|----------|---------------|---------------|--------|
+| [pkg] | core | CRITICAL | [CVE-XXXX] | YES/NO | UPDATE/REPLACE |
+| [pkg] | website | HIGH | [CVE-XXXX] | YES/NO | UPDATE/REPLACE |
+```
+
+### 1.4 Auto-fix (If Safe)
+```bash
+# Attempt automatic fix
+npm audit fix
+
+# Force fix (may have breaking changes - REVIEW FIRST)
+npm audit fix --force --dry-run  # Preview
+```
+
+---
+
+## AUDIT SECTION 2: OUTDATED PACKAGES
+
+### 2.1 Check Outdated
+```bash
+# Root outdated
+npm outdated
+
+# Core package outdated
+cd packages/core && npm outdated
+
+# Website outdated (if applicable)
+cd website && npm outdated 2>/dev/null
+```
+
+### 2.2 Outdated Matrix
+```markdown
+### Outdated Packages
+
+| Package | Current | Wanted | Latest | Location | Action |
+|---------|---------|--------|--------|----------|--------|
+| [pkg] | 1.0.0 | 1.0.5 | 2.0.0 | core | PATCH |
+| [pkg] | 2.1.0 | 2.1.0 | 3.0.0 | website | REVIEW |
+```
+
+### 2.3 Update Priority
+| Priority | Definition | Criteria |
+|----------|------------|----------|
+| **P0** | Security fix | Has vulnerability fix |
+| **P1** | Bug fix | Patch version, bug fixes |
+| **P2** | Minor update | New features, backward compatible |
+| **P3** | Major update | Breaking changes, needs migration |
+
+---
+
+## AUDIT SECTION 3: DEPENDENCY ANALYSIS
+
+### 3.1 Dependency Tree
+```bash
+# Full tree
+npm ls --depth=2
+
+# Find specific package
+npm ls [package-name]
+
+# Why is package installed?
+npm why [package-name]
+```
+
+### 3.2 Duplicate Detection
+```bash
+# Find duplicates
+npm dedupe --dry-run
+```
+
+### 3.3 Unused Dependencies
+```bash
+# Find potentially unused (packages/core)
+npx depcheck packages/core
+
+# Verify no phantom MCP SDK references (should be 0 — raw JSON-RPC 2.0)
+grep -rn "@modelcontextprotocol/sdk" packages/core/src/ --include="*.ts" | wc -l
+
+# Check better-sqlite3 usage
+grep -rn "better-sqlite3\|Database" packages/core/src/ --include="*.ts" | wc -l
+```
+
+### 3.4 Dependency Matrix
+```markdown
+### Dependency Analysis
+
+| Package | Direct | Versions | Used | Action |
+|---------|--------|----------|------|--------|
+| [pkg] | YES | 1 | YES | KEEP |
+| [pkg] | NO | 2 | - | DEDUPE |
+| [pkg] | YES | 1 | NO | REMOVE |
+```
+
+---
+
+## AUDIT SECTION 4: COMPATIBILITY CHECK
+
+### 4.1 Peer Dependencies
+```bash
+# Check peer dependency warnings
+npm ls 2>&1 | grep -i "peer dep\|WARN"
+```
+
+### 4.2 Engine Compatibility
+```bash
+# Check Node.js version requirement
+grep -A 5 '"engines"' packages/core/package.json
+
+# Current Node.js version
+node --version
+```
+
+### 4.3 TypeScript Compatibility
+```bash
+# Verify TypeScript version
+npx tsc --version
+
+# Check for type definition updates
+npm outdated | grep @types
+```
+
+---
+
+## AUDIT SECTION 5: UPDATE PROCESS
+
+### 5.1 Safe Update Order
+1. **Dev dependencies first** (lower risk)
+2. **Patch updates** (bug fixes only)
+3. **Minor updates** (backward compatible)
+4. **Major updates** (one at a time, test thoroughly)
+
+### 5.2 Post-Update Verification
+```bash
+# After EACH update:
+
+# 1. Type check
+cd packages/core && npx tsc --noEmit
+
+# 2. Build (includes hook compilation)
+npm run build
+
+# 3. Test
+npm test
+
+# 4. Pattern scanner
+bash scripts/massu-pattern-scanner.sh
+
+# 5. Security scanner
+bash scripts/massu-security-scanner.sh
+```
+
+### 5.3 Update Checklist
+```markdown
+### Package Update: [PACKAGE_NAME]
+
+- [ ] Reviewed changelog for breaking changes
+- [ ] Updated package: `npm install [pkg]@[version]`
+- [ ] Type check passes
+- [ ] Build passes
+- [ ] Tests pass
+- [ ] Pattern scanner passes
+```
+
+---
+
+## AUDIT SECTION 6: LOCK FILE INTEGRITY
+
+### 6.1 Lock File Check
+```bash
+# Verify lock file integrity
+npm ci
+
+# If issues, regenerate
+rm -rf node_modules package-lock.json
+npm install
+```
+
+---
+
+## DEPENDENCY REPORT FORMAT
+
+```markdown
+## MASSU DEPS AUDIT REPORT
+
+### Summary
+- **Date**: [timestamp]
+- **Total packages**: [N]
+- **Direct dependencies**: [N]
+- **Dev dependencies**: [N]
+
+### Security Status
+| Severity | Count | Action Required |
+|----------|-------|-----------------|
+| Critical | 0 | IMMEDIATE |
+| High | 0 | ASAP |
+| Moderate | 0 | PLANNED |
+| Low | 0 | DEFER |
+
+**Security Status: PASS / BLOCKED**
+
+### Outdated Packages
+| Priority | Count | Packages |
+|----------|-------|----------|
+| P0 Security | 0 | [list] |
+| P1 Patches | N | [list] |
+| P2 Minor | N | [list] |
+| P3 Major | N | [list] |
+
+### Updates Applied
+| Package | From | To | Breaking | Status |
+|---------|------|----|---------| -------|
+| [pkg] | X.X.X | Y.Y.Y | NO | PASS |
+
+### Verification
+| Check | Result |
+|-------|--------|
+| npm audit | PASS |
+| Type check | PASS |
+| Build | PASS |
+| Tests | PASS |
+| Pattern scanner | PASS |
+
+### Recommendations
+1. [Recommendation 1]
+2. [Recommendation 2]
+
+**DEPENDENCY HEALTH: GOOD / NEEDS ATTENTION / CRITICAL**
+```
+
+---
+
+## SESSION STATE UPDATE
+
+After audit, update `session-state/CURRENT.md`:
+
+```markdown
+## DEPS AUDIT SESSION
+
+### Audit
+- **Date**: [timestamp]
+- **Type**: Security / Full
+
+### Findings
+- Critical vulnerabilities: [N]
+- Outdated packages: [N]
+- Unused packages: [N]
+
+### Updates Applied
+- [package]: X.X.X -> Y.Y.Y
+
+### Status
+- All checks passing: YES/NO
+```
+
+---
+
+## QUICK COMMANDS
+
+```bash
+# Quick security check
+npm audit --audit-level=high
+
+# Quick outdated check
+npm outdated
+
+# Update all patches (safe)
+npm update
+
+# Fix vulnerabilities (safe)
+npm audit fix
+
+# Full clean install
+rm -rf node_modules package-lock.json && npm install
+
+# Check for duplicates
+npm dedupe --dry-run
+```
+
+---
+
+## START NOW
+
+1. Run npm audit for security
+2. Run npm outdated for updates
+3. Analyze dependency tree
+4. Check for duplicates and unused
+5. Plan update order (security first)
+6. Apply updates incrementally
+7. Verify after each update
+8. Produce dependency report
+9. Update session state
+
+**Remember: Security first, one update at a time, verify after each.**

package/commands/massu-doc-gen.md

@@ -0,0 +1,279 @@
+---
+name: massu-doc-gen
+description: Generate JSDoc comments, README sections, and API docs for undocumented code
+allowed-tools: Bash(*), Read(*), Write(*), Edit(*), Grep(*), Glob(*)
+---
+name: massu-doc-gen
+
+> **Shared rules apply.** Read `.claude/commands/_shared-preamble.md` before proceeding. CR-9, CR-35 enforced.
+
+# CS Doc Gen: Documentation Generation
+
+## Objective
+
+Scan the codebase for undocumented functions, modules, and exported types, then generate accurate JSDoc comments, README sections, and API reference docs. Only documentation is added — no logic is modified.
+
+**Usage**: `/massu-doc-gen` (full scan) or `/massu-doc-gen [area]` (focused: jsdoc, readme, api, config)
+
+---
+
+## NON-NEGOTIABLE RULES
+
+- **Documentation ONLY** — never change logic, only add or update comments and docs
+- **Accuracy over completeness** — only document what the code actually does; never invent behavior
+- **FIX ALL ISSUES ENCOUNTERED (CR-9)** — incorrect existing docs found during scan MUST be corrected
+- **Run type check after every file** — JSDoc tags must not introduce TS errors
+- **Read before writing** — always read the full function before writing its doc
+
+---
+
+## STEP 1: INVENTORY
+
+Enumerate all documentation gaps across the codebase.
+
+### 1a. Undocumented Functions (packages/core)
+
+```bash
+# Functions and methods without a preceding JSDoc block
+grep -n "^export function\|^export async function\|^  [a-zA-Z].*): " \
+  packages/core/src/*.ts | grep -v "__tests__" | while IFS=: read file line content; do
+  # Check if line above is */ (end of JSDoc)
+  prev=$((line - 1))
+  preceding=$(sed -n "${prev}p" "$file" 2>/dev/null)
+  if [[ "$preceding" != *"*/"* && "$preceding" != *"// "* ]]; then
+    echo "UNDOCUMENTED: $file:$line  $content"
+  fi
+done
+```
+
+### 1b. Exported Types Without Description
+
+```bash
+# Exported interfaces and types without a preceding JSDoc
+grep -n "^export interface\|^export type\|^export enum" \
+  packages/core/src/*.ts | grep -v "__tests__"
+```
+
+### 1c. Module-Level Doc Coverage
+
+```bash
+# Source modules without a top-of-file comment block
+for f in packages/core/src/*.ts; do
+  first_line=$(head -1 "$f")
+  if [[ "$first_line" != "/**"* && "$first_line" != "//"* ]]; then
+    echo "NO MODULE DOC: $f"
+  fi
+done
+```
+
+### 1d. Config Schema Coverage
+
+```bash
+# Config fields without description in massu.config.yaml
+cat massu.config.yaml 2>/dev/null | head -80
+```
+
+### 1e. Package Modules Without JSDoc
+
+```bash
+# Package modules without JSDoc exports
+for f in packages/core/src/*.ts; do
+  if ! grep -q "@description\|/\*\*" "$f"; then
+    echo "NO JSDOC: $f"
+  fi
+done
+```
+
+---
+
+## STEP 2: ANALYSIS
+
+For each undocumented item, read the source and classify the documentation needed:
+
+```markdown
+### Documentation Inventory
+
+| File | Item | Type | Priority | Action |
+|------|------|------|----------|--------|
+| [file] | [name] | function/type/module/endpoint | HIGH/MED/LOW | ADD_JSDOC/ADD_COMMENT/UPDATE_DOC |
+```
+
+**Priority Rules:**
+- HIGH: exported functions/types used by tools.ts or server.ts
+- MED: internal utilities with complex behavior
+- LOW: simple pass-through wrappers
+
+---
+
+## STEP 3: GENERATION
+
+Apply documentation in order of priority. Read the entire function/type before writing docs.
+
+### JSDoc Pattern for Functions
+
+```typescript
+/**
+ * Brief one-line description of what this function does.
+ *
+ * @param paramName - Description of the parameter
+ * @param anotherParam - Description with type context
+ * @returns Description of the return value
+ * @throws Description of error conditions, if any
+ *
+ * @example
+ * const result = doSomething('input', { option: true });
+ */
+export function doSomething(paramName: string, anotherParam: Options): Result {
+```
+
+### JSDoc Pattern for Types / Interfaces
+
+```typescript
+/**
+ * Brief description of what this type represents.
+ * Include usage context if non-obvious.
+ */
+export interface MyType {
+  /** Description of this field */
+  fieldName: string;
+  /** Description, including valid values if enum-like */
+  status: 'active' | 'inactive';
+}
+```
+
+### Module-Level Comment Pattern
+
+```typescript
+/**
+ * [module-name] — One-sentence description of module purpose.
+ *
+ * Responsibilities:
+ * - [Responsibility 1]
+ * - [Responsibility 2]
+ *
+ * @module [module-name]
+ */
+```
+
+### After Each File
+
+```bash
+# Verify no TypeScript errors introduced
+cd packages/core && npx tsc --noEmit 2>&1
+# MUST show same or fewer errors than baseline
+```
+
+---
+
+## STEP 4: README / API REFERENCE
+
+If `$ARGUMENTS` includes `readme` or `api`, generate structured docs:
+
+### README Section Template
+
+```markdown
+## [Module Name]
+
+[One-paragraph description of purpose and responsibilities.]
+
+### Exported Functions
+
+| Function | Parameters | Returns | Description |
+|----------|------------|---------|-------------|
+| `functionName(param)` | `param: Type` | `ReturnType` | Brief description |
+
+### Configuration
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `configKey` | `string` | `"default"` | What this controls |
+
+### Example
+
+\`\`\`typescript
+import { functionName } from './module-name.ts';
+const result = functionName('input');
+\`\`\`
+```
+
+### Config Schema Annotation
+
+For `massu.config.yaml`, add inline comments for undocumented fields:
+
+```yaml
+# Brief description of this section
+sectionName:
+  # Description of this field. Valid values: foo | bar | baz. Default: foo.
+  fieldName: value
+```
+
+---
+
+## STEP 5: VERIFICATION
+
+### Gate 1: Type Check (VR-TYPE)
+```bash
+cd packages/core && npx tsc --noEmit
+# MUST show 0 errors (or <= baseline before docs were added)
+```
+
+### Gate 2: Pattern Scanner (VR-PATTERN)
+```bash
+bash scripts/massu-pattern-scanner.sh
+# MUST exit 0
+```
+
+### Gate 3: All Tests (VR-TEST)
+```bash
+npm test
+# Documentation changes MUST NOT affect test results
+```
+
+---
+
+## COMPLETION REPORT
+
+```markdown
+## CS DOC GEN COMPLETE
+
+### Coverage Summary
+
+| Category | Before | After | Added |
+|----------|--------|-------|-------|
+| Documented functions | [N] | [N] | [+N] |
+| Documented types/interfaces | [N] | [N] | [+N] |
+| Modules with module-level doc | [N] | [N] | [+N] |
+| API endpoints with description | [N] | [N] | [+N] |
+| Config fields with annotation | [N] | [N] | [+N] |
+
+### Files Modified
+
+| File | Items Documented |
+|------|-----------------|
+| [file] | [list of items] |
+
+### Verification Gates
+| Gate | Status |
+|------|--------|
+| Type Safety | PASS (no new errors introduced) |
+| Pattern Scanner | PASS |
+| Tests | PASS ([N] passed, unchanged) |
+
+### Corrections Made (CR-9)
+| File | Issue | Fix Applied |
+|------|-------|------------|
+| [file] | [incorrect doc] | [correction] |
+
+### Next Steps
+- Review changes: `git diff`
+- Commit: `/massu-commit`
+```
+
+---
+
+## AUTO-LEARNING
+
+After generating documentation, record the pattern:
+1. Note what documentation was needed and why
+2. Update session state with files generated
+3. If a documentation gap pattern is discovered, note it for future reference