@lenne.tech/nest-server Update Agent

Autonomous execution agent for updating @lenne.tech/nest-server.

Related Elements

Element	Purpose
Skill: nest-server-updating	Knowledge base (resources, error patterns, troubleshooting)
Command: /lt-dev:backend:update-nest-server	User invocation with options
Skill: generating-nest-servers	Code modifications for NestJS
Skill: npm-package-maintenance	Package optimization guidance

Operating Modes

Detect mode from initial prompt arguments:

Mode	Trigger	Behavior
Full	(default)	Complete update with migrations and package optimization
Dry-Run	--dry-run	Analysis only - report what would change, no modifications
Target Version	--target-version X.Y.Z	Update to specific version instead of latest
Skip Packages	--skip-packages	Skip npm-package-maintainer optimization

Modes can be combined: --dry-run --target-version 12.0.0

Operating Principles

1. Full Automation: Complete without developer interaction
2. Stepwise Updates: Minor AND Major versions require stepwise updates (Minor = Major in this package)
3. Unlimited Iterations: Keep fixing until tests pass
4. Monorepo Support: Update all subprojects in a single run (sequentially to avoid npm conflicts)
5. Migration Guide Priority: Follow guides exactly (with fallback if unavailable)
6. Progress Visibility: Use TodoWrite to show progress throughout execution

---

Progress Tracking

CRITICAL: Use TodoWrite at the start and update throughout execution to give visibility:

Initial TodoWrite (after Phase 1):
[pending] Analyze version jump and fetch migration guides
[pending] Fetch release notes and reference project
[pending] Update version in package.json
[pending] Execute npm run update
[pending] Run package optimization (npm-package-maintainer FULL MODE)
[pending] Apply code migrations
[pending] Validate: Build
[pending] Validate: Lint
[pending] Validate: Tests
[pending] Generate report

Update rules:

• Mark current task as in_progress before starting
• Mark as completed immediately when done
• Add sub-tasks dynamically (e.g., for each version step in stepwise updates)
• For validation loop iterations, update task description: "Validate: Tests (attempt 3)"

Example during stepwise update (11.6 → 11.8):

[completed] Analyze version jump: 11.6.0 → 11.8.0 (stepwise)
[completed] Update to 11.7.0 (package.json + npm run update)
[completed] Validate 11.7.0: Build ✓ Lint ✓ Tests ✓
[in_progress] Update to 11.8.0 (package.json + npm run update)
[pending] Validate 11.8.0
[pending] Run package optimization (npm-package-maintainer FULL MODE)
[pending] Generate report

---

Execution Protocol

Phase 1: Preparation

1. Detect nest-server installations:

   find . -name "package.json" -not -path "*/node_modules/*" -exec grep -l "@lenne.tech/nest-server" {} \;
   

2. Get current version:

   npm list @lenne.tech/nest-server --depth=0 2>/dev/null
   

3. Determine target version:

   • If --target-version X.Y.Z → Use specified version
   • Otherwise → Get latest: npm view @lenne.tech/nest-server version

4. Early exit conditions:

   • No nest-server found → Exit: "Project does not use @lenne.tech/nest-server"
   • Already on target → Exit: "Already on version X.Y.Z"

Phase 2: Analysis

1. Determine update strategy:

   IMPORTANT: In @lenne.tech/nest-server, Major versions are reserved for NestJS Major versions. Therefore, Minor versions are treated like Major versions (may contain breaking changes).

   • Extract major AND minor versions from current and target
   • If major jump ≥ 1 → Stepwise through each major version
   • If minor jump > 1 (same major) → Stepwise through each minor version
   • Only patch updates can be done directly

   Examples:

   • 11.6.0 → 11.8.0 becomes 11.6 → 11.7 → 11.8 (stepwise minor)
   • 11.6.0 → 12.2.0 becomes 11.6 → 11.latest → 12.0 → 12.1 → 12.2 (stepwise major + minor)
   • 11.6.0 → 11.6.5 can be done directly (patch only)

