القائمة
Grafema release procedure for publishing new versions to npm. Covers happy path, pitfalls, rfdb binary lifecycle, and rollback. Use when user says "release", "publish", "bump version".
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
Fix RFDB V2 graph data silently not persisting to disk after analysis. Use when: (1) rfdb-server reports "0 nodes, 0 edges" on restart despite successful analysis, (2) segment directories exist but are empty (no .bin files), (3) manifest_index.json shows total_nodes: 0 despite analysis logging 70k+ nodes, (4) Docker builds produce empty graph databases, (5) --clear flag used before analyze command. Root cause: GraphEngineV2::clear() replaces the store with MultiShardStore::ephemeral() which has path: None, causing all flush operations to write to in-memory buffers only.
Fix missing theorem proof terms when analyzing Lean 4 environments via importModules. Use when: (1) ConstantInfo.value? returns none for theorems despite TheoremVal.value being Expr, (2) building code graph / dependency extractor for Lean 4 and getting 0 proof dependency edges, (3) Lean 4.30+ project where theorem proofs appear missing from loaded environment, (4) analyzing Mathlib or any Lean 4 project and proof terms are empty. Root cause: breaking change in Lean 4.30 — value? treats theorems as opaque by default.
Fix silent metadata issues in RFDB node storage. Covers two traps: (1) metadata flattening — nested metadata fields become top-level after serialization, so node.metadata.field is undefined but node.field works. (2) reserved keys — fields named "type", "id", "name", "file", "exported" are silently stripped from metadata by _parseNode() to prevent overwriting top-level node fields.
Diagnose React + Three.js (or any browser canvas) frame stutter by capturing a CDP CPU profile via Playwright instead of guessing from `[perf]` console logs. Use when: (1) frame time is bad but `[perf]` instrumentation doesn't pinpoint the offender, (2) you've spent more than ~30 minutes "fixing" suspects without measuring, (3) hot paths involve animation systems, allocation bursts, or invisible scene-graph traversal, (4) you need self-time per function with line numbers, not aggregate "render slow". The `console.warn` pattern is good for monitoring; CDP is needed for diagnosis. Covers script template, sourcemap setup so minified function names are decoded, and interactive variant where the user drives the interaction and signals stop via `touch /tmp/<flag>`.
Force `rust-embed` to re-embed assets from `$GRAFEMA_UI_DIST` (or any env-driven path) when cargo's incremental compilation skips the macro re-expansion. Use when: (1) you rebuilt the GUI bundle but the rust-server binary still serves the OLD bundle, (2) `cargo build --release` finishes in seconds (incremental hit) and `strings target/release/binary | grep <new-hash>` finds nothing, (3) any rust-embed pipeline where assets live outside the cargo source tree and are picked up via env var or symlink. Cargo only re-runs the proc macro when the rust file declaring `#[derive(RustEmbed)]` changes — env var changes alone don't trigger it.
Verify which process actually owns a TCP port before assuming your fresh restart succeeded. Use when: (1) you killed an old server and started a new one but behaviour matches the OLD code/data, (2) `pkill -f pattern` returned 0 but old behaviour persists, (3) you embedded a new asset/binary but the served version is stale, (4) any "I just restarted X but I'm getting old results" situation. `pkill -f` matches against the process command line — if the live old process was started with `--port 0` (auto-assigned) and got the port you now want, the pattern won't match it. Always verify with `lsof -i :PORT` before debugging deeper.
| name | grafema-release |
| description | Grafema release procedure for publishing new versions to npm. Covers happy path, pitfalls, rfdb binary lifecycle, and rollback. Use when user says "release", "publish", "bump version". |
| author | Claude Code |
| version | 3.0.0 |
| date | "2026-05-03T00:00:00.000Z" |
./scripts/release.sh patch --dry-run # Preview
./scripts/release.sh patch # Bump only
./scripts/release.sh 0.2.5-beta --publish # Bump and publish
main branch, clean working directorypnpm build — MUST run before tests (tests import from dist/)pnpm test — verify tests passnpm whoami — verify npm authIf releasing @grafema/rfdb, download prebuilt binaries BEFORE publishing:
git log $(git tag -l 'rfdb-v*' | sort -V | tail -1)..HEAD -- packages/rfdb-server/src/
git tag rfdb-v0.X.Y && git push origin rfdb-v0.X.Y./scripts/download-rfdb-binaries.sh rfdb-v0.X.Yls -la packages/rfdb-server/prebuilt/*/rfdb-server — must show 4 binariesnpm tags (v0.2.12-beta) and rfdb CI tags (rfdb-v0.2.12-beta) are independent. The release script doesn't check if binaries match current Rust source.
| Type | npm dist-tag |
|---|---|
patch / minor / major / 0.3.0 | latest |
prerelease / 0.2.5-beta | beta |
@grafema/types → @grafema/rfdb-client → @grafema/util → @grafema/mcp → @grafema/api → @grafema/cli → @grafema/rfdb
.gitignore pattern .grafema/* is anchored to root. Use **/.grafema/graph.rfdb/ for nested matches.
Release script runs tests BEFORE building. dist/ is stale. Fix: run pnpm build manually first.
macOS vs Linux rfdb-server may produce different graph output. Workaround: --skip-ci-check.
release.sh packages whatever is in prebuilt/. See "MANDATORY" section above.
release-validate.yml runs automatically (5-10 min)release-publish.yml manuallynpx @grafema/cli@<version> --versionnpm unpublish @grafema/cli@0.2.5-beta # within 72 hours
# or
npm deprecate @grafema/cli@0.2.5-beta "Use 0.2.4-beta instead"
git revert HEAD && git push origin main stable
git tag -d v0.2.5-beta && git push origin :refs/tags/v0.2.5-beta
## [0.X.Y-beta] - YYYY-MM-DD
### Highlights
### Features
### Bug Fixes
### Infrastructure
### Known Issues
npx @grafema/cli@latest --versionstable branch auto-updated by release script