Skip to content

Commit 5871bcc

Browse files
chore: improve hephaestus messaging (#380)
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
1 parent 0dddad0 commit 5871bcc

13 files changed

Lines changed: 225 additions & 52 deletions

.github/workflows/ci-quality-gates.yml

Lines changed: 38 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,17 @@ jobs:
3636
with:
3737
fetch-depth: 0
3838

39+
# Ensure a stable Node/npm toolchain and proper npm caching
40+
- name: Setup Node.js (LTS) and npm cache
41+
uses: actions/setup-node@v4
42+
with:
43+
node-version-file: '.node-version'
44+
cache: 'npm'
45+
cache-dependency-path: |
46+
package-lock.json
47+
webapp/package-lock.json
48+
49+
3950
# Advanced cache setup with fallback
4051
- name: Setup shared caches
4152
uses: ./.github/actions/setup-caches
@@ -81,16 +92,28 @@ jobs:
8192
run: |
8293
echo "🔍 Running webapp quality checks..."
8394
84-
if [ ! -d "node_modules" ]; then
85-
npm ci --prefer-offline --no-audit --progress=false
86-
fi
95+
# Always install at repo root to ensure hoisted deps (incl. platform optionals) are present
96+
cd ..
97+
rm -rf node_modules
98+
npm ci --workspaces --include=dev --include=optional --no-audit --progress=false
99+
# Optional: report native package presence (warnings only) at the hoist root
100+
npm ls @rollup/rollup-linux-x64-gnu || echo "⚠️ rollup native not installed yet"
101+
npm ls @biomejs/cli-linux-x64 || echo "⚠️ biome binary not installed yet (will try npx fallback)"
102+
# Force-install platform binaries deterministically
103+
node scripts/install-platform-binaries.mjs
104+
cd webapp
87105
88106
ISSUES_FOUND=()
89107
90108
echo "🎨 Running Biome checks..."
91109
if ! npm run check; then
92-
echo "❌ Biome checks failed"
93-
ISSUES_FOUND+=("Biome checks failed. Run: npm run check -- --write")
110+
echo "❌ Biome checks failed (attempting npx fallback to platform-specific CLI)..."
111+
BIOME_VER=$(node -p "require('./package.json').devDependencies['@biomejs/biome'] || ''")
112+
if ! npx -y @biomejs/cli-linux-x64@${BIOME_VER:-latest} check; then
113+
ISSUES_FOUND+=("Biome checks failed. Run: npm run check -- --write")
114+
else
115+
echo "✅ Biome checks passed via pinned platform CLI fallback (${BIOME_VER:-latest})"
116+
fi
94117
else
95118
echo "✅ Biome checks passed"
96119
fi
@@ -105,8 +128,16 @@ jobs:
105128
106129
echo "🏗️ Running build check..."
107130
if ! npm run build; then
108-
echo "❌ Build check failed"
109-
ISSUES_FOUND+=("Build failed")
131+
echo "❌ Build failed (retrying after clean reinstall at root to pull any missed optionals)..."
132+
cd ..
133+
rm -rf node_modules
134+
npm ci --workspaces --include=dev --include=optional --no-audit --progress=false
135+
cd webapp
136+
if ! npm run build; then
137+
ISSUES_FOUND+=("Build failed")
138+
else
139+
echo "✅ Build passed after reinstall"
140+
fi
110141
else
111142
echo "✅ Build check passed"
112143
fi

.github/workflows/ci-security-scan.yml

Lines changed: 16 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,16 @@ jobs:
2828
with:
2929
fetch-depth: 0
3030

31+
# Ensure stable Node/npm and caching for Node steps used in SAST
32+
- name: Setup Node.js (LTS) and npm cache
33+
uses: actions/setup-node@v4
34+
with:
35+
node-version-file: '.node-version'
36+
cache: 'npm'
37+
cache-dependency-path: |
38+
package-lock.json
39+
webapp/package-lock.json
40+
3141
# SAST (Static Application Security Testing)
3242
- name: Initialize CodeQL
3343
if: matrix.scan-type == 'sast'
@@ -54,13 +64,12 @@ jobs:
5464
cd server/application-server
5565
mvn compile -DskipTests --quiet
5666
57-
# Node.js build
58-
cd ../../webapp
59-
60-
# Always install to avoid half-restored caches
61-
npm ci --prefer-offline --no-audit
62-
63-
npm run build
67+
# Node.js (webapp) - Type-only build for CodeQL; avoid bundle to reduce native deps
68+
cd ../..
69+
rm -rf node_modules
70+
npm ci --workspaces --include=dev --include=optional --no-audit --progress=false
71+
cd webapp
72+
npx tsc --noEmit
6473
6574
# Python dependencies
6675
cd ../server/intelligence-service

.github/workflows/ci-tests.yml

Lines changed: 27 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,16 @@ jobs:
2828
# Critical for TurboSnap: Ensure Chromatic can read full git history
2929
fetch-depth: 0
3030

31+
# Ensure stable Node/npm and proper caching for webapp visual tests
32+
- name: Setup Node.js (LTS) and npm cache
33+
uses: actions/setup-node@v4
34+
with:
35+
node-version-file: '.node-version'
36+
cache: 'npm'
37+
cache-dependency-path: |
38+
package-lock.json
39+
webapp/package-lock.json
40+
3141
# Advanced caching strategy
3242
- name: Setup advanced caches
3343
uses: ./.github/actions/setup-caches
@@ -63,11 +73,26 @@ jobs:
6373
working-directory: webapp
6474
run: |
6575
echo "🎨 Running webapp ${{ matrix.test-type }} tests"
66-
npm ci --prefer-offline --no-audit --progress=false
76+
# Install from repo root for workspace/hoisted optional deps
77+
cd ..
78+
rm -rf node_modules
79+
npm ci --workspaces --include=dev --include=optional --no-audit --progress=false
80+
# Optional: report Rollup native presence (warning only)
81+
npm ls @rollup/rollup-linux-x64-gnu || echo "⚠️ rollup native not installed yet"
82+
# Force-install platform binaries deterministically
83+
node scripts/install-platform-binaries.mjs
84+
cd webapp
6785
6886
case "${{ matrix.test-type }}" in
6987
"webapp-visual")
70-
npm run build-storybook
88+
if ! npm run build-storybook; then
89+
echo "❌ Storybook build failed (retrying after clean reinstall at root to pull any missed optionals)..."
90+
cd ..
91+
rm -rf node_modules
92+
npm ci --workspaces --include=dev --include=optional --no-audit --progress=false
93+
cd webapp
94+
npm run build-storybook
95+
fi
7196
;;
7297
esac
7398