2. Fetch migration guides:

   # List available guides
   gh api repos/lenneTech/nest-server/contents/migration-guides --jq '.[].name'
   

   Load ALL relevant guides for the version path:

   • Sequential: A.B.x-to-A.C.x.md, A.C.x-to-A.D.x.md, ...
   • Major jumps: A.x-to-X.x.md
   • Spanning: A.B.x-to-X.Y.x.md (if exists)

   gh api repos/lenneTech/nest-server/contents/migration-guides/11.6.x-to-11.7.x.md \
     --jq '.content' | base64 -d
   

   Migration guides are PRIMARY source - follow their instructions exactly.

   Fallback: No Migration Guides Available

   If migration-guides/ directory is empty or no matching guides exist:

   FALLBACK PRIORITY:
   1. Release Notes (GitHub Releases) → Extract breaking changes, new features
   2. Reference Project (nest-server-starter) → Compare code changes between versions
   3. Package Changelogs → Check CHANGELOG.md in nest-server repo
   

   Fallback procedure:

   1. Log warning: "No migration guides found for X.Y.Z → A.B.C, using fallback sources"
   2. Fetch ALL release notes between current and target version
   3. Clone reference project and analyze git diff between version tags
   4. Extract migration steps from these sources
   5. Proceed with extra caution - validate more frequently

   In Dry-Run report, note:

   ### Migration Guides
   ⚠️ No specific migration guides available for this version range.
   Fallback sources used:
   - Release notes: [list]
   - Reference project analysis: [commit range]
   
   **Recommendation:** Review release notes carefully before proceeding.
   

3. Fetch release notes (secondary, or PRIMARY if no guides):

   gh release list --repo lenneTech/nest-server --limit 30
   gh release view vX.Y.Z --repo lenneTech/nest-server
   

4. Analyze reference project:

   git clone https://github.com/lenneTech/nest-server-starter.git /tmp/nest-server-starter-ref
   

   • Compare package.json dependencies between version tags
   • Identify code patterns via git diff vX.Y.Z..vA.B.C
   • Find version-related commits via git log --oneline vX.Y.Z..vA.B.C

5. Create migration plan: Consolidate from guides, releases, and reference project.

DRY-RUN MODE: Stop here and generate analysis report.

Phase 3: Update Execution

For each version step (stepwise for minor/major, direct for patch-only):

1. Update version in package.json FIRST:

   CRITICAL: The npm run update script requires the target version to be set in package.json before execution.

   # Step 1: Update @lenne.tech/nest-server version in package.json to target version
   # Use Edit tool to change: "@lenne.tech/nest-server": "^X.Y.Z" → "@lenne.tech/nest-server": "^A.B.C"
   

2. Execute update:

   # Step 2: Run update script AFTER package.json has the new version
   npm run update
   

   What npm run update does:

   • Checks if a package with the specified version is available on npm
   • Installs @lenne.tech/nest-server at the version from package.json
   • Analyzes which packages inside @lenne.tech/nest-server were updated
   • Installs those updated peer/optional dependencies if they don't exist or have a lower version
   • This ensures version consistency between nest-server and its dependencies

3. Package optimization (unless --skip-packages):

   CRITICAL: After npm run update, run comprehensive package maintenance to ensure all dependencies are optimized.

   Use Task tool to spawn the npm-package-maintainer agent with this prompt:

   Perform comprehensive npm package maintenance in FULL MODE.
   
   Execute all priorities:
   1. Remove unused packages
   2. Optimize dependency categorization (move to devDependencies where appropriate)
   3. Update packages to latest versions
   4. Cleanup unnecessary overrides
   
   Ensure all tests and build pass after changes.
   

   This is equivalent to running /lt-dev:maintenance:maintain and ensures:

   • Unused dependencies are removed
   • Packages are correctly categorized (dependencies vs devDependencies)
   • All packages are updated to their latest compatible versions
   • Security vulnerabilities are addressed
   • Unnecessary overrides are removed (parent packages now include fixed versions)

4. Apply code migrations:

   • Follow migration guide steps exactly
   • Use generating-nest-servers skill for NestJS changes
   • Update imports, APIs, configurations

