Forge Space Core

Forge-Space Core Shared standards, patterns, and MCP context server for the Forge Space ecosystem.

[](https://github.com/Forge-Space/core/actions/workflows/ci.yml) [](https://opensource.org/licenses/MIT) [](https://www.typescriptlang.org/) [](CONTRIBUTING.md) [](https://www.npmjs.com/package/@forgespace/core)

Part of Forge Space — the open full-stack AI workspace. This repo provides the foundation that all other Forge Space projects build on: code quality standards, security framework, CI/CD workflows, and a local MCP context server for IDE integration.

Overview

Forge-Space Core provides shared configurations, workflows, and architectural patterns for consistency across the ecosystem. Centralized feature toggles, reusable GitHub Actions workflows (95% reduction in maintenance overhead), and comprehensive security validation.

Key Features

• 🔒 Zero Secrets: Public repository with comprehensive security validation
• 🏗️ Architectural Patterns: Proven patterns for scalable applications
• 🔄 Automation: Scripts and workflows for consistent project setup
• 📊 Quality Standards: 80% test coverage, linting, and security scanning
• 🛡️ Security First: Built-in security scanning and validation
• 🐳 Docker Patterns: Containerization and deployment patterns
• 🎛️ Centralized Feature Toggles: Cross-project feature management with CLI control
• 📡 MCP Context Server: Local stdio MCP server exposing all Forge Space project context documents as resources
• 📝 Logger Module: Comprehensive logging with observability and distributed tracing
• 🚀 High Performance: Sub-100ms integration times and optimized patterns
• 🔄 GitHub Workflows Optimization: Organization-level reusable workflows eliminating duplication
• 🔐 SHA-Pinned Automation: Workflow/action references use full commit SHAs for supply-chain safety

Tenant Isolation Standard

Forge-Space Core now defines an explicit tenant contract and enforces decoupling checks to keep platform code tenant-agnostic.

• Contract export: TenantProfile and validators from src/tenant/contract.ts
• Required profile keys:
• tenant_id
• github_owner
• sonar_org
• npm_scope
• quality_policy
• ci_policy
• CI guardrail: npm run check:tenant-decoupling
• Blocks tenant-specific hardcodes in platform paths (src, patterns, scripts, .github)
• Uses rg when available and automatically falls back to grep on constrained runners
• Allowed references should live in dedicated tenant profile repositories or explicit examples
• Works in CI/local environments with rg or grep fallback

Test Autogen — Phase 0 (Warn)

Phase 0 is active in warn-only mode to guide contributors without blocking delivery:

• Local hooks (.husky/pre-commit, .husky/pre-push) run forge-ai-init test-autogen only

when FORGE_TENANT_ID and FORGE_TENANT_PROFILE_REF are set, and always exit 0 in phase 0.

• Pull requests run CI job test-autogen-warn using forge-ai-action with:
• command: test-autogen-check
• tenant: acme-sandbox
• tenant_profile_ref: .forge-tenant-profiles/tenants/acme-sandbox/profile.yaml
• test_autogen_phase: warn
• PR feedback enabled (comment: true, annotations: true)
• Cross-repo profile checkout token: FORGE_TENANT_PROFILES_READ_TOKEN (fallback: GITHUB_TOKEN)
• External tenant profile checkout is best-effort; if unavailable, parity is skipped

and the warn-only flow remains non-blocking

This phase highlights missing tests early while preserving non-blocking developer flow.

Lint Toolchain Compatibility

Keep @typescript-eslint/eslint-plugin, @typescript-eslint/parser, and typescript-eslint on the same minor version to avoid npm ci peer-dependency resolution failures in CI.

📋 Projects Using These Patterns

• siza: Next.js web application with multi-environment deployment
• ui-mcp: MCP server for AI-powered UI generation
• mcp-gateway: Python/Node.js MCP gateway with comprehensive CI/CD
• branding-mcp: AI-powered brand identity generation
• siza-gen: AI generation engine with component registry

🌐 Ecosystem Integration

This core repository provides the foundation for the entire Forge Space ecosystem:

• 🔗 Shared Standards: Consistent coding patterns across all projects
• 🛡️ Security Framework: Unified security validation and scanning
• 🔄 Automation: Centralized workflows and CI/CD pipelines
• 📊 Quality Gates: Standardized testing and quality requirements

Related Projects:

• Siza - AI-powered full-stack workspace
• MCP Gateway - Central tool aggregation and routing
• ui-mcp - MCP server for UI generation

Documentation:

• [Documentation Hub](docs/README.md) - Complete documentation
• [Project Context](docs/project/PROJECT_CONTEXT.MD) - Project guide and context

IDP — Internal Developer Platform

CLI tools for project governance, shipped as part of @forgespace/core:

| Tool | Command | Purpose | |------|---------|---------| | Scorecard | npx forge-scorecard | Evaluate project quality across security, quality, performance, compliance | | Policy Engine | npx forge-policy | Enforce governance policies with block/warn/log actions | | Init | npx forge-init | Bootstrap governance for any project | | Feature Toggles | npx forge-features | Manage file-based feature toggles | | Audit | npx forge-audit | Assess legacy codebase migration readiness |

Runtime Import Safety

Importing @forgespace/core is side-effect free. Governance scaffolding runs only when forge-init is executed as a CLI command (npx forge-init or forge-init binary), not when the package is imported in application runtime code.

forge-audit evaluates 6 categories: dependencies, architecture, security, quality, migration-readiness, and ai-governance.

Quick Start

npx forge-init --template nextjs   # Next.js project with SSR + bundle policies
npx forge-init --template react    # React with accessibility + component coverage
npx forge-init --template node     # Node.js with dependency audit + API validation
npx forge-init                     # Base governance (no framework-specific rules)

npx forge-audit --dir /path/to/legacy-app       # Migration assessment
npx forge-audit --json --threshold 60            # CI gate mode

Guides

• [Scorecard Integration](docs/guides/scorecard-integration.md) — add quality scorecards to any repo
• [Policy Engine Integration](docs/guides/policy-engine-integration.md) — add policy checks to any repo
• [Security Spoke Contract v1](docs/guides/security-spoke-contract.md) — shared scanner output contract

Security Spoke Contract v1

Security scanner outputs across Forge Space use the canonical v1 contract in patterns/idp/security-spoke.

• Report schema:

patterns/idp/security-spoke/schema/security-spoke-report-v1.schema.json

• Rule catalog:

patterns/idp/security-spoke/rules/security-spoke-rules-v1.json

• Compatibility fixtures:

patterns/idp/security-spoke/fixtures/*.json

� GitHub Workflows Optimization

Canonical Workflow Source

Reusable workflows are now centralized in Forge-Space/.github. This repository (core) provides bootstrap orchestration and templates for new projects.

Limit-Aware CI (New Orgs + New Projects)

New projects generated by scripts/bootstrap/project.sh default to the limit-aware CI profile:

• baseline checks always run: lint, typecheck, unit tests, build, secret scan
• heavy jobs degrade when Actions usage crosses configured thresholds:
• Docker build
• E2E
• Semgrep
• Trivy
• CodeQL on PR
• nightly security workflow still runs heavy scans regardless of degrade mode

Bootstrap example:

./scripts/bootstrap/project.sh my-service node \
  --org Forge-Space \
  --actions-cap-minutes 20000

Initialize Actions budget variables for an org:

./scripts/bootstrap/actions-org-setup.sh \
  --org Forge-Space \
  --actions-cap-minutes 20000

Related Guides

1. [Organization Setup](docs/guides/organization-setup.md)
2. [Actions Limits Strategy](docs/guides/actions-limits-strategy.md)

� Documentation

For complete documentation, see our [Documentation Hub](docs/README.md) which includes:

• [Project Context](docs/project/PROJECT_CONTEXT.MD) - Complete project guide and context
• [Implementation Reports](docs/reports/) - Integration and analysis reports
• [Pattern Documentation](docs/patterns/) - All pattern documentation
• [Architecture Decisions](docs/architecture-decisions/) - System design decisions
• [User Guides](docs/guides/) - Deployment and user journey guides
• [MCP Context Server](docs/guides/MCPCONTEXTSERVER.md) - Setup and IDE integration for the Forge Space context MCP server
• [VSCode Extension](patterns/ide-extensions/vscode/README.md) - Pattern discovery, scaffolding, and compliance validation in VSCode
• [Development Standards](docs/standards/) - Coding and security standards

🚀 Quick Start

1. Install Forge Patterns

npm install @forgespace/core

Published on npm as @forgespace/core.

2. Integrate into Your Project

# Navigate to your project directory
cd /path/to/your-project
# Use the automated integration CLI
npx forge-patterns integrate

# Or use individual integration commands
npx forge-patterns integrate --project=mcp-gateway
npx forge-patterns integrate --project=siza-mcp
npx forge-patterns integrate --project=siza

--project=siza-mcp is the current integration CLI alias for the ui-mcp server in this repo.

Community

• Documentation hub
• GitHub Discussions

GitHub Workflow

This repository follows the shared Forge Space GitHub work-management baseline:

• Discussions for ideas, RFCs, Q&A, and announcements
• Issues for actionable delivery work
• Projects for roadmap visibility and cross-repo reporting

See Forge-Space/.github GOVERNANCE.md for the org-wide contract.

Funding Ops

The repo includes an NLnet packet generator for the mcp-gateway funding lane. Project facts stay in ops/funding/nlnet/project.json, while personal/contact details belong in the ignored ops/funding/nlnet/applicant.local.json.

cp ops/funding/nlnet/applicant.local.example.json ops/funding/nlnet/applicant.local.json
npm run funding:nlnet:render
npm run funding:nlnet:check

Generated artifacts land in ops/funding/nlnet/generated/ and stay redacted for workflow-safe issue updates and browser-assisted handoff.

• Issue tracker

📁 Repository Structure

forge-patterns/
├── .github/
│   ├── workflows/          # CI/CD workflow templates
│   └── templates/          # GitHub templates (PR, issues)
├── patterns/
│   ├── code-quality/       # ESLint, Prettier configurations
│   ├── config/            # Centralized configuration management
│   ├── docker/            # Docker and containerization patterns
│   ├── feature-toggles/   # 🎛️ Centralized feature toggle system
│   ├── git/               # Git hooks and workflows
│   ├── mcp-gateway/       # MCP Gateway patterns (security, performance)
│   ├── mcp-servers/       # MCP Server patterns (AI providers, streaming)
│   ├── security/          # Security patterns (authentication, middleware)
│   └── shared-infrastructure/ # Shared infrastructure patterns (optimization)
├── docs/                   # 📚 Comprehensive documentation
│   ├── architecture/       # Architecture decisions and summaries
│   ├── architecture-decisions/ # ADRs for system design
│   ├── guides/            # User guides and deployment playbooks
│   ├── standards/         # Development and security standards
│   └── reports/           # Implementation and analysis reports
├── test/                   # 🧪 Comprehensive test suites
│   ├── feature-toggle-validation.js # Feature toggle system tests
│   ├── cross-project-integration.js # Cross-project integration tests
│   └── performance-benchmark.js # Performance benchmarking
├── scripts/
│   ├── forge-features      # 🎛️ CLI tool for feature management
│   ├── integrate.js        # Automated integration script
│   ├── apply-readme-branding.sh     # Forge Space README header (CDN wordmark)
│   ├── apply-readme-branding-all.sh # Run branding for all Forge Space projects
│   ├── security/          # Security validation scripts
│   └── bootstrap/         # Project bootstrap scripts
├── src/                   # TypeScript source files
├── test/                  # 🧪 Comprehensive test suites
├── package.json           # Package configuration
└── README.md             # This file

🔧 Available Patterns

🎛️ Centralized Feature Toggle System

NEW: Cross-project feature management with unified control

# Enable global features
forge-features enable global.debug-mode
forge-features enable global.beta-features

# Enable project-specific features
forge-features enable mcp-gateway.rate-limiting
forge-features enable forge-space-ui.rate-limiting
forge-features enable forge-space-mcp.ai-chat
forge-features enable forge-space-ui.dark-mode

# Check feature status
forge-features status --global
forge-features status --project=mcp-gateway

Features:

• Global and project-specific feature namespaces
• CLI tool for feature management
• Real-time feature updates
• Cross-project consistency

Code Quality Patterns

ESLint Configuration

// Base ESLint config for TypeScript projects
module.exports = {
  root: true,
  extends: ['eslint:recommended', '@typescript-eslint/recommended', 'prettier'],
  // ... comprehensive rules
};

Prettier Configuration

{
  "semi": true,
  "trailingComma": "es5",
  "singleQuote": true,
  "printWidth": 100,
  "tabWidth": 2,
  "useTabs": false,
  "arrowParens": "always",
  "endOfLine": "lf"
}

Docker Patterns

NEW: High-Efficiency Docker Standards

# Three-state service model with sleep/wake architecture
services:
  [service-name]:
    resources:
      memory: "512M"
      cpu: "0.5"
      memory_reservation: "256M"
    sleep_policy:
      enabled: true
      idle_timeout: 300
      priority: "normal"
    auto_start: false

Multi-stage Dockerfile

# Build stage
FROM node:22-alpine AS builder
# ... build process

# Production stage
FROM node:22-alpine AS runtime
# ... optimized production image

Docker Compose Development

version: '3.8'
services:
  app:
    build: .
    ports:
      - "3000:3000"
    volumes:
      - .:/app
    command: npm run dev

Test Coverage Patterns

Jest Configuration (TypeScript)

module.exports = {
  collectCoverageFrom: ['src/**/*.ts'],
  coverageThreshold: {
    global: {
      branches: 80,
      functions: 80,
      lines: 80,
      statements: 80
    }
  }
};

Codecov Configuration

codecov:
  coverage:
    status:
      project:
        default:
          target: 80%
          threshold: 1%

Git Workflow Patterns

Pre-commit Hook

#!/bin/bash
# Comprehensive pre-commit validation
echo "🚀 Running Forge Space pre-commit validations..."
# Security validation, linting, testing, etc.

Conventional Commits

# Enforces conventional commit format
# feat, fix, docs, style, ref

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Forge-Space](https://github.com/Forge-Space)
- **Source:** [Forge-Space/core](https://github.com/Forge-Space/core)
- **License:** MIT
- **Homepage:** https://github.com/Forge-Space/core

Install and usage instructions live in the source repository linked above.