.node-version

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
22.10.0

README.md

Lines changed: 9 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,9 @@
22
<img alt="Hephaestus Logo" height="100px" src="./docs/images/hammer_bg.svg">
33
</div>
44

5-
# Hephaestus: Forging Healthy Software Teams
5+
# Hephaestus — Process-Aware Mentoring for Agile Software Teams
66

7-
Our mission is simple: to empower novice software engineers and foster sustainable, collaborative development practices. Hephaestus is a growing platform designed to provide actionable toolslike code review gamification and AI-guided reflective sessions — that help teams continuously improve and stay focused on real-world challenges. While we're just getting started, our vision is to evolve into a comprehensive framework that nurtures agile, effective, and healthy software teams for the long term.
7+
Hephaestus is an open-source platform for process-aware mentoring that scaffolds self-regulated learning and onboarding for agile software teams. The platform focuses on the software processfrom issues to pull requests and team rituals — to bridge the theory–practice gap and help novices adopt industry best practices faster with less struggle. Heph is the platform’s conversational AI mentor that delivers repo-grounded guidance.
88

99
<img alt="Agile Hephaestus" height="200px" src="./docs/images/agile_hephaestus.png">
1010

@@ -21,10 +21,11 @@ Hephaestus /hɪˈfɛstəs/ is the Greek god of blacksmiths, craftsmen, and artis
2121

2222
- **Automated Recognition:** Celebrate excellence with weekly Slack notifications that honor the top three reviewers and link directly to the previous week's leaderboard.
2323

24-
2. **AI Mentor**
25-
- **Reflective Sessions:** Engage in AI-assisted weekly sessions that help you set, adjust, and achieve your goals through structured reflection.
26-
- **Automated Standups:** Convert insights from your reflective sessions into a structured weekly standup table for streamlined team communication.
27-
- **GitHub Activity Awareness:** Utilize the GitHub integration to provide context during reflective sessions, driving continuous improvement through objective, data-driven feedback.
24+
2. **Heph (Conversational AI Mentor)**
25+
26+
- **SRL-guided reflection:** Run structured, AI-assisted sessions that support self-regulated learning (goals → strategies → reflection) tailored to agile project work.
27+
- **Automated standups:** Turn weekly insights into a concise standup table to streamline team communication and accountability.
28+
- **Repo context awareness:** Ground guidance in actual activity (issues, commits, reviews, PRs) to deliver objective, data-informed feedback and next steps.
2829

2930
## Roadmap
3031