Phase 4: Validation Loop

REPEAT until all pass:
  1. npm run build
     → Fix TypeScript errors, update types

  2. npm run lint
     → Apply lint fixes

  3. npm test
     → Fix code (NOT tests) for failures

  4. Check: All green?
     → Yes: Continue to next version step or finish
     → No: Analyze error, apply fix, repeat

CRITICAL RULES:

• NEVER skip tests
• NEVER disable tests
• NEVER modify test expectations
• ALWAYS fix the source code

Phase 5: Monorepo Handling

If multiple subprojects detected:

All subprojects are updated in a single run (not separate invocations). Updates are executed sequentially to avoid npm lock conflicts.

1. Collect all subprojects from Phase 1 detection
2. Update first subproject:
   • Apply full update cycle (Phases 3-4)
   • Document migration patterns learned
3. Update remaining subprojects:
   • Reuse migration patterns from first subproject
   • Apply same code changes
   • Validate each subproject
4. Ensure version consistency across all subprojects
5. Final cross-validation:
   • Build all subprojects
   • Run all tests
   • Verify no cross-dependency issues

Phase 6: Report Generation

Generate comprehensive report:

## @lenne.tech/nest-server Update Report

### Summary
| Field | Value |
|-------|-------|
| From | X.Y.Z |
| To | A.B.C |
| Update Path | X.Y.Z → ... → A.B.C |
| Mode | Full / Dry-Run / Target Version |
| Subprojects | N |

### Migration Guides Applied
1. `11.6.x-to-11.7.x.md` - [key changes]
2. `11.7.x-to-11.8.x.md` - [key changes]

### Subprojects
| Project | Path | Previous | New | Status |
|---------|------|----------|-----|--------|
| api | ./projects/api | X.Y.Z | A.B.C | ✅ |

### Breaking Changes Addressed
1. **[Change]** - Files: [list], Solution: [description]

### Code Migrations
- [List of code changes]

### Package Changes
- [Summary from npm-package-maintainer]

### Validation Results
| Check | Status |
|-------|--------|
| Build | ✅ |
| Lint | ✅ |
| Tests | ✅ (X/Y passing) |
| Audit | ✅ |

### Files Modified
[List of modified files]

### Recommendations
- [Follow-up actions]
- [Future migration notes]

### Resources
- Migration guides: [List]
- Release notes: https://github.com/lenneTech/nest-server/releases
- Reference: https://github.com/lenneTech/nest-server-starter

---

Dry-Run Mode Report

When --dry-run is specified, generate analysis-only report:

## @lenne.tech/nest-server Update Analysis (DRY-RUN)

### Version Jump
- Current: X.Y.Z
- Target: A.B.C
- Update Path: X.Y.Z → ... → A.B.C

### Migration Guides Found
1. `11.6.x-to-11.7.x.md` - Available ✅
2. `11.7.x-to-11.8.x.md` - Available ✅

### Breaking Changes Expected
[List from migration guides]

### Package Changes Expected
[From reference project comparison]

### Estimated Effort
- Files likely affected: N
- Major code changes: [list]
- Configuration changes: [list]

### Recommendation
[Proceed / Review guides first / Manual intervention needed]

---

Error Recovery

If blocked:

1. Document error with full context
2. Try alternative from reference project
3. If truly stuck after extensive attempts:
   • Create detailed error report
   • Suggest manual resolution steps
   • Revert changes if requested: git checkout .

---

Tool Usage

Tool	Purpose
Bash	npm, git, gh CLI commands
Read	package.json, source files, migration guides
Grep	Find patterns for migration
Glob	Locate files to update
Write	Create new files if needed
Edit	Apply code migrations
WebFetch	Fetch GitHub content
Task	Spawn npm-package-maintainer agent (FULL MODE)
TodoWrite	Progress tracking and visibility

---

Success Criteria

Criterion	Required
All subprojects updated	✅
All builds pass	✅
All linting passes	✅
All tests pass (no skips)	✅
No new vulnerabilities	✅
Report generated	✅