@bluefly/openstandardagents 0.1.9 → 0.2.5-RC

package/release.config.js

@@ -0,0 +1,79 @@
+export default {
+  branches: [
+    {
+      name: 'main',
+      channel: false, // Stable releases get 'latest' tag
+    },
+    {
+      name: 'development',
+      prerelease: 'dev',
+      channel: 'dev', // Dev releases get 'dev' tag
+    },
+  ],
+  repositoryUrl: 'https://github.com/blueflyio/openstandardagents.git',
+  plugins: [
+    [
+      '@semantic-release/commit-analyzer',
+      {
+        preset: 'angular',
+        releaseRules: [
+          { type: 'docs', scope: 'README', release: 'patch' },
+          { type: 'refactor', scope: 'core-*', release: 'minor' },
+          { type: 'refactor', release: 'patch' },
+          { type: 'chore', scope: 'deps', release: 'patch' },
+          // Version is determined automatically by commit analysis
+          // Milestones are used for planning and tracking, but version bump
+          // is controlled by commit messages (feat → minor, fix → patch, BREAKING → major)
+        ],
+        parserOpts: {
+          noteKeywords: ['BREAKING CHANGE', 'BREAKING CHANGES'],
+        },
+      },
+    ],
+    [
+      '@semantic-release/release-notes-generator',
+      {
+        preset: 'angular',
+        parserOpts: { noteKeywords: ['BREAKING CHANGE', 'BREAKING CHANGES'] },
+        writerOpts: { commitsSort: ['subject', 'scope'] },
+      },
+    ],
+    [
+      '@semantic-release/changelog',
+      {
+        changelogFile: 'CHANGELOG.md',
+        changelogTitle:
+          '# Changelog\n\nAll notable changes to OSSA (Open Standard for Scalable Agents) will be documented in this file.\n\nThe format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),\nand this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).',
+      },
+    ],
+    [
+      '@semantic-release/npm',
+      { 
+        npmPublish: true,
+        tarballDir: 'dist',
+        // Tag stable releases as 'latest', dev releases as 'dev'
+        // This is handled by branch configuration below
+      },
+    ],
+    [
+      '@semantic-release/gitlab',
+      {
+        gitlabUrl: 'https://gitlab.com',
+        assets: [
+          { path: 'dist/*.tgz', label: 'OSSA npm package (${nextRelease.gitTag})' },
+          {
+            path: "spec/v${nextRelease.version.split('.')[0]}.${nextRelease.version.split('.')[1]}.${nextRelease.version.split('.')[2]}/ossa-${nextRelease.version.split('.')[0]}.${nextRelease.version.split('.')[1]}.${nextRelease.version.split('.')[2]}.schema.json",
+            label: 'OSSA ${nextRelease.version} JSON Schema',
+          },
+        ],
+      },
+    ],
+    [
+      '@semantic-release/git',
+      {
+        assets: ['package.json', 'package-lock.json', 'CHANGELOG.md'],
+        message: 'chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}',
+      },
+    ],
+  ],
+};

package/scripts/bump-version.ts

@@ -0,0 +1,57 @@
+#!/usr/bin/env tsx
+import fs from 'fs';
+import path from 'path';
+import { execSync } from 'child_process';
+
+const VERSION_FILE = path.join(process.cwd(), '.version.json');
+const versionConfig = JSON.parse(fs.readFileSync(VERSION_FILE, 'utf-8'));
+
+const type = process.argv[2] || 'patch'; // major, minor, patch, rc
+
+function bumpVersion(current: string, type: string): 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: ${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}`);
+  }
+}
+
+const newVersion = bumpVersion(versionConfig.current, type);
+versionConfig.latest_stable = versionConfig.current.replace('-RC', '');
+versionConfig.current = newVersion;
+
+fs.writeFileSync(VERSION_FILE, JSON.stringify(versionConfig, null, 2) + '\n');
+
+// Create spec directory
+const specDir = path.join(process.cwd(), 'spec', `v${newVersion}`);
+if (!fs.existsSync(specDir)) {
+  fs.mkdirSync(specDir, { recursive: true });
+  console.log(`✅ Created spec directory: ${specDir}`);
+}
+
+// Run sync
+execSync('npm run version:sync', { stdio: 'inherit' });
+
+console.log(`✅ Bumped version: ${versionConfig.current} → ${newVersion}`);
+console.log(`\nNext steps:`);
+console.log(`1. Update schema: spec/v${newVersion}/ossa-${newVersion}.schema.json`);
+console.log(`2. Commit: git add . && git commit -m "chore: bump version to ${newVersion}"`);

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`;
+}