@@ -34,9 +35,9 @@ Hephaestus /hɪˈfɛstəs/ is the Greek god of blacksmiths, craftsmen, and artis
3435
- **Medium Term:** Expand multi-workspace capabilities to allow configuration of multiple organizations and selected open-source repositories, enabling seamless integration into diverse GitHub projects.
3536
- **Medium Term:** Integrate GitLab support to cater to self-hosted Git platforms, particularly for educational contexts.
3637
- **Medium Term:** Develop an advanced mentor prompt scheduler tailored for project-based courses, enabling daily reflective sessions and guided adaptation to evolving project requirements.
37-
- **Medium Term:** Enhance the gamification system with additional features and further expand the AI Mentor's capabilities.
38+
- **Medium Term:** Enhance the gamification system with additional features and further expand Heph's capabilities.
3839
- **Long Term:** Proactively integrate with GitHub and GitLab to deliver feedback directly via comments on issues or pull requests.
39-
- **Long Term:** Launch an peer-to-peer recognition system to reward high-quality reviews and establish a review quality assurance mechanism.
40+
- **Long Term:** Launch a peer-to-peer recognition system to reward high-quality reviews and establish a review quality assurance mechanism.
4041

4142
## Documentation
4243

docs/index.md

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Hephaestus: Forging Healthy Software Teams
1+
# Hephaestus — Process-Aware Mentoring for Agile Software Teams
22

33
```{figure} ./images/agile_hephaestus.png
44
:width: 200px
@@ -16,10 +16,12 @@ Hephaestus /hɪˈfɛstəs/ is the Greek god of blacksmiths, craftsmen, and artis
1616

1717
- **Automated Recognition:** Celebrate excellence with weekly Slack notifications that honor the top three reviewers and link directly to the previous week's leaderboard.
1818

19-
2. **AI Mentor**
20-
- **Reflective Sessions:** Engage in AI-assisted weekly sessions that help you set, adjust, and achieve your goals through structured reflection.
21-
- **Automated Standups:** Convert insights from your reflective sessions into a structured weekly standup table for streamlined team communication.
22-
- **GitHub Activity Awareness:** Utilize the GitHub integration to provide context during reflective sessions, driving continuous improvement through objective, data-driven feedback.
19+
2. **Heph (Conversational AI Mentor)**
20+
- **SRL-guided reflection:** Engage in AI-assisted sessions that support goal setting, strategy selection, and reflection aligned with agile rituals.
21+
- **Automated standups:** Convert insights into a structured weekly standup table for streamlined team communication.
22+
- **Repo context awareness:** Use GitHub activity to ground mentoring in issues, commits, reviews, and pull requests for objective, data-informed feedback.
23+
24+
Note: Hephaestus is the platform; Heph is the conversational AI mentor embedded in the platform.
2325

2426
```{toctree}
2527
:caption: User Guide

package-lock.json

