🇺🇸English

Codervisor Forge

Complete toolkit for Rust+Node.js hybrid projects — from scaffolding to publishing.

Domains

When to Use This Skill

Activate when any of the following are true:

• Starting a new Rust+Node.js project or adding infrastructure to an existing one
• Working with .github/workflows/ in a repo with both Cargo.toml and package.json
• Publishing Rust binaries to npm or debugging publish pipeline failures
• Managing versions across workspace packages or Cargo.toml
• Working with pnpm workspace:* protocol
• Scripts matching *publish*, *platform*, *version*, or *sync* exist
• User says "bootstrap", "scaffold", "init", "set up a new project"

Decision Tree

What does the user need?

Starting a new project or scaffolding?
  → Bootstrap section below
  → Full tree: references/project-structure.md
  → Verify: references/checklist.md

Setting up or fixing CI?
  → CI/CD section below
  → Workflow templates: templates/workflows/

Publishing Rust binaries to npm?
  → Publishing section below
  → Pipeline details: references/publish-pipeline.md
  → Platform config: references/platform-matrix.md

Managing versions?
  → Versioning section below
  → Strategy: references/version-strategy.md
  → Workspace protocol: references/workspace-protocol.md

Debugging a failure?
  → references/troubleshooting.md

Bootstrap

Scaffold a new Rust+Node.js hybrid project with all forge infrastructure.

Gather Project Info

Scaffold Structure

See references/project-structure.md for the full annotated tree.

my-tool/
├── .github/workflows/       ← CI + publish workflows
├── .lean-spec/config.json   ← LeanSpec configuration
├── specs/                   ← Spec-driven development
├── packages/cli/            ← Main npm package (thin JS wrapper)
│   ├── package.json         ← bin + optionalDependencies
│   └── bin.js               ← Resolves platform binary, spawns it
├── rust/                    ← Rust workspace
├── scripts/                 ← Publish & version scripts
├── publish.config.ts        ← Publish pipeline configuration
├── package.json             ← Root (version source of truth)
├── pnpm-workspace.yaml      ← pnpm workspace definition
└── Cargo.toml               ← Rust workspace manifest

Generate Files (Order Matters)

1. Root configs — package.json, pnpm-workspace.yaml, Cargo.toml, turbo.json Use templates in templates/bootstrap/.
2. Publish config — publish.config.ts (drives script generation)
3. Main package wrapper — Copy bin.js + package.json from templates/wrapper/, fill in scope/binary name/platforms
4. Scripts — Copy from templates/scripts/

Verify

pnpm install && pnpm build && cargo check --workspace && pnpm tsx scripts/sync-versions.ts

See references/checklist.md for the full post-bootstrap checklist.

Install the LeanSpec Skill

After scaffolding, install the companion skill for spec-driven development:

npx skills add codervisor/lean-spec@leanspec-sdd -g -y

Bootstrap Decision Tree

Starting from scratch?
  YES → Full scaffold (all steps above)
  NO  → Incremental setup ↓

Has package.json?     → NO: Create root package.json + pnpm-workspace.yaml
Has Cargo.toml?       → NO: Create Cargo workspace
Has .github/workflows? → NO: Generate from templates/workflows/
Has scripts/?         → NO: Copy from templates/scripts/
Has specs/?           → NO: Initialize LeanSpec

CI/CD

Two-track CI for Rust+Node.js hybrid repos using GitHub Actions.

Architecture

┌─────────────┐     ┌──────────────────┐
│  Node Build  │     │   Rust Build     │
│  (test/lint) │     │  (per platform)  │
└──────┬──────┘     └────────┬─────────┘
       │                     │
       │   ┌─────────────┐   │
       └──►│  Artifacts   │◄──┘
           └──────┬──────┘
                  │
           ┌──────▼──────┐
           │   Publish    │
           └─────────────┘

Workflows

Templates: templates/workflows/

CI Jobs

Node job:

steps:
  - uses: codervisor/forge/actions/setup-workspace@v1
  - run: pnpm build
  - run: pnpm test
  - run: pnpm typecheck

Rust job:

steps:
  - uses: actions/checkout@v4
  - uses: dtolnay/rust-toolchain@stable
    with:
      components: clippy, rustfmt
  - run: cargo fmt --all -- --check
  - run: cargo clippy --workspace -- -D warnings
  - run: cargo test --workspace

Caching

• pnpm : actions/setup-node@v4 with cache: 'pnpm'
• Rust : Swatinem/rust-cache@v2
• Turbo : actions/cache@v4 on .turbo path

Reusable Actions

Publish Workflow Matrix

strategy:
  matrix:
    include:
      - { os: macos-latest,   target: x86_64-apple-darwin,      platform: darwin-x64 }
      - { os: macos-latest,   target: aarch64-apple-darwin,     platform: darwin-arm64 }
      - { os: ubuntu-22.04,   target: x86_64-unknown-linux-gnu, platform: linux-x64 }
      - { os: windows-latest, target: x86_64-pc-windows-msvc,   platform: windows-x64 }

Artifact Flow

