Skip to content

Commit b8ec8b7

Browse files
CoderrobCoderrob
committed
feat: add copyright notice and license information to validate-tool-metadata.ts
chore: update yarn.lock with new dependencies and versions for rollup plugins and related packages
1 parent 20d2758 commit b8ec8b7

File tree

128 files changed

+6109
-229
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

128 files changed

+6109
-229
lines changed

‎.github/workflows/build.yml‎

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
name: Build and Test
2+
3+
on:
4+
push:
5+
branches: [main, develop]
6+
pull_request:
7+
branches: [main]
8+
9+
jobs:
10+
build:
11+
runs-on: ubuntu-latest
12+
13+
strategy:
14+
matrix:
15+
node-version: [18.x, 20.x, 22.x]
16+
17+
steps:
18+
- uses: actions/checkout@v4
19+
20+
- name: Use Node.js ${{ matrix.node-version }}
21+
uses: actions/setup-node@v4
22+
with:
23+
node-version: ${{ matrix.node-version }}
24+
cache: "yarn"
25+
26+
- name: Install dependencies
27+
run: yarn install --frozen-lockfile
28+
29+
- name: Run linting
30+
run: yarn lint
31+
32+
- name: Run tests
33+
run: yarn test
34+
35+
- name: Build the project
36+
run: yarn build
37+
38+
- name: Validate build outputs
39+
run: yarn validate:build
40+
41+
- name: Test global installation (CommonJS)
42+
run: |
43+
# Test that the built CJS file can execute
44+
node dist/index.cjs --help || echo "Expected: needs env vars"
45+
46+
- name: Test global installation (ESM)
47+
run: |
48+
# Test that the built ESM file can execute
49+
node dist/index.mjs --help || echo "Expected: needs env vars"
50+
51+
- name: Upload build artifacts
52+
uses: actions/upload-artifact@v4
53+
with:
54+
name: build-artifacts-node-${{ matrix.node-version }}
55+
path: |
56+
dist/
57+
!dist/**/*.map
58+
retention-days: 7
59+
60+
# Job to test publishing (dry run)
61+
publish-test:
62+
runs-on: ubuntu-latest
63+
needs: build
64+
if: github.event_name == 'pull_request'
65+
66+
steps:
67+
- uses: actions/checkout@v4
68+
69+
- name: Use Node.js 20.x
70+
uses: actions/setup-node@v4
71+
with:
72+
node-version: 20.x
73+
cache: "yarn"
74+
75+
- name: Install dependencies
76+
run: yarn install --frozen-lockfile
77+
78+
- name: Build the project
79+
run: yarn build
80+
81+
- name: Test npm pack
82+
run: |
83+
npm pack --dry-run
84+
echo "✅ Package can be packed successfully"
85+
86+
- name: Verify package contents
87+
run: |
88+
echo "📦 Package contents that would be published:"
89+
npm pack --dry-run 2>/dev/null | grep -E "^\s*[0-9]+" || true

‎.github/workflows/release.yml‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
name: Release
2+
3+
on:
4+
push:
5+
tags:
6+
- "v*"
7+
8+
jobs:
9+
release:
10+
runs-on: ubuntu-latest
11+
12+
steps:
13+
- uses: actions/checkout@v4
14+
15+
- name: Use Node.js 20.x
16+
uses: actions/setup-node@v4
17+
with:
18+
node-version: 20.x
19+
cache: "yarn"
20+
registry-url: "https://registry.npmjs.org"
21+
22+
- name: Install dependencies
23+
run: yarn install --frozen-lockfile
24+
25+
- name: Run tests
26+
run: yarn test
27+
28+
- name: Build the project
29+
run: yarn build
30+
31+
- name: Validate build
32+
run: yarn validate:build
33+
34+
- name: Publish to NPM
35+
run: npm publish
36+
env:
37+
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
38+
39+
- name: Create GitHub Release
40+
uses: actions/create-release@v1
41+
env:
42+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
43+
with:
44+
tag_name: ${{ github.ref }}
45+
release_name: Release ${{ github.ref }}
46+
body: |
47+
## Changes in this Release
48+
49+
- Built with Rollup for optimized dual-format output
50+
- CommonJS and ESM bundles available
51+
- Global installation support via npm
52+
53+
## Installation
54+
55+
```bash
56+
npm install -g @coderrob/backstage-mcp-server
57+
```
58+
59+
## Usage
60+
61+
```bash
62+
backstage-mcp-server
63+
```
64+
draft: false
65+
prerelease: false