Lines changed: 1 addition & 1 deletion
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.
Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
#!/usr/bin/env node
2+
import { createRequire } from 'node:module';
3+
import { execSync } from 'node:child_process';
4+
import { readFileSync } from 'node:fs';
5+
import path from 'node:path';
6+
7+
const require = createRequire(import.meta.url);
8+
9+
function log(msg) {
10+
console.log(`[platform-binaries] ${msg}`);
11+
}
12+
13+
function getVersionSafe(getter, label) {
14+
try {
15+
const v = getter();
16+
if (typeof v === 'string' && v.trim()) return v;
17+
} catch (e) {
18+
log(`WARN: Unable to resolve version for ${label}: ${e.message}`);
19+
}
20+
return '';
21+
}
22+
23+
// Detect platform triplet we support
24+
const isLinux = process.platform === 'linux';
25+
const isX64 = process.arch === 'x64';
26+
const suffix = isLinux && isX64 ? 'linux-x64-gnu' : '';
27+
28+
if (!suffix) {
29+
log('INFO: Non-linux/x64 platform detected; no native platform binaries to install.');
30+
process.exit(0);
31+
}
32+
33+
// Resolve versions from installed/declared packages
34+
const rollupVer = getVersionSafe(() => require('rollup/package.json').version, 'rollup');
35+
36+
function resolveLightningCssVersion() {
37+
// Try npm ls first (works well with workspaces)
38+
try {
39+
const out = execSync('npm ls lightningcss --json', { stdio: 'pipe' }).toString();
40+
const json = JSON.parse(out);
41+
if (json.dependencies && json.dependencies.lightningcss && json.dependencies.lightningcss.version) {
42+
return json.dependencies.lightningcss.version;
43+
}
44+
} catch {}
45+
// Fallback: resolve file path then read nearest package.json
46+
try {
47+
const entry = require.resolve('lightningcss/node/index.js');
48+
let dir = path.dirname(entry);
49+
while (dir && dir !== path.parse(dir).root) {
50+
const pj = path.join(dir, 'package.json');
51+
try {
52+
const data = JSON.parse(readFileSync(pj, 'utf8'));
53+
if (data.name === 'lightningcss' && data.version) return data.version;
54+
} catch {}
55+
dir = path.dirname(dir);
56+
}
57+
} catch {}
58+
return '';
59+
}
60+
61+
const lightningCssVer = resolveLightningCssVersion();
62+
const biomeVer = getVersionSafe(() => require('../webapp/package.json').devDependencies['@biomejs/biome'], '@biomejs/biome');
63+
64+
const pkgs = [];
65+
if (rollupVer) pkgs.push(`@rollup/rollup-${suffix}@${rollupVer}`);
66+
if (lightningCssVer) pkgs.push(`lightningcss-${suffix}@${lightningCssVer}`);
67+
// Biome CLI package naming does not include -gnu suffix
68+
if (biomeVer) pkgs.push(`@biomejs/cli-linux-x64@${biomeVer}`);
69+
70+
if (pkgs.length === 0) {
71+
log('INFO: No platform-specific packages to install (versions unresolved).');
72+
process.exit(0);
73+
}
74+
75+
log(`Installing platform binaries: ${pkgs.join(', ')}`);
76+
try {
77+
// Install at repo root to match hoisted module locations; avoid lockfile churn
78+
execSync(`npm i --no-save --no-audit --progress=false ${pkgs.join(' ')}`, {
79+
stdio: 'inherit',
80+
env: { ...process.env, npm_config_package_lock: 'false' },
81+
});
82+
} catch (e) {
83+
log(`ERROR: Failed to install platform binaries: ${e.status || ''}`);
84+
process.exit(1);
85+
}
86+
87+
// Verify presence
88+
const verifyPkgs = [
89+
'@rollup/rollup-linux-x64-gnu',
90+
'lightningcss-linux-x64-gnu',
91+
'@biomejs/cli-linux-x64',
92+
];
93+
94+
for (const p of verifyPkgs) {
95+
try {
96+
execSync(`npm ls ${p}`, { stdio: 'inherit' });
97+
} catch {
98+
log(`WARN: ${p} not found after install (may be unused or version unresolved).`);
99+
}
100+
}
101+
102+
log('Done installing platform-specific binaries.');

webapp/src/components/info/about/AboutHeroSection.tsx

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -10,8 +10,9 @@ export function AboutHeroSection() {
1010
About <span className="text-github-done-foreground">Heph</span>aestus
1111
</h1>
1212
<p className="text-xl text-muted-foreground max-w-2xl mx-auto">
13-
Hephaestus helps teams grow through healthy code review habits and
14-
personalized guidance. Meet Heph, our friendly AI mentor.
13+
Process-aware mentoring for agile software teams. Heph grounds guidance
14+
in your repository flow — issues, commits, reviews, and PRs — to
15+
scaffold self-regulated learning and better team habits.
1516
</p>
1617
</section>
1718
);

webapp/src/components/info/about/AboutMissionSection.tsx

Lines changed: 10 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -14,10 +14,10 @@ const FEATURES_DATA: FeatureData[] = [
1414
{
1515
icon: Sparkles,
1616
badge: "Core Feature",
17-
title: "AI-Powered Mentorship",
18-
description: "Your team's personalized guide",
17+
title: "Process-Aware AI Mentoring",
18+
description: "Guidance grounded in your repo activity",
1919
content:
20-
"Receive contextual guidance through Hephour AI mentor—that provides personalized feedback, identifies growth opportunities, and helps team members develop their skills with practical insights that lead to measurable improvement.",
20+
"Hephour AI mentor — delivers personalized, data-informed feedback based on issues, commits, reviews, and pull requests. It supports self-regulated learning with goal setting, reflection, and practical next steps.",
2121
},
2222
];
2323

@@ -32,15 +32,17 @@ export function AboutMissionSection() {
3232

3333
<div className="space-y-6">
3434
<p className="text-lg leading-relaxed">
35-
We empower novice software engineers and foster sustainable,
36-
collaborative development practices through smart gamification and
37-
AI guidance that adapts to your team's unique challenges.
35+
We help novice developers onboard and grow in agile, project-based
36+
courses by combining smart gamification with process-aware AI
37+
mentoring. Our guidance is grounded in your actual repository
38+
activity and supports self-regulated learning.
3839
</p>
3940

4041
<div className="border-l-4 border-primary pl-6 py-2">
4142
<p className="text-lg font-medium">
42-
We believe the best software isn't just about writing code — it's
43-
about building teams that bring out the best in each other.
43+
We believe the best software isn't just about code — it's about
44+
building teams that practice healthy habits and continuous
45+
reflection.
4446
</p>
4547
</div>
4648
</div>

0 commit comments

Comments
 (0)