Skip to content

Commit e94edb0

Browse files
author
Waldek Herka
committed
feat(lib): extract scaffold scripts into @prompt-registry/collection-scripts npm package
## Summary Extract all scaffold scripts into a shared npm package for reuse across collection repositories and the VS Code extension. This eliminates code duplication and ensures consistent validation/build logic. ## Changes ### New npm package: @prompt-registry/collection-scripts (lib/) - TypeScript library with CLI commands for collection management - Validation: validateCollectionFile, validateAllCollections, validateSkillFolder - Skills: createSkill, validateSkillName, generateSkillContent - Build: build-collection-bundle, compute-collection-version, publish-collections - Utilities: generateBundleId, CLI argument parsing - 93 unit tests covering all modules ### Scaffold template updates - Replace local scripts with npm package CLI commands - Add .npmrc.template for GitHub Packages authentication - Add packages:read permission and NODE_AUTH_TOKEN to CI workflows - Update package.template.json to use CLI commands (validate-collections, etc.) ### VS Code extension integration - Import validation functions from @prompt-registry/collection-scripts - Reference package via file:./lib for development ### CI/CD - Add lib-collection-scripts-ci.yml for package CI/CD - Add 'Build lib package' step to extension CI workflow - Configure GitHub Packages publishing on main branch ### Documentation - Add docs/author-guide/collection-scripts.md with usage and auth setup - Add docs/contributor-guide/spec-collection-scripts-lib.md specification - Update scaffold README with GitHub Packages authentication instructions ### Test updates - Update tests to expect npm package instead of local scripts - Add bundleIdSync test using npm package exports
1 parent b34062e commit e94edb0

File tree

64 files changed

+5003
-5028
lines changed

Some content is hidden

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

64 files changed

+5003
-5028
lines changed

‎.github/workflows/lib-collection-scripts-ci.yml‎

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
name: Collection Scripts Library CI
2+
3+
on:
4+
push:
5+
branches: [main, develop]
6+
paths:
7+
- "lib/**"
8+
pull_request:
9+
branches: [main, develop]
10+
paths:
11+
- "lib/**"
12+
workflow_dispatch:
13+
14+
permissions: read-all
15+
16+
env:
17+
NODE_VERSION: "20"
18+
19+
jobs:
20+
lint-and-test:
21+
name: Lint and Test
22+
runs-on: ubuntu-latest
23+
defaults:
24+
run:
25+
working-directory: lib
26+
27+
steps:
28+
- name: Checkout code
29+
uses: actions/checkout@v4
30+
31+
- name: Setup Node.js
32+
uses: actions/setup-node@v4
33+
with:
34+
node-version: ${{ env.NODE_VERSION }}
35+
cache: "npm"
36+
cache-dependency-path: "lib/package-lock.json"
37+
38+
- name: Install dependencies
39+
run: npm ci
40+
41+
- name: Build TypeScript
42+
run: npm run build
43+
44+
- name: Run tests
45+
run: npm test
46+
47+
publish:
48+
name: Publish to GitHub Packages
49+
runs-on: ubuntu-latest
50+
needs: lint-and-test
51+
if: github.ref == 'refs/heads/main' && github.event_name == 'push'
52+
permissions:
53+
contents: read
54+
packages: write
55+
defaults:
56+
run:
57+
working-directory: lib
58+
59+
steps:
60+
- name: Checkout code
61+
uses: actions/checkout@v4
62+
with:
63+
fetch-depth: 0
64+
65+
- name: Setup Node.js
66+
uses: actions/setup-node@v4
67+
with:
68+
node-version: ${{ env.NODE_VERSION }}
69+
cache: "npm"
70+
cache-dependency-path: "lib/package-lock.json"
71+
registry-url: "https://npm.pkg.github.com"
72+
73+
- name: Install dependencies
74+
run: npm ci
75+
76+
- name: Build TypeScript
77+
run: npm run build
78+
79+
- name: Check if version changed
80+
id: version-check
81+
run: |
82+
PACKAGE_VERSION=$(node -p "require('./package.json').version")
83+
echo "version=$PACKAGE_VERSION" >> $GITHUB_OUTPUT
84+
85+
# Check if this version tag already exists
86+
if git tag -l "collection-scripts-v$PACKAGE_VERSION" | grep -q .; then
87+
echo "exists=true" >> $GITHUB_OUTPUT
88+
else
89+
echo "exists=false" >> $GITHUB_OUTPUT
90+
fi
91+
92+
- name: Publish package
93+
if: steps.version-check.outputs.exists == 'false'
94+
run: npm publish
95+
env:
96+
NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
97+
98+
- name: Create version tag
99+
if: steps.version-check.outputs.exists == 'false'
100+
run: |
101+
git config user.name "github-actions[bot]"
102+
git config user.email "github-actions[bot]@users.noreply.github.com"
103+
git tag "collection-scripts-v${{ steps.version-check.outputs.version }}"
104+
git push origin "collection-scripts-v${{ steps.version-check.outputs.version }}"
105+
env:
106+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
107+
108+
- name: Skip publish (version exists)
109+
if: steps.version-check.outputs.exists == 'true'
110+
run: |
111+
echo "Version ${{ steps.version-check.outputs.version }} already published, skipping."