# Upload from build job
- uses: actions/upload-artifact@v4
  with:
    name: binary-${{ matrix.platform }}
    path: target/${{ matrix.target }}/release/my-cli${{ matrix.platform == 'windows-x64' && '.exe' || '' }}

# Download in publish job
- uses: actions/download-artifact@v4
  with:
    pattern: binary-*
    path: artifacts/
    merge-multiple: false

Publishing

Distribute Rust binaries via npm using the optionalDependencies platform package pattern (same approach used by SWC, Turbopack, and similar tools).

The Pattern

@scope/my-tool                    ← main package (thin JS wrapper + bin.js)
├── optionalDependencies:
│   ├── @scope/my-tool-darwin-arm64   ← macOS ARM (M-series)
│   ├── @scope/my-tool-darwin-x64     ← macOS Intel
│   ├── @scope/my-tool-linux-x64      ← Linux x86_64
│   └── @scope/my-tool-windows-x64    ← Windows x86_64

Each platform package contains only the pre-compiled binary for that target. npm installs only the one matching the user's OS/CPU.

Configuration

Each repo provides a publish.config.ts (see examples/ for real configs):

export default {
  scope: '@myorg',
  binaries: [{ name: 'my-cli', scope: 'cli', cargoPackage: 'my-cli-rs' }],
  platforms: ['darwin-x64', 'darwin-arm64', 'linux-x64', 'windows-x64'],
  mainPackages: [{ path: 'packages/cli', name: 'my-cli' }],
  cargoWorkspace: 'Cargo.toml',
  repositoryUrl: 'https://github.com/myorg/my-project',
};

Publish Pipeline

sync-versions → generate-manifests → add-platform-deps → copy-binaries
→ validate-binaries → prepare-publish → validate-workspace → publish-platforms
→ wait-propagation → publish-main → restore-packages

Critical ordering : Platform packages MUST be published and propagated on npm before main packages, because main packages reference them as optionalDependencies.

See references/publish-pipeline.md for step-by-step details.

Main Package Wrapper

The main npm package is a thin JS wrapper — bin.js resolves the correct platform binary and spawns it. See templates/wrapper/ for the template.

Key details:

• process.platform returns win32 (not windows), so map win32-x64 → @scope/cli-windows-x64
• Use require.resolve('pkg/package.json') to find the platform package, then read main for the binary filename
• Use execFileSync and forward exit codes from the Rust binary
• The main package has NO os/cpu fields — it installs everywhere. Only platform packages use those.

Platform Package Manifests

Each platform package needs os and cpu fields plus a postinstall.js for chmod:

{
  "name": "@scope/cli-darwin-arm64",
  "os": ["darwin"],
  "cpu": ["arm64"],
  "main": "my-cli"
}

Adding a New Platform

1. Add to platforms array in publish.config.ts
2. Add Rust target: rustup target add <target-triple>
3. Add to CI matrix in publish workflow
4. Regenerate manifests: pnpm tsx scripts/generate-platform-manifests.ts

See references/platform-matrix.md for the full platform reference.

Versioning

Root package.json is the single source of truth for version. Everything derives from it.

root package.json (version: "0.2.15")
  ├── packages/cli/package.json        → 0.2.15
  ├── packages/sdk/package.json        → 0.2.15
  ├── Cargo.toml                       → 0.2.15
  └── platform-packages/*/package.json → 0.2.15

Never manually edit version in child packages or Cargo.toml. Always update root, then sync.

Version Sync Flow

npm version patch                     # Bump root: 0.2.15 → 0.2.16
pnpm tsx scripts/sync-versions.ts     # Propagate to all packages + Cargo.toml

Dev (Pre-release) Versioning

For non-release builds: 0.2.15 → 0.2.16-dev.{github_run_id}

• Bumps patch, appends -dev.{run_id} for unique, deterministic pre-release versions
• Published with --tag dev on npm (npm install my-cli@dev)

Workspace Protocol (workspace:*)

pnpm uses workspace:* for internal dependencies during development. These MUST be replaced with actual version numbers before publishing to npm:

pnpm tsx scripts/prepare-publish.ts                  # Replace workspace:* → real versions
pnpm tsx scripts/validate-no-workspace-protocol.ts   # Safety check
npm publish                                          # Publish
pnpm tsx scripts/restore-packages.ts                 # Restore workspace:*

Version Bump Guide

See references/version-strategy.md for the full strategy. See references/workspace-protocol.md for protocol details.

Platform Matrix

See references/platform-matrix.md for adding new platforms and binary validation.

Troubleshooting Quick Reference

See references/troubleshooting.md for detailed diagnostics and fixes.

Templates

References

Setup & Activation

Install via forge:

npx skills add codervisor/forge@codervisor-forge -g -y

Auto-activation hints

• Both Cargo.toml and package.json present at root
• .github/workflows/ directory exists
• pnpm-workspace.yaml present
• scripts/*publish* or scripts/*platform* files exist
• User mentions "bootstrap", "scaffold", "publish", "version sync"

Weekly Installs

0

Repository

codervisor/forge

First Seen

1 day ago

Security Audits

Gen Agent Trust HubPassSocketPassSnykWarn