@bluefly/openstandardagents 0.2.4 → 0.2.5-RC

package/scripts/enhanced-version-manager.ts

@@ -0,0 +1,257 @@
+#!/usr/bin/env tsx
+/**
+ * Enhanced Version Manager Script
+ * 
+ * Integrates with GitLab agents for automated version management.
+ * Can run standalone or be invoked by GitLab agents.
+ * 
+ * Features:
+ * - GitLab API integration for milestone-based versioning
+ * - Automated MR creation
+ * - Version consistency validation
+ * - Documentation template processing
+ * - GitLab agent orchestration
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { execSync } from 'child_process';
+import { z } from 'zod';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// ============================================================================
+// Configuration
+// ============================================================================
+
+const VERSION_FILE = path.join(process.cwd(), '.version.json');
+const GITLAB_API_URL = process.env.CI_API_V4_URL || process.env.GITLAB_API_URL || 'https://gitlab.com/api/v4';
+// Use service account token (preferred) or fallback to user token
+const GITLAB_TOKEN = process.env.SERVICE_ACCOUNT_VERSION_MANAGER_TOKEN || 
+                      process.env.GITLAB_TOKEN || 
+                      process.env.GITLAB_PUSH_TOKEN || '';
+const PROJECT_ID = process.env.CI_PROJECT_ID || '';
+
+// ============================================================================
+// Zod Schemas
+// ============================================================================
+
+const VersionConfigSchema = z.object({
+  current: z.string(),
+  latest_stable: z.string(),
+  spec_path: z.string(),
+  schema_file: z.string(),
+});
+
+const BumpTypeSchema = z.enum(['major', 'minor', 'patch', 'rc', 'release']);
+
+type VersionConfig = z.infer<typeof VersionConfigSchema>;
+type BumpType = z.infer<typeof BumpTypeSchema>;
+
+// ============================================================================
+// Version Management
+// ============================================================================
+
+function getVersionConfig(): VersionConfig {
+  if (!fs.existsSync(VERSION_FILE)) {
+    throw new Error('.version.json not found');
+  }
+  const config = JSON.parse(fs.readFileSync(VERSION_FILE, 'utf-8'));
+  return VersionConfigSchema.parse(config);
+}
+
+function bumpVersion(current: string, type: BumpType): string {
+  const rcMatch = current.match(/^(\d+)\.(\d+)\.(\d+)-RC$/);
+  if (rcMatch) {
+    if (type === 'release') {
+      return `${rcMatch[1]}.${rcMatch[2]}.${rcMatch[3]}`;
+    }
+  }
+  
+  const match = current.match(/^(\d+)\.(\d+)\.(\d+)$/);
+  if (!match) throw new Error(`Invalid version format: ${current}`);
+  
+  let [, major, minor, patch] = match.map(Number);
+  
+  switch (type) {
+    case 'major':
+      return `${major + 1}.0.0`;
+    case 'minor':
+      return `${major}.${minor + 1}.0`;
+    case 'patch':
+      return `${major}.${minor}.${patch + 1}`;
+    case 'rc':
+      return `${major}.${minor}.${patch + 1}-RC`;
+    default:
+      throw new Error(`Unknown bump type: ${type}`);
+  }
+}
+
+// ============================================================================
+// GitLab Integration
+// ============================================================================
+
+async function getMilestoneVersion(milestoneId?: string): Promise<string | null> {
+  if (!milestoneId || !GITLAB_TOKEN || !PROJECT_ID) {
+    return null;
+  }
+
+  try {
+    const response = await fetch(
+      `${GITLAB_API_URL}/projects/${PROJECT_ID}/milestones/${milestoneId}`,
+      {
+        headers: {
+          'PRIVATE-TOKEN': GITLAB_TOKEN,
+        },
+      }
+    );
+
+    if (!response.ok) return null;
+
+    const milestone = await response.json();
+    const title = milestone.title || '';
+    
+    // Extract version from milestone title (e.g., "v0.2.6" or "0.2.6")
+    const versionMatch = title.match(/(\d+\.\d+\.\d+)/);
+    return versionMatch ? versionMatch[1] : null;
+  } catch (error) {
+    console.warn('Failed to fetch milestone:', error);
+    return null;
+  }
+}
+
+async function createMergeRequest(
+  sourceBranch: string,
+  targetBranch: string,
+  title: string,
+  description: string
+): Promise<number | null> {
+  if (!GITLAB_TOKEN || !PROJECT_ID) {
+    console.warn('GitLab credentials not available, skipping MR creation');
+    return null;
+  }
+
+  try {
+    const response = await fetch(
+      `${GITLAB_API_URL}/projects/${PROJECT_ID}/merge_requests`,
+      {
+        method: 'POST',
+        headers: {
+          'PRIVATE-TOKEN': GITLAB_TOKEN,
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({
+          source_branch: sourceBranch,
+          target_branch: targetBranch,
+          title,
+          description,
+          labels: ['version-bump', 'automated', 'chore'],
+          remove_source_branch: true,
+        }),
+      }
+    );
+
+    if (!response.ok) {
+      const error = await response.text();
+      throw new Error(`Failed to create MR: ${error}`);
+    }
+
+    const mr = await response.json();
+    return mr.iid;
+  } catch (error) {
+    console.error('Failed to create merge request:', error);
+    return null;
+  }
+}
+
+// ============================================================================
+// Main Execution
+// ============================================================================
+
+async function main() {
+  const args = process.argv.slice(2);
+  const bumpType = BumpTypeSchema.parse(args[0] || 'patch');
+  const milestoneId = process.env.CI_MILESTONE_ID || args[1];
+
+  console.log('🤖 Enhanced Version Manager');
+  console.log('===========================\n');
+
+  const config = getVersionConfig();
+  console.log(`📦 Current version: ${config.current}`);
+
+  // Try to get version from milestone
+  let targetVersion: string | null = null;
+  if (milestoneId) {
+    targetVersion = await getMilestoneVersion(milestoneId);
+    if (targetVersion) {
+      console.log(`🎯 Milestone version: ${targetVersion}`);
+    }
+  }
+
+  // Calculate new version
+  const newVersion = targetVersion || bumpVersion(config.current, bumpType);
+  console.log(`🚀 New version: ${newVersion}\n`);
+
+  // Update .version.json
+  config.latest_stable = config.current.replace('-RC', '');
+  config.current = newVersion;
+  fs.writeFileSync(VERSION_FILE, JSON.stringify(config, null, 2) + '\n');
+  console.log('✅ Updated .version.json');
+
+  // Run sync
+  console.log('\n📝 Syncing version references...');
+  execSync('npm run version:sync', { stdio: 'inherit' });
+
+  // Process docs
+  console.log('\n📚 Processing documentation templates...');
+  execSync('npm run docs:process', { stdio: 'inherit' });
+
+  // Validate
+  console.log('\n🔍 Validating version consistency...');
+  try {
+    execSync('npm run version:sync -- --check', { stdio: 'inherit' });
+    console.log('✅ Version consistency validated');
+  } catch (error) {
+    console.error('❌ Version consistency check failed');
+    process.exit(1);
+  }
+
+  // Git operations (if in CI or explicitly requested)
+  if (process.env.CI || process.argv.includes('--create-mr')) {
+    const targetBranch = process.env.CI_MERGE_REQUEST_TARGET_BRANCH_NAME || 'development';
+    const sourceBranch = `chore/version-bump-${newVersion}`;
+
+    console.log(`\n🌿 Creating branch: ${sourceBranch}`);
+    execSync(`git checkout -b ${sourceBranch}`, { stdio: 'inherit' });
+
+    console.log('\n📝 Committing changes...');
+    execSync('git add .', { stdio: 'inherit' });
+    execSync(`git commit -m "chore: bump version to ${newVersion}"`, { stdio: 'inherit' });
+
+    console.log('\n⬆️  Pushing branch...');
+    execSync(`git push -u origin ${sourceBranch}`, { stdio: 'inherit' });
+
+    console.log('\n🔀 Creating merge request...');
+    const mrId = await createMergeRequest(
+      sourceBranch,
+      targetBranch,
+      `chore: bump version to ${newVersion}`,
+      `Automated version bump to ${newVersion}\n\nTriggered by: ${milestoneId ? 'Milestone' : 'Manual'}\n\nChanges:\n- Updated .version.json\n- Synced package.json files\n- Updated documentation\n- Created spec/v${newVersion}/ directory`
+    );
+
+    if (mrId) {
+      console.log(`✅ Merge request created: !${mrId}`);
+    }
+  }
+
+  console.log('\n✅ Version management complete!');
+  console.log(`   ${config.current} → ${newVersion}`);
+}
+
+main().catch((error) => {
+  console.error('❌ Error:', error);
+  process.exit(1);
+});
+

package/scripts/gen-types.ts

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+/**
+ * Generate TypeScript types from current version schema
+ * 
+ * Follows OpenAPI-first, DRY, and type-safe principles.
+ * Uses Zod for validation and shared utilities.
+ */
+
+import { join } from 'path';
+import { fileURLToPath } from 'url';
+import { dirname } from 'path';
+import { getCurrentVersion, getSchemaPath, getTypesOutputPath } from './lib/version.js';
+import { requireFile, writeFile } from './lib/file-ops.js';
+import { execCommand } from './lib/exec.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const ROOT = join(__dirname, '..');
+
+async function main() {
+  try {
+    // Get version with validation
+    const version = getCurrentVersion();
+    console.log(`📦 Current version: ${version}`);
+    
+    // Build paths
+    const schemaPath = join(ROOT, getSchemaPath(version));
+    const outputPath = join(ROOT, getTypesOutputPath(version));
+    
+    // Validate schema exists
+    requireFile(schemaPath, `Schema not found at ${schemaPath}`);
+    console.log(`📄 Schema: ${schemaPath}`);
+    
+    // Generate types
+    console.log('🔄 Generating TypeScript types...');
+    const output = execCommand(`npx json-schema-to-typescript ${schemaPath}`, {
+      encoding: 'utf8',
+    });
+    
+    // Write output
+    writeFile(outputPath, output);
+    console.log(`✅ Generated: ${outputPath}`);
+    
+  } catch (error) {
+    console.error('❌ Error:', error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  }
+}
+
+main();
+

package/scripts/gen-zod.ts

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+/**
+ * Generate Zod schemas from current version schema
+ * 
+ * Follows OpenAPI-first, DRY, and type-safe principles.
+ * Uses Zod for validation and shared utilities.
+ */
+
+import { join } from 'path';
+import { fileURLToPath } from 'url';
+import { dirname } from 'path';
+import { getCurrentVersion, getSchemaPath, getZodOutputPath } from './lib/version.js';
+import { requireFile, writeFile } from './lib/file-ops.js';
+import { execCommand } from './lib/exec.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const ROOT = join(__dirname, '..');
+
+async function main() {
+  try {
+    // Get version with validation
+    const version = getCurrentVersion();
+    console.log(`📦 Current version: ${version}`);
+    
+    // Build paths
+    const schemaPath = join(ROOT, getSchemaPath(version));
+    const outputPath = join(ROOT, getZodOutputPath(version));
+    
+    // Validate schema exists
+    requireFile(schemaPath, `Schema not found at ${schemaPath}`);
+    console.log(`📄 Schema: ${schemaPath}`);
+    
+    // Generate Zod schemas
+    console.log('🔄 Generating Zod schemas...');
+    const output = execCommand(`npx json-schema-to-zod ${schemaPath}`, {
+      encoding: 'utf8',
+    });
+    
+    // Write output
+    writeFile(outputPath, output);
+    console.log(`✅ Generated: ${outputPath}`);
+    
+  } catch (error) {
+    console.error('❌ Error:', error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  }
+}
+
+main();
+

package/scripts/lib/exec.ts

@@ -0,0 +1,37 @@
+/**
+ * Execution Utilities
+ * 
+ * DRY: Reusable command execution with proper error handling
+ * Type-safe: Validates commands and handles errors
+ */
+
+import { execSync } from 'child_process';
+import { z } from 'zod';
+
+const CommandSchema = z.string().min(1);
+
+interface ExecOptions {
+  encoding?: BufferEncoding;
+  stdio?: 'inherit' | 'pipe';
+}
+
+/**
+ * Execute command with validation and error handling
+ */
+export function execCommand(
+  command: string,
+  options: ExecOptions = {}
+): string {
+  const validatedCommand = CommandSchema.parse(command);
+  
+  try {
+    const result = execSync(validatedCommand, {
+      encoding: options.encoding || 'utf8',
+      stdio: options.stdio || 'pipe',
+    });
+    return result as string;
+  } catch (error: any) {
+    const message = error?.message || 'Command execution failed';
+    throw new Error(`Command failed: ${validatedCommand}\n${message}`);
+  }
+}

package/scripts/lib/file-ops.ts

@@ -0,0 +1,58 @@
+/**
+ * File Operations Utilities
+ * 
+ * DRY: Reusable file operations with proper error handling
+ * Type-safe: Validates paths and operations
+ */
+
+import { readFileSync, writeFileSync, existsSync } from 'fs';
+import { z } from 'zod';
+
+const FilePathSchema = z.string().min(1);
+
+/**
+ * Read file with validation
+ */
+export function readFile(filePath: string): string {
+  const validatedPath = FilePathSchema.parse(filePath);
+  
+  if (!existsSync(validatedPath)) {
+    throw new Error(`File not found: ${validatedPath}`);
+  }
+  
+  try {
+    return readFileSync(validatedPath, 'utf8');
+  } catch (error) {
+    throw new Error(`Failed to read file ${validatedPath}: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
+/**
+ * Write file with validation
+ */
+export function writeFile(filePath: string, content: string): void {
+  const validatedPath = FilePathSchema.parse(filePath);
+  
+  try {
+    writeFileSync(validatedPath, content, 'utf8');
+  } catch (error) {
+    throw new Error(`Failed to write file ${validatedPath}: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
+/**
+ * Check if file exists
+ */
+export function fileExists(filePath: string): boolean {
+  const validatedPath = FilePathSchema.parse(filePath);
+  return existsSync(validatedPath);
+}
+
+/**
+ * Validate file exists or throw
+ */
+export function requireFile(filePath: string, errorMessage?: string): void {
+  if (!fileExists(filePath)) {
+    throw new Error(errorMessage || `Required file not found: ${filePath}`);
+  }
+}

package/scripts/lib/version.ts

@@ -0,0 +1,83 @@
+/**
+ * Version Management Utilities
+ * 
+ * DRY: Single source of truth for version operations
+ * Type-safe: Uses Zod for validation
+ */
+
+import { readFileSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { z } from 'zod';
+import {
+  PackageJsonSchema,
+  VersionSchema,
+  type PackageJson,
+  type Version,
+} from '../schemas/package.schema.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const ROOT = join(__dirname, '..', '..');
+
+/**
+ * Get current version from package.json with Zod validation
+ */
+export function getCurrentVersion(): Version {
+  const packageJsonPath = join(ROOT, 'package.json');
+  const content = readFileSync(packageJsonPath, 'utf8');
+  
+  try {
+    const json = JSON.parse(content);
+    const pkg = PackageJsonSchema.parse(json);
+    return VersionSchema.parse(pkg.version);
+  } catch (error) {
+    if (error instanceof z.ZodError) {
+      throw new Error(
+        `Invalid package.json version: ${error.errors.map((e) => e.message).join(', ')}`
+      );
+    }
+    throw error;
+  }
+}
+
+/**
+ * Get package.json with validation
+ */
+export function getPackageJson(): PackageJson {
+  const packageJsonPath = join(ROOT, 'package.json');
+  const content = readFileSync(packageJsonPath, 'utf8');
+  
+  try {
+    const json = JSON.parse(content);
+    return PackageJsonSchema.parse(json);
+  } catch (error) {
+    if (error instanceof z.ZodError) {
+      throw new Error(
+        `Invalid package.json: ${error.errors.map((e) => e.message).join(', ')}`
+      );
+    }
+    throw error;
+  }
+}
+
+/**
+ * Build schema path from version
+ */
+export function getSchemaPath(version: Version): string {
+  return `spec/v${version}/ossa-${version}.schema.json`;
+}
+
+/**
+ * Build output path for generated types
+ */
+export function getTypesOutputPath(version: Version): string {
+  return `src/types/generated/ossa-${version}.types.ts`;
+}
+
+/**
+ * Build output path for generated Zod schemas
+ */
+export function getZodOutputPath(version: Version): string {
+  return `src/types/generated/ossa-${version}.zod.ts`;
+}

package/scripts/process-doc-templates.ts

@@ -0,0 +1,37 @@
+#!/usr/bin/env tsx
+import fs from 'fs';
+import path from 'path';
+import { glob } from 'glob';
+
+const VERSION_FILE = path.join(process.cwd(), '.version.json');
+const versionConfig = JSON.parse(fs.readFileSync(VERSION_FILE, 'utf-8'));
+
+const replacements = {
+  '{{VERSION}}': versionConfig.current,
+  '{{VERSION_STABLE}}': versionConfig.latest_stable,
+  '{{SPEC_PATH}}': versionConfig.spec_path.replace('{version}', versionConfig.current),
+  '{{SCHEMA_FILE}}': versionConfig.schema_file.replace('{version}', versionConfig.current),
+};
+
+async function processTemplates() {
+  const files = await glob('website/content/docs/**/*.md', { ignore: 'node_modules/**' });
+  
+  for (const file of files) {
+    let content = fs.readFileSync(file, 'utf-8');
+    let updated = false;
+    
+    for (const [placeholder, value] of Object.entries(replacements)) {
+      if (content.includes(placeholder)) {
+        content = content.replaceAll(placeholder, value);
+        updated = true;
+      }
+    }
+    
+    if (updated) {
+      fs.writeFileSync(file, content);
+      console.log(`✅ Processed: ${file}`);
+    }
+  }
+}
+
+processTemplates();

package/scripts/schemas/package.schema.ts

@@ -0,0 +1,75 @@
+/**
+ * Shared Zod Schemas for Build Scripts
+ * 
+ * Follows OpenAPI-first, DRY, and type-safe principles.
+ * Single source of truth for package.json and version validation.
+ */
+
+import { z } from 'zod';
+
+/**
+ * Semantic version pattern (supports RC, alpha, beta, etc.)
+ * Matches: 0.2.5, 0.2.5-RC, 0.2.5-alpha.1, 1.0.0-beta.2, etc.
+ */
+const SemverPattern = /^\d+\.\d+\.\d+(-[a-zA-Z0-9.]+)?$/;
+
+/**
+ * Package.json schema (partial - only fields we use)
+ */
+export const PackageJsonSchema = z.object({
+  name: z.string().min(1),
+  version: z.string().regex(SemverPattern, {
+    message: 'Invalid semver version format. Expected: X.Y.Z or X.Y.Z-SUFFIX',
+  }),
+  exports: z
+    .object({
+      './schema': z.string().optional(),
+    })
+    .passthrough()
+    .optional(),
+}).passthrough();
+
+/**
+ * Version string schema
+ */
+export const VersionSchema = z.string().regex(SemverPattern, {
+  message: 'Invalid version format',
+});
+
+/**
+ * File path schema
+ */
+export const FilePathSchema = z.string().min(1);
+
+/**
+ * Script configuration schema
+ */
+export const ScriptConfigSchema = z.object({
+  version: VersionSchema,
+  schemaPath: FilePathSchema,
+  outputPath: z.string().optional(),
+  rootDir: FilePathSchema,
+});
+
+// Type exports
+export type PackageJson = z.infer<typeof PackageJsonSchema>;
+export type Version = z.infer<typeof VersionSchema>;
+export type ScriptConfig = z.infer<typeof ScriptConfigSchema>;
+
+/**
+ * Parse and validate package.json
+ */
+export function parsePackageJson(content: string): PackageJson {
+  try {
+    const json = JSON.parse(content);
+    return PackageJsonSchema.parse(json);
+  } catch (error) {
+    if (error instanceof z.ZodError) {
+      throw new Error(
+        `Invalid package.json: ${error.issues.map((e: z.ZodIssue) => e.message).join(', ')}`
+      );
+    }
+    throw error;
+  }
+}
+

package/scripts/setup-branch-protection.sh

@@ -0,0 +1,33 @@
+#!/bin/bash
+#
+# Setup Branch Protection
+# Installs git hooks to prevent checking out main/development locally
+#
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+echo "🔒 Setting up branch protection for main and development..."
+
+# Ensure hooks directory exists
+mkdir -p "$PROJECT_ROOT/.git/hooks"
+
+# Copy hooks if they don't exist or are outdated
+if [ ! -f "$PROJECT_ROOT/.git/hooks/post-checkout" ] || [ "$PROJECT_ROOT/.git/hooks/post-checkout" -ot "$SCRIPT_DIR/setup-branch-protection.sh" ]; then
+  echo "✅ Installing post-checkout hook..."
+  # Hook is already installed, just ensure it's executable
+  chmod +x "$PROJECT_ROOT/.git/hooks/post-checkout" 2>/dev/null || true
+fi
+
+# Set git config for hooks
+git config core.hooksPath .git/hooks 2>/dev/null || true
+
+echo ""
+echo "✅ Branch protection installed!"
+echo ""
+echo "Protected branches: main, development"
+echo ""
+echo "The hook will automatically switch you back if you try to checkout these branches."
+echo ""