Skip to content

Commit 865baa1

Browse files
author
fspec
committed
feat: add github actions for building napi binaries
1 parent 22ed071 commit 865baa1

16 files changed

Lines changed: 2848 additions & 63 deletions

‎.claude/commands/publish-codelet-napi.md‎

Lines changed: 181 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,181 @@
1+
# /publish-codelet-napi - Push Tag to Trigger CI Publishing
2+
3+
You are implementing the `/publish-codelet-napi` slash command for publishing `@sengac/codelet-napi` to npm via GitHub Actions CI.
4+
5+
**Note:** Unlike fspec, codelet-napi publishing is handled by CI. This command pushes the tag which triggers the build and publish workflow.
6+
7+
## Critical Requirements
8+
9+
### Pre-Publish Validation (MUST CHECK FIRST)
10+
11+
1. **Verify codelet-napi tag exists locally:**
12+
- Run `git describe --tags --match "codelet-napi-v*" --exact-match 2>/dev/null`
13+
- Parse version from tag (e.g., `codelet-napi-v0.2.0` → `0.2.0`)
14+
- If no tag, ABORT with error: "No codelet-napi tag found. Run /release-codelet-napi first."
15+
16+
2. **Verify package.json version matches:**
17+
- Read `codelet/napi/package.json`
18+
- Compare git tag version with package.json version
19+
- If mismatch, ABORT with error
20+
21+
3. **Check if already published to npm:**
22+
- Run `npm view @sengac/codelet-napi version 2>/dev/null || echo ""`
23+
- If npm version equals tag version:
24+
- Display: `Version {version} already published to npm. Skipping.`
25+
- Exit successfully (no action needed)
26+
27+
4. **Check if tag already pushed:**
28+
- Run `git ls-remote --tags origin | grep "codelet-napi-v{version}"`
29+
- If tag exists on remote, check CI status instead of pushing again
30+
31+
### Publishing (Push Tag)
32+
33+
1. **Push commits:**
34+
- Run `git push`
35+
36+
2. **Push tag:**
37+
- Run `git push origin codelet-napi-v{version}`
38+
39+
3. **Display CI link:**
40+
- Show GitHub Actions URL: `https://github.com/sengac/fspec/actions`
41+
- Explain what will happen
42+
43+
### Post-Push Monitoring (Optional)
44+
45+
After pushing, optionally check CI status:
46+
- Run `gh run list --workflow=build-codelet-napi.yml --limit=1`
47+
- Display current status
48+
49+
## Workflow Summary
50+
51+
```bash
52+
# 1. Version verification
53+
git describe --tags --match "codelet-napi-v*" --exact-match # Get current tag
54+
# Parse version from tag (codelet-napi-v0.2.0 → 0.2.0)
55+
# Read codelet/napi/package.json version
56+
# Compare (ABORT if mismatch)
57+
58+
# 2. Check npm registry
59+
npm view @sengac/codelet-napi version # Get published version
60+
# If already published, skip
61+
62+
# 3. Check if tag already on remote
63+
git ls-remote --tags origin | grep "codelet-napi-v{version}"
64+
65+
# 4. Push to trigger CI
66+
git push
67+
git push origin codelet-napi-v{version}
68+
69+
# 5. Display CI link
70+
echo "Monitor CI: https://github.com/sengac/fspec/actions"
71+
```
72+
73+
## Example Scenarios
74+
75+
### Scenario 1: Fresh release ready to publish
76+
```
77+
$ /publish-codelet-napi
78+
79+
Checking versions...
80+
Git tag: codelet-napi-v0.2.0
81+
package.json: 0.2.0
82+
npm registry: 0.1.0
83+
84+
✓ Versions match locally
85+
✓ New version detected (0.2.0 > 0.1.0)
86+
87+
Pushing to remote...
88+
git push
89+
git push origin codelet-napi-v0.2.0
90+
91+
✓ Tag pushed successfully!
92+
93+
═══════════════════════════════════════════════════════════
94+
CI Build Triggered: @sengac/codelet-napi v0.2.0
95+
═══════════════════════════════════════════════════════════
96+
97+
GitHub Actions is now:
98+
1. Building native binaries for 6 platforms (~5-10 min)
99+
2. Running smoke tests on each platform
100+
3. Publishing all packages to npm
101+
102+
Monitor progress:
103+
https://github.com/sengac/fspec/actions
104+
105+
Once complete, verify:
106+
npm view @sengac/codelet-napi version
107+
```
108+
109+
### Scenario 2: Already published
110+
```
111+
$ /publish-codelet-napi
112+
113+
Checking versions...
114+
Git tag: codelet-napi-v0.2.0
115+
package.json: 0.2.0
116+
npm registry: 0.2.0
117+
118+
✓ Versions match locally
119+
⚠ Version 0.2.0 already published to npm. Skipping.
120+
121+
No action needed. Package is up to date.
122+
```
123+
124+
### Scenario 3: No tag found
125+
```
126+
$ /publish-codelet-napi
127+
128+
Checking versions...
129+
✗ No codelet-napi tag found on current commit.
130+
131+
Run /release-codelet-napi first to create a release.
132+
```
133+
134+
### Scenario 4: Version mismatch
135+
```
136+
$ /publish-codelet-napi
137+
138+
Checking versions...
139+
Git tag: codelet-napi-v0.2.0
140+
package.json: 0.1.0
141+
142+
✗ Version mismatch detected!
143+
144+
Git tag (codelet-napi-v0.2.0) does not match package.json (0.1.0).
145+
Run /release-codelet-napi first to ensure versions are synchronized.
146+
```
147+
148+
### Scenario 5: Tag already pushed, CI in progress
149+
```
150+
$ /publish-codelet-napi
151+
152+
Checking versions...
153+
Git tag: codelet-napi-v0.2.0
154+
package.json: 0.2.0
155+
npm registry: 0.1.0
156+
157+
✓ Versions match locally
158+
✓ Tag already pushed to remote
159+
160+
Checking CI status...
161+
Workflow: Build codelet-napi
162+
Status: in_progress
163+
Started: 3 minutes ago
164+
165+
CI is still running. Monitor progress:
166+
https://github.com/sengac/fspec/actions
167+
```
168+
169+
## Error Handling
170+
171+
- **No git tag:** ABORT with error "No codelet-napi tag found. Run /release-codelet-napi first."
172+
- **Version mismatch:** ABORT with detailed error showing git tag vs package.json
173+
- **Push fails:** Display git error output, explain potential causes
174+
- **Network issues:** Catch and display connection errors
175+
176+
## Implementation Notes
177+
178+
- This command triggers CI, it doesn't publish directly
179+
- The actual npm publish happens in GitHub Actions after all 6 platforms build
180+
- Use `gh` CLI if available for checking CI status
181+
- Always display the Actions URL for manual monitoring