‎.github/workflows/vscode-extension-secure-ci.yml‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,13 +8,15 @@ on:
88
- "*.json"
99
- "*.js"
1010
- "*.ts"
11+
- "!lib/**"
1112
pull_request:
1213
branches: [main, develop]
1314
paths:
1415
- "src/**"
1516
- "*.json"
1617
- "*.js"
1718
- "*.ts"
19+
- "!lib/**"
1820
workflow_dispatch:
1921

2022
# Security: Restrict permissions to minimum necessary (SLSA Level 2)
@@ -53,6 +55,13 @@ jobs:
5355
cache: "npm"
5456
cache-dependency-path: "${{ env.EXTENSION_DIR }}/package-lock.json"
5557

58+
- name: Build lib package
59+
working-directory: lib
60+
shell: bash
61+
run: |
62+
npm ci --fund=false
63+
npm run build
64+
5665
- name: Install dependencies with audit
5766
working-directory: ${{ env.EXTENSION_DIR }}
5867
shell: bash
@@ -97,6 +106,12 @@ jobs:
97106
cache: "npm"
98107
cache-dependency-path: "package-lock.json"
99108

109+
- name: Build lib package
110+
working-directory: lib
111+
run: |
112+
npm ci --fund=false
113+
npm run build
114+
100115
- name: Install dependencies
101116
run: npm ci --fund=false
102117

@@ -156,6 +171,12 @@ jobs:
156171
cache: "npm"
157172
cache-dependency-path: "package-lock.json"
158173

174+
- name: Build lib package
175+
working-directory: lib
176+
run: |
177+
npm ci --fund=false
178+
npm run build
179+
159180
- name: Install dependencies
160181
run: npm ci --fund=false
161182

@@ -295,6 +316,12 @@ jobs:
295316
cache: "npm"
296317
cache-dependency-path: "package-lock.json"
297318

319+
- name: Build lib package
320+
working-directory: lib
321+
run: |
322+
npm ci --fund=false
323+
npm run build
324+
298325
- name: Install dependencies
299326
run: npm ci --fund=false
300327

‎.vscodeignore.production‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -148,6 +148,7 @@ INTEGRATION_TEST_*.md
148148
# Project-specific exclusions
149149
.specification/
150150
.tmp/
151+
lib/
151152

152153
# Test results
153154
test-results/

‎docs/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@ Marketplace and registry for Copilot prompt bundles in VS Code.
1919
## ✍️ For Collection Authors
2020

2121
- **[Creating Collections](author-guide/creating-source-bundle.md)** — How to create collections
22+
- **[Collection Scripts](author-guide/collection-scripts.md)** — Shared npm package for validation and building
2223
- **[Collection Schema](author-guide/collection-schema.md)** — YAML schema reference
2324
- **[Validation](author-guide/validation.md)** — Validating collections
2425
- **[Publishing](author-guide/publishing.md)** — Publishing to registries

‎docs/author-guide/collection-scripts.md‎

