development

Development Guide

Prerequisites

Node.js 20+
npm (NOT pnpm - this project uses npm)
Git

Quick Start

# Clone repository
git clone https://gitlab.com/blueflyio/ossa/openstandardagents.org.git
cd openstandardagents.org

# Install dependencies
cd website
npm install

# Fetch content (required for data)
npm run fetch-spec
npm run fetch-examples
npm run fetch-versions
npm run fetch-highlights

# Start development server
npm run dev

Visit http://localhost:3000

Project Structure

openstandardagents.org/
 .gitlab/
    ci/                  # CI configuration files
       agent-communication.yml
       agent-orchestration.yml
       review-apps.yml
       scheduled-sync.yml
       website-automation.yml
    k8s/                 # Kubernetes manifests
        review-app.yaml
 website/                 # Next.js website
    app/                # App Router pages
    components/         # React components
    content/            # MDX content
    lib/                # Utilities
    public/             # Static assets
    scripts/            # Sync scripts
 .gitlab-ci.yml          # Main CI configuration
 Dockerfile              # Container build
 package.json            # Root dependencies

Development Workflow

Branch Strategy

main (protected)
  
release/v0.3.x (protected)
  
feature/your-feature (your work)

Create feature branch from release/v0.3.x
Make changes
Create MR targeting release/v0.3.x
After approval, merge to release
Release merges to main for deployment

Creating a Feature Branch

# Fetch latest
git fetch origin

# Create worktree for feature
git worktree add ../worktrees/feature-name release/v0.3.x
cd ../worktrees/feature-name

# Create feature branch
git checkout -b feature/my-feature

# Make changes...

# Push
git push -u origin feature/my-feature

Commit Messages

Follow conventional commits:

feat: add examples filter by category
fix: correct mobile navigation z-index
docs: update deployment guide
chore: update dependencies
refactor: simplify sync script

Available Scripts

Website ([object Object])

# Development
npm run dev           # Start dev server
npm run build         # Production build
npm run start         # Start production server
npm run lint          # Run ESLint
npm run typecheck     # TypeScript check

# Content Sync
npm run fetch-spec       # Fetch OSSA schema from npm
npm run fetch-examples   # Fetch examples from GitHub
npm run fetch-versions   # Fetch version metadata
npm run fetch-highlights # Fetch release notes
npm run sync-version     # Sync version references
npm run fix-versions     # Fix version mismatches

# Validation
npm run validate:links   # Check for broken links

Content Management

Adding Documentation

Create MDX file in website/content/docs/

Add frontmatter:

---
title: My Page
description: Page description
---

# My Page

Content here...

Update navigation in website/config/docs.ts if needed

Updating Examples

Examples are auto-synced from GitHub. To add new sources:

Edit website/scripts/fetch-examples.js
Add repository to EXAMPLE_SOURCES array
Run npm run fetch-examples

Updating Schema Documentation

Schema docs come from the @bluefly/ossa npm package:

Update schema in the OSSA package repo
Publish new version to npm
Run npm run fetch-spec or wait for auto-sync

Testing

Local Testing

cd website

# Lint
npm run lint

# Type check
npm run typecheck

# Build (catches build errors)
npm run build

CI Testing

Every MR runs:

ESLint + Prettier
TypeScript compilation
Build verification
Link validation
SEO checks
Accessibility checks

Common Tasks

Fix Linting Errors

cd website
npm run lint -- --fix

Update Dependencies

cd website
npm update
npm audit fix

Clear Cache

cd website
rm -rf .next
rm -rf node_modules
npm install

Debug Build Issues

cd website
npm run build 2>&1 | tee build.log
# Check build.log for errors

Environment Variables

Local Development

Create website/.env.local:

# Optional - for Google Analytics
NEXT_PUBLIC_GA_ID=G-XXXXXXXXXX

# Optional - for API testing
GITLAB_TOKEN=your-token

CI/CD Variables

Set in GitLab CI/CD Settings:

Variable	Description
`KUBECONFIG_LOCAL`	Base64 K8s config for review apps
`GITLAB_TOKEN`	API token for sync operations

Debugging

Check Synced Content

# Check examples
cat website/public/examples.json | jq '. | length'

# Check versions
cat website/lib/versions.json | jq '.'

# Check schema
ls -la website/content/spec/

View CI Logs

Go to GitLab CI/CD Pipelines
Click failed job
View job log

Local Docker Build

# Build image
docker build -t ossa-local .

# Run container
docker run -p 3000:3000 ossa-local

# Debug container
docker run -it ossa-local sh

Important Notes

Use npm, NOT pnpm

This project uses npm. There is no pnpm-lock.yaml.

# Correct
npm install
npm run dev

# Wrong - will fail
pnpm install

Shell Compatibility

CI runs on Alpine Linux with ash shell (not bash). When editing CI:

Use POSIX-compatible syntax
Escape quotes properly in JSON strings
Use \\n not \n for newlines in heredocs

Protected Branches

main - Requires MR, no direct push
release/* - Requires MR, no direct push
Feature branches - Direct push allowed

Getting Help

Wiki: This wiki
Issues: https://gitlab.com/blueflyio/ossa/openstandardagents.org/-/issues
CI Docs: https://docs.gitlab.com/ee/ci/