‎.claude/commands/release-codelet-napi.md‎

Lines changed: 152 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,152 @@
1+
# /release-codelet-napi - Create Tagged Release for codelet-napi
2+
3+
You are implementing the `/release-codelet-napi` slash command for creating tagged releases of the `@sengac/codelet-napi` native module.
4+
5+
**Note:** This is separate from the main fspec release. codelet-napi has its own version and release cycle.
6+
7+
## Critical Requirements
8+
9+
### Git Commit Author
10+
**MANDATORY**: ALL commits created by this command MUST use:
11+
- Author: `Roland Quast <rquast@rolandquast.com>`
12+
- Use `--author="Roland Quast <rquast@rolandquast.com>"` flag with git commit
13+
14+
### Pre-Release Validation (MUST RUN FIRST)
15+
16+
1. **Check for uncommitted changes:**
17+
- Run `git status --porcelain` to check for unstaged/staged files
18+
- If changes exist in `codelet/` directory, stage them: `git add codelet/`
19+
- Create commit with analyzed message and author `Roland Quast <rquast@rolandquast.com>`
20+
21+
2. **Run E2E publish test:**
22+
- Execute `npm run test:napi-publish`
23+
- This tests the full publish → install → load flow locally
24+
- If test fails, ABORT release with error message
25+
26+
### Version Determination
27+
28+
1. **Get last codelet-napi git tag:**
29+
- Run `git describe --tags --match "codelet-napi-v*" --abbrev=0 2>/dev/null || echo ""`
30+
- If no tag exists, use `codelet/napi/package.json` version as base
31+
32+
2. **Get commits since last tag:**
33+
- Run `git log <last-tag>..HEAD --oneline -- codelet/` (only codelet changes)
34+
- Parse conventional commit messages
35+
36+
3. **Determine semver bump:**
37+
- If any commit has `BREAKING CHANGE:` in body/footer → **major** bump
38+
- Else if any commit starts with `feat:` → **minor** bump
39+
- Else if any commit starts with `fix:` → **patch** bump
40+
- Else → **patch** bump (default)
41+
42+
4. **Calculate new version:**
43+
- Parse base version (from tag or package.json)
44+
- Apply semver bump to calculate new version
45+
46+
### Version Update
47+
48+
1. **Update codelet/napi/package.json:**
49+
- Update `"version"` field to new version
50+
- Update ALL versions in `optionalDependencies` to match:
51+
```json
52+
"optionalDependencies": {
53+
"@sengac/codelet-napi-darwin-arm64": "{new-version}",
54+
"@sengac/codelet-napi-darwin-x64": "{new-version}",
55+
"@sengac/codelet-napi-linux-arm64-gnu": "{new-version}",
56+
"@sengac/codelet-napi-linux-x64-gnu": "{new-version}",
57+
"@sengac/codelet-napi-win32-arm64-msvc": "{new-version}",
58+
"@sengac/codelet-napi-win32-x64-msvc": "{new-version}"
59+
}
60+
```
61+
62+
2. **Stage and commit:**
63+
- Run `git add codelet/napi/package.json`
64+
- Commit message: `chore(codelet-napi): release v{version}`
65+
- Use `--author="Roland Quast <rquast@rolandquast.com>"`
66+
67+
3. **Create git tag:**
68+
- Tag name: `codelet-napi-v{version}` (with `codelet-napi-v` prefix)
69+
- Run: `git tag -a codelet-napi-v{version} -m "Release @sengac/codelet-napi v{version}"`
70+
71+
### Post-Release
72+
73+
- **DO NOT push** to remote (manual step for user)
74+
- Display success message with:
75+
- New version number
76+
- Tag name created
77+
- Reminder to push: `git push && git push origin codelet-napi-v{version}`
78+
- Explanation that CI will build all 6 platforms and publish to npm
79+
80+
## Workflow Summary
81+
82+
```bash
83+
# 1. Pre-release validation
84+
git status --porcelain
85+
git add codelet/ # Stage codelet changes if any
86+
npm run test:napi-publish # E2E test (ABORT if fails)
87+
88+
# 2. Version determination
89+
git describe --tags --match "codelet-napi-v*" --abbrev=0 # Get last tag
90+
git log <last-tag>..HEAD --oneline -- codelet/ # Get codelet commits
91+
# Parse conventional commits, determine semver bump
92+
93+
# 3. Version update
94+
# Update codelet/napi/package.json version AND optionalDependencies
95+
git add codelet/napi/package.json
96+
git commit -m "chore(codelet-napi): release v{version}" --author="Roland Quast <rquast@rolandquast.com>"
97+
98+
# 4. Create tag
99+
git tag -a codelet-napi-v{version} -m "Release @sengac/codelet-napi v{version}"
100+
101+
# 5. Display success message (do NOT push)
102+
```
103+
104+
## Example Output
105+
106+
```
107+
$ /release-codelet-napi
108+
109+
Running E2E publish test...
110+
✓ E2E TEST PASSED
111+
112+
Analyzing commits since codelet-napi-v0.1.0...
113+
- feat: add new persistence API
114+
- fix: memory leak in session handling
115+
116+
Determined version bump: minor (0.1.0 → 0.2.0)
117+
118+
Updating codelet/napi/package.json...
119+
- version: 0.2.0
120+
- optionalDependencies: all updated to 0.2.0
121+
122+
Creating release commit...
123+
✓ Committed: chore(codelet-napi): release v0.2.0
124+
125+
Creating tag...
126+
✓ Created tag: codelet-napi-v0.2.0
127+
128+
═══════════════════════════════════════════════════════════
129+
Release Ready: @sengac/codelet-napi v0.2.0
130+
═══════════════════════════════════════════════════════════
131+
132+
To publish, run:
133+
git push && git push origin codelet-napi-v0.2.0
134+
135+
This will trigger GitHub Actions to:
136+
1. Build native binaries for all 6 platforms
137+
2. Run smoke tests on each platform
138+
3. Publish to npm:
139+
- @sengac/codelet-napi@0.2.0
140+
- @sengac/codelet-napi-darwin-arm64@0.2.0
141+
- @sengac/codelet-napi-darwin-x64@0.2.0
142+
- @sengac/codelet-napi-linux-arm64-gnu@0.2.0
143+
- @sengac/codelet-napi-linux-x64-gnu@0.2.0
144+
- @sengac/codelet-napi-win32-arm64-msvc@0.2.0
145+
- @sengac/codelet-napi-win32-x64-msvc@0.2.0
146+
```
147+
148+
## Error Handling
149+
150+
- If E2E test fails: Display error, ABORT release
151+
- If no codelet commits since last tag: Warn user, ask for confirmation
152+
- If cannot determine version: Display error with guidance

0 commit comments

Comments
 (0)