Lines changed: 156 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,156 @@
1+
# Collection Scripts Library
2+
3+
The Prompt Registry provides a shared npm package `@prompt-registry/collection-scripts` that contains all the scripts needed for building, validating, and publishing Copilot prompt collections.
4+
5+
## Installation
6+
7+
### Quick Setup with GitHub CLI (Recommended)
8+
9+
If you have the [GitHub CLI](https://cli.github.com/) installed:
10+
11+
```bash
12+
# Ensure you have packages scope (one-time)
13+
gh auth login --scopes read:packages
14+
15+
# Configure npm to use GitHub Packages
16+
npm config set @prompt-registry:registry https://npm.pkg.github.com
17+
npm config set //npm.pkg.github.com/:_authToken $(gh auth token)
18+
19+
# Install the package
20+
npm install @prompt-registry/collection-scripts
21+
```
22+
23+
### Manual Setup
24+
25+
1. Create or edit `.npmrc` in your project root:
26+
```
27+
@prompt-registry:registry=https://npm.pkg.github.com
28+
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}
29+
```
30+
31+
2. Set your GitHub token:
32+
```bash
33+
export GITHUB_TOKEN=<your-personal-access-token-with-read:packages>
34+
```
35+
36+
3. Install the package:
37+
```bash
38+
npm install @prompt-registry/collection-scripts
39+
```
40+
41+
### GitHub Actions (No Setup Required)
42+
43+
In GitHub Actions, authentication is automatic via `GITHUB_TOKEN`:
44+
45+
```yaml
46+
- name: Install dependencies
47+
run: npm ci
48+
env:
49+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
50+
```
51+
52+
## Usage in Collection Repositories
53+
54+
### NPM Scripts
55+
56+
The scaffolded repositories automatically include the necessary npm scripts:
57+
58+
```json
59+
{
60+
"scripts": {
61+
"validate": "validate-collections",
62+
"validate:verbose": "validate-collections --verbose",
63+
"build-collection-bundle": "build-collection-bundle",
64+
"publish-collections": "publish-collections",
65+
"list-collections": "list-collections",
66+
"compute-collection-version": "compute-collection-version",
67+
"skill:create": "create-skill",
68+
"build": "build-collection-bundle",
69+
"publish": "publish-collections"
70+
}
71+
}
72+
```
73+
74+
### Common Tasks
75+
76+
```bash
77+
# Validate all collections
78+
npm run validate
79+
80+
# Build a specific collection bundle
81+
npm run build-collection-bundle -- --collection-file collections/my.collection.yml --version 1.0.0
82+
83+
# Publish affected collections (used in CI)
84+
npm run publish-collections
85+
86+
# Create a new skill
87+
npm run skill:create my-new-skill
88+
```
89+
90+
## GitHub Actions Integration
91+
92+
The scaffolded GitHub Actions automatically use the npm package:
93+
94+
```yaml
95+
- name: Validate collections
96+
run: npm run validate -- --output-markdown validation-comment.md
97+
98+
- name: Publish affected collections
99+
run: npx publish-collections
100+
```
101+
102+
## VS Code Extension Integration
103+
104+
The Prompt Registry VS Code extension uses the same validation logic as the CLI tools, ensuring consistent behavior between the extension and command-line tools.
105+
106+
## Available Commands
107+
108+
| Command | Description |
109+
|---------|-------------|
110+
| `validate-collections` | Validate collection YAML files |
111+
| `validate-skills` | Validate skill folders against Agent Skills spec |
112+
| `build-collection-bundle` | Build a collection bundle ZIP |
113+
| `compute-collection-version` | Compute next version from git tags |
114+
| `detect-affected-collections` | Detect collections affected by file changes |
115+
| `generate-manifest` | Generate deployment manifest |
116+
| `publish-collections` | Build and publish affected collections |
117+
| `list-collections` | List all collections in repo |
118+
| `create-skill` | Create a new skill directory (interactive wizard) |
119+
120+
## Programmatic API
121+
122+
You can also use the library directly in your code:
123+
124+
```typescript
125+
import {
126+
validateCollectionFile,
127+
validateAllCollections,
128+
listCollectionFiles,
129+
generateBundleId
130+
} from '@prompt-registry/collection-scripts';
131+
132+
// Validate a single collection
133+
const result = validateCollectionFile(repoRoot, 'collections/my.collection.yml');
134+
135+
// List all collections
136+
const collections = listCollectionFiles(repoRoot);
137+
138+
// Generate a bundle ID
139+
const bundleId = generateBundleId('owner/repo', 'my-collection', '1.0.0');
140+
```
141+
142+
## Migration from Local Scripts
143+
144+
If you have an existing repository with local scripts:
145+
146+
1. Remove the `scripts/lib/` directory
147+
2. Update `package.json` to include the npm dependency
148+
3. Update npm scripts to use CLI commands directly
149+
4. The GitHub Actions will automatically use the npm package via `npx`
150+
151+
## Benefits
152+
153+
- **Single Source of Truth**: All repositories use the same validation logic
154+
- **Automatic Updates**: Bug fixes and improvements are available via npm updates
155+
- **Consistency**: Identical behavior between CLI, CI/CD, and VS Code extension
156+
- **Maintenance**: Centralized code reduces duplication and maintenance burden

0 commit comments

Comments
 (0)