‎.npmignore‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
# Source files
2+
src/
3+
tsconfig*.json
4+
rollup.config.js
5+
jest.config.mjs
6+
eslint.config.js
7+
8+
# Development files
9+
*.test.ts
10+
*.spec.ts
11+
__mocks__/
12+
coverage/
13+
.vscode/
14+
15+
# Documentation (except main files)
16+
planning.md
17+
TODO.md
18+
19+
# Build artifacts not needed in package
20+
*.tsbuildinfo
21+
*.log
22+
node_modules/
23+
24+
# Git
25+
.git/
26+
.gitignore

‎DEPENDENCY_GUIDE.md‎

Lines changed: 215 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,215 @@
1+
# Dependency Management Guide
2+
3+
This document provides comprehensive guidance on managing dependencies in the Backstage MCP Server project.
4+
5+
## Overview
6+
7+
The project includes several tools and scripts for dependency management:
8+
9+
1. **Comprehensive Analysis**: `scripts/dependency-manager.sh` - Enterprise-grade dependency analysis
10+
2. **Quick Operations**: `scripts/deps.sh` - Simple helper for common tasks
11+
3. **Package Scripts**: Convenient yarn/npm commands for all operations
12+
13+
## Quick Start
14+
15+
### Immediate Health Check
16+
17+
```bash
18+
# Quick peer dependency check
19+
yarn deps:quick
20+
21+
# Full dependency analysis
22+
yarn deps:analyze
23+
24+
# Check for outdated packages
25+
yarn deps:outdated
26+
```
27+
28+
### Common Maintenance Tasks
29+
30+
```bash
31+
# Security audit
32+
yarn deps:audit
33+
34+
# Remove duplicate dependencies
35+
yarn deps:dedupe
36+
37+
# Safe patch-level updates
38+
yarn deps:update
39+
```
40+
41+
## Scripts Reference
42+
43+
### 1. Quick Helper (`scripts/deps.sh`)
44+
45+
Simple script for common dependency operations:
46+
47+
| Command | Description | Example |
48+
| ---------- | ----------------------------- | -------------------- |
49+
| `check` | Quick peer dependency check | `yarn deps:quick` |
50+
| `update` | Safe patch-level updates only | `yarn deps:update` |
51+
| `outdated` | Show outdated packages | `yarn deps:outdated` |
52+
| `dedupe` | Remove duplicate dependencies | `yarn deps:dedupe` |
53+
| `audit` | Security vulnerability scan | `yarn deps:audit` |
54+
| `analyze` | Run full dependency analysis | `yarn deps:analyze` |
55+
56+
### 2. Comprehensive Manager (`scripts/dependency-manager.sh`)
57+
58+
Enterprise-grade dependency analysis with advanced features:
59+
60+
| Option | Description | Example |
61+
| ----------- | ------------------------------ | ------------------------------------------- |
62+
| `--dry-run` | Analyze without making changes | `yarn deps:check` |
63+
| `--debug` | Verbose debugging output | `yarn deps:debug` |
64+
| `--backup` | Create dependency backup | `./scripts/dependency-manager.sh --backup` |
65+
| `--restore` | Restore from backup | `./scripts/dependency-manager.sh --restore` |
66+
67+
## Package Scripts Available
68+
69+
```json
70+
{
71+
"deps": "bash scripts/deps.sh", // Show help
72+
"deps:analyze": "bash scripts/dependency-manager.sh",
73+
"deps:audit": "bash scripts/deps.sh audit",
74+
"deps:check": "bash scripts/dependency-manager.sh --dry-run",
75+
"deps:debug": "bash scripts/dependency-manager.sh --debug",
76+
"deps:dedupe": "bash scripts/deps.sh dedupe",
77+
"deps:outdated": "bash scripts/deps.sh outdated",
78+
"deps:quick": "bash scripts/deps.sh check",
79+
"deps:update": "bash scripts/deps.sh update"
80+
}
81+
```
82+
83+
## Dependency Strategy
84+
85+
### Stable Version Matrix
86+
87+
The project maintains compatibility with these stable versions:
88+
89+
| Package | Version | Reason |
90+
| ----------------------- | --------- | --------------------------------------------- |
91+
| `@rollup/plugin-terser` | `^0.4.4` | Official Rollup v4 compatibility |
92+
| `rollup` | `^4.50.2` | Latest stable with ESM/CJS support |
93+
| `rollup-plugin-dts` | `^6.2.3` | TypeScript declaration bundling |
94+
| `typescript` | `^5.9.2` | Stable release with full feature set |
95+
| `yarn` | `4.4.0` | Modern package manager with workspace support |
96+
97+
### Update Policy
98+
99+
1. **Patch Updates**: Safe to apply automatically (`yarn deps:update`)
100+
2. **Minor Updates**: Review breaking changes before applying
101+
3. **Major Updates**: Test thoroughly in development environment
102+
4. **Security Updates**: Apply immediately regardless of version
103+
104+
### Peer Dependency Resolution
105+
106+
Common peer dependency conflicts and solutions:
107+
108+
```bash
109+
# Check for conflicts
110+
yarn deps:quick
111+
112+
# Full conflict analysis
113+
yarn deps:analyze --debug
114+
115+
# View peer dependency tree
116+
yarn why [package-name]
117+
```
118+
119+
## Build System Integration
120+
121+
The dependency management integrates with the Rollup build system:
122+
123+
### External Dependencies
124+
125+
- All `@backstage/*` packages are marked as external
126+
- Peer dependencies are automatically excluded from bundles
127+
- Warning suppression for external dependency resolution
128+
129+
### Declaration Bundling
130+
131+
- Single `dist/index.d.ts` file generated from all TypeScript declarations
132+
- External type references preserved for consumer compatibility
133+
134+
## Troubleshooting
135+
136+
### Common Issues
137+
138+
1. **Peer Dependency Warnings**
139+
140+
```bash
141+
yarn deps:quick # Check for conflicts
142+
yarn deps:analyze --debug # Detailed analysis
143+
```
144+
145+
2. **Outdated Packages**
146+
147+
```bash
148+
yarn deps:outdated # Show what's outdated
149+
yarn deps:update # Safe patch updates
150+
```
151+
152+
3. **Security Vulnerabilities**
153+
154+
```bash
155+
yarn deps:audit # Security scan
156+
yarn audit --fix # Auto-fix if available
157+
```
158+
159+
4. **Duplicate Dependencies**
160+
161+
```bash
162+
yarn deps:dedupe # Remove duplicates
163+
```
164+
165+
5. **Build Issues**
166+
167+
```bash
168+
yarn clean && yarn build # Clean rebuild
169+
yarn validate:build # Validate output
170+
```
171+
172+
### Debug Information
173+
174+
For detailed debugging information:
175+
176+
```bash
177+
# Full debug output
178+
yarn deps:debug
179+
180+
# Environment validation
181+
yarn deps:analyze --backup # Also creates environment snapshot
182+
```
183+
184+
## File Locations
185+
186+
- **Main Scripts**: `scripts/dependency-manager.sh`, `scripts/deps.sh`
187+
- **Configuration**: `package.json`, `yarn.lock`
188+
- **Build Config**: `rollup.config.js`
189+
- **Documentation**: `BUILD_SETUP.md`, this file
190+
191+
## Best Practices
192+
193+
1. **Regular Maintenance**
194+
- Run `yarn deps:quick` before major development sessions
195+
- Schedule weekly `yarn deps:outdated` reviews
196+
- Monthly security audits with `yarn deps:audit`
197+
198+
2. **Before Releases**
199+
- Full dependency analysis: `yarn deps:analyze`
200+
- Security audit: `yarn deps:audit`
201+
- Build validation: `yarn validate:build`
202+
203+
3. **Development Workflow**
204+
- Use `yarn deps:update` for safe updates
205+
- Test thoroughly after any dependency changes
206+
- Keep peer dependencies aligned with target Backstage versions
207+
208+
4. **Monitoring**
209+
- Set up automated dependency scanning in CI/CD
210+
- Monitor security advisories for used packages
211+
- Track update patterns for major dependencies
212+
213+
---
214+
215+
_This guide is part of the comprehensive dependency management system. For technical details, see the individual script files and `BUILD_SETUP.md`._

0 commit comments

Comments
 (0)