@bluefly/openstandardagents 0.1.9 → 0.2.5-RC

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 ""

package/scripts/sync-version.ts

@@ -0,0 +1,39 @@
+#!/usr/bin/env tsx
+import fs from 'fs';
+import path from 'path';
+
+const VERSION_FILE = path.join(process.cwd(), '.version.json');
+const versionConfig = JSON.parse(fs.readFileSync(VERSION_FILE, 'utf-8'));
+const { current } = versionConfig;
+
+// Update package.json
+const pkgPath = path.join(process.cwd(), 'package.json');
+const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+pkg.version = current;
+fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
+
+// Update website package.json
+const websitePkgPath = path.join(process.cwd(), 'website/package.json');
+const websitePkg = JSON.parse(fs.readFileSync(websitePkgPath, 'utf-8'));
+websitePkg.version = current;
+fs.writeFileSync(websitePkgPath, JSON.stringify(websitePkg, null, 2) + '\n');
+
+// Update README badge
+const readmePath = path.join(process.cwd(), 'README.md');
+let readme = fs.readFileSync(readmePath, 'utf-8');
+readme = readme.replace(
+  /\[!\[Specification\]\(https:\/\/img\.shields\.io\/badge\/Spec-v[^-\)]+(-[^-\)]+)?-blue\)\]/g,
+  `[![Specification](https://img.shields.io/badge/Spec-v${current}-blue)]`
+);
+fs.writeFileSync(readmePath, readme);
+
+// Update website home
+const homePath = path.join(process.cwd(), 'website/content/docs/00-HOME.md');
+let home = fs.readFileSync(homePath, 'utf-8');
+home = home.replace(
+  /\[!\[Specification\]\(https:\/\/img\.shields\.io\/badge\/Spec-v[^-\)]+(-[^-\)]+)?-blue\)\]/g,
+  `[![Specification](https://img.shields.io/badge/Spec-v${current}-blue)]`
+);
+fs.writeFileSync(homePath, home);
+
+console.log(`✅ Synced version to ${current}`);

package/scripts/sync-versions.ts

@@ -0,0 +1,488 @@
+#!/usr/bin/env node
+
+/**
+ * OSSA Version Sync Script (Zod Edition)
+ *
+ * Automatically synchronizes version references across the entire project.
+ * Single source of truth: package.json version field
+ *
+ * Uses Zod for runtime validation and type safety.
+ *
+ * Updates:
+ * - README.md (schema links, badges, examples)
+ * - spec/vX.Y.Z/ directory creation
+ * - website/docs version references
+ * - OpenAPI spec version fields
+ * - CHANGELOG.md unreleased section
+ *
+ * Usage:
+ *   npx tsx scripts/sync-versions.ts [--check|--fix]
+ *
+ *   --check: Validate version consistency (CI mode)
+ *   --fix:   Update all version references
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { z } from 'zod';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// ============================================================================
+// Zod Schemas
+// ============================================================================
+
+const PackageJsonSchema = z.object({
+  name: z.string(),
+  version: z.string().regex(/^\d+\.\d+\.\d+(-[a-zA-Z0-9.]+)?$/, 'Invalid semver version'),
+  exports: z.object({
+    './schema': z.string().optional(),
+  }).passthrough().optional(),
+}).passthrough();
+
+const ConfigSchema = z.object({
+  root: z.string(),
+  packageJson: z.string(),
+  readme: z.string(),
+  changelog: z.string(),
+  releasing: z.string(),
+  specDir: z.string(),
+  mode: z.enum(['check', 'fix']),
+});
+
+const ResultSchema = z.object({
+  errors: z.array(z.string()),
+  changes: z.array(z.string()),
+  warnings: z.array(z.string()),
+});
+
+type PackageJson = z.infer<typeof PackageJsonSchema>;
+type Config = z.infer<typeof ConfigSchema>;
+type Result = z.infer<typeof ResultSchema>;
+
+// ============================================================================
+// Configuration
+// ============================================================================
+
+const ROOT = path.resolve(__dirname, '..');
+const PACKAGE_JSON = path.join(ROOT, 'package.json');
+const README = path.join(ROOT, 'README.md');
+const CHANGELOG = path.join(ROOT, 'CHANGELOG.md');
+const RELEASING = path.join(ROOT, 'RELEASING.md');
+const SPEC_DIR = path.join(ROOT, 'spec');
+
+// Mode: check or fix
+const MODE = process.argv[2] === '--check' ? 'check' : 'fix';
+
+const config: Config = ConfigSchema.parse({
+  root: ROOT,
+  packageJson: PACKAGE_JSON,
+  readme: README,
+  changelog: CHANGELOG,
+  releasing: RELEASING,
+  specDir: SPEC_DIR,
+  mode: MODE,
+});
+
+const result: Result = {
+  errors: [],
+  changes: [],
+  warnings: [],
+};
+
+// ============================================================================
+// Version Management
+// ============================================================================
+
+/**
+ * Get current version from package.json with validation
+ */
+function getCurrentVersion(): string {
+  try {
+    const pkgRaw = fs.readFileSync(config.packageJson, 'utf8');
+    const pkg = PackageJsonSchema.parse(JSON.parse(pkgRaw));
+    return pkg.version;
+  } catch (error) {
+    if (error instanceof z.ZodError) {
+      result.errors.push(`package.json validation failed: ${error.issues.map((e: z.ZodIssue) => e.message).join(', ')}`);
+    } else {
+      result.errors.push(`Failed to read package.json: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    throw error;
+  }
+}
+
+/**
+ * Get package.json as validated object
+ */
+function getPackageJson(): PackageJson {
+  const pkgRaw = fs.readFileSync(config.packageJson, 'utf8');
+  return PackageJsonSchema.parse(JSON.parse(pkgRaw));
+}
+
+// ============================================================================
+// Spec Directory Management
+// ============================================================================
+
+/**
+ * Check if spec directory exists for version
+ */
+function checkSpecDirectory(version: string): boolean {
+  const specPath = path.join(config.specDir, `v${version}`);
+  return fs.existsSync(specPath);
+}
+
+/**
+ * Create spec directory for version (copy from latest)
+ */
+function createSpecDirectory(version: string): void {
+  const newSpecPath = path.join(config.specDir, `v${version}`);
+
+  if (fs.existsSync(newSpecPath)) {
+    console.log(`✓ Spec directory already exists: spec/v${version}/`);
+    return;
+  }
+
+  // Find latest spec directory
+  const specDirs = fs.readdirSync(config.specDir)
+    .filter(d => d.startsWith('v') && !d.includes('-dev') && fs.statSync(path.join(config.specDir, d)).isDirectory())
+    .sort((a, b) => {
+      const aVer = a.slice(1).split('.').map(Number);
+      const bVer = b.slice(1).split('.').map(Number);
+      for (let i = 0; i < 3; i++) {
+        if (aVer[i] !== bVer[i]) return (bVer[i] || 0) - (aVer[i] || 0);
+      }
+      return 0;
+    });
+
+  if (specDirs.length === 0) {
+    result.errors.push(`No existing spec directories found to copy from`);
+    return;
+  }
+
+  const latestSpec = specDirs[0];
+  const sourceSpecPath = path.join(config.specDir, latestSpec);
+
+  if (config.mode === 'check') {
+    result.errors.push(`Spec directory missing: spec/v${version}/`);
+    return;
+  }
+
+  // Copy directory
+  console.log(`Creating spec/v${version}/ from ${latestSpec}...`);
+  try {
+    fs.cpSync(sourceSpecPath, newSpecPath, { recursive: true });
+  } catch (error) {
+    result.errors.push(`Failed to copy spec directory: ${error instanceof Error ? error.message : String(error)}`);
+    return;
+  }
+
+  // Update schema version in copied files
+  const oldVersion = latestSpec.slice(1);
+  const schemaFile = path.join(newSpecPath, `ossa-${oldVersion}.schema.json`);
+  const newSchemaFile = path.join(newSpecPath, `ossa-${version}.schema.json`);
+
+  if (fs.existsSync(schemaFile)) {
+    try {
+      const schema = JSON.parse(fs.readFileSync(schemaFile, 'utf8'));
+      schema.$id = schema.$id.replace(`v${oldVersion}`, `v${version}`);
+      schema.properties.ossaVersion.const = version;
+
+      fs.writeFileSync(newSchemaFile, JSON.stringify(schema, null, 2));
+
+      if (schemaFile !== newSchemaFile) {
+        fs.unlinkSync(schemaFile);
+      }
+    } catch (error) {
+      result.errors.push(`Failed to update schema file: ${error instanceof Error ? error.message : String(error)}`);
+      return;
+    }
+  }
+
+  result.changes.push(`Created spec/v${version}/ directory`);
+}
+
+// ============================================================================
+// File Updates
+// ============================================================================
+
+/**
+ * Semver pattern that matches versions with optional pre-release tags
+ * Matches: 0.2.5, 0.2.5-RC, 0.2.5-alpha.1, 1.0.0-beta.2, etc.
+ */
+const SEMVER_PATTERN = '[\\d]+\\.[\\d]+\\.[\\d]+(?:-[a-zA-Z0-9.]+)?';
+
+/**
+ * Update README.md version references
+ */
+function updateReadme(version: string): void {
+  if (!fs.existsSync(config.readme)) {
+    result.errors.push('README.md not found');
+    return;
+  }
+
+  let readme = fs.readFileSync(config.readme, 'utf8');
+  const original = readme;
+
+  // Update schema references (spec/vX.Y.Z/ossa-X.Y.Z.schema.json)
+  const schemaRegex = new RegExp(`spec/v${SEMVER_PATTERN}/ossa-${SEMVER_PATTERN}\\.schema\\.json`, 'g');
+  readme = readme.replace(schemaRegex, `spec/v${version}/ossa-${version}.schema.json`);
+
+  // Update version in YAML examples (ossaVersion: "X.Y.Z")
+  const yamlVersionRegex = new RegExp(`ossaVersion:\\s*["']${SEMVER_PATTERN}["']`, 'g');
+  readme = readme.replace(yamlVersionRegex, `ossaVersion: "${version}"`);
+
+  // Update "OSSA vX.Y.Z Schema:" header pattern
+  const headerRegex = new RegExp(`OSSA v${SEMVER_PATTERN} Schema:`, 'g');
+  readme = readme.replace(headerRegex, `OSSA v${version} Schema:`);
+
+  // Update version references in spec paths (e.g., spec/v0.2.5-RC/)
+  const versionLinkRegex = new RegExp(`spec/v${SEMVER_PATTERN}/`, 'g');
+  readme = readme.replace(versionLinkRegex, `spec/v${version}/`);
+
+  // Update ossa-X.Y.Z.yaml references
+  const yamlFileRegex = new RegExp(`ossa-${SEMVER_PATTERN}\\.yaml`, 'g');
+  readme = readme.replace(yamlFileRegex, `ossa-${version}.yaml`);
+
+  if (readme !== original) {
+    if (config.mode === 'check') {
+      result.errors.push('README.md has outdated version references');
+    } else {
+      fs.writeFileSync(config.readme, readme);
+      result.changes.push('Updated README.md version references');
+    }
+  } else {
+    console.log('✓ README.md version references are current');
+  }
+}
+
+/**
+ * Update RELEASING.md current version
+ */
+function updateReleasing(version: string): void {
+  if (!fs.existsSync(config.releasing)) {
+    result.warnings.push('RELEASING.md not found');
+    return;
+  }
+
+  let releasing = fs.readFileSync(config.releasing, 'utf8');
+  const original = releasing;
+
+  // Update "Current Version: X.Y.Z" line
+  const currentVersionRegex = /\*\*Current Version\*\*:\s*[\d.\-a-zA-Z]+/;
+  if (currentVersionRegex.test(releasing)) {
+    releasing = releasing.replace(currentVersionRegex, `**Current Version**: ${version}`);
+  }
+
+  if (releasing !== original) {
+    if (config.mode === 'check') {
+      result.errors.push(`RELEASING.md has outdated version (should be ${version})`);
+    } else {
+      fs.writeFileSync(config.releasing, releasing);
+      result.changes.push('Updated RELEASING.md current version');
+    }
+  } else {
+    console.log('✓ RELEASING.md is current');
+  }
+}
+
+/**
+ * Update CHANGELOG.md unreleased section
+ */
+function updateChangelog(version: string): void {
+  if (!fs.existsSync(config.changelog)) {
+    result.warnings.push('CHANGELOG.md not found');
+    return;
+  }
+
+  let changelog = fs.readFileSync(config.changelog, 'utf8');
+  const original = changelog;
+
+  // Replace [Unreleased] with [vX.Y.Z] - YYYY-MM-DD
+  const today = new Date().toISOString().split('T')[0];
+  const unreleasedRegex = /## \[Unreleased\]/;
+
+  if (unreleasedRegex.test(changelog)) {
+    changelog = changelog.replace(
+      unreleasedRegex,
+      `## [v${version}] - ${today}`
+    );
+
+    if (config.mode === 'check') {
+      result.errors.push('CHANGELOG.md has [Unreleased] section that should be versioned');
+    } else {
+      fs.writeFileSync(config.changelog, changelog);
+      result.changes.push(`Updated CHANGELOG.md: [Unreleased] → [v${version}]`);
+    }
+  } else {
+    console.log('✓ CHANGELOG.md is current');
+  }
+}
+
+/**
+ * Update package.json exports
+ */
+function updatePackageExports(version: string): void {
+  const pkg = getPackageJson();
+
+  if (pkg.exports && pkg.exports['./schema']) {
+    const expectedSchema = `./spec/v${version}/ossa-${version}.schema.json`;
+    const currentSchema = pkg.exports['./schema'];
+
+    // Check if current schema matches ANY version pattern (not just the expected one)
+    const schemaVersionRegex = new RegExp(`\\./spec/v${SEMVER_PATTERN}/ossa-${SEMVER_PATTERN}\\.schema\\.json`);
+
+    if (currentSchema !== expectedSchema) {
+      if (config.mode === 'check') {
+        result.errors.push(`package.json exports["./schema"] is "${currentSchema}", should be "${expectedSchema}"`);
+      } else {
+        pkg.exports['./schema'] = expectedSchema;
+        fs.writeFileSync(config.packageJson, JSON.stringify(pkg, null, 2) + '\n');
+        result.changes.push('Updated package.json schema export');
+      }
+    } else {
+      console.log('✓ package.json schema export is current');
+    }
+  }
+}
+
+/**
+ * Update website documentation
+ */
+function updateWebsiteDocs(version: string): void {
+  const websiteDir = path.join(config.root, 'website', 'content', 'docs');
+
+  if (!fs.existsSync(websiteDir)) {
+    result.warnings.push('website/content/docs/ not found (skipping)');
+    return;
+  }
+
+  // Recursively find all .md files
+  function findMarkdownFiles(dir: string): string[] {
+    const files: string[] = [];
+    const items = fs.readdirSync(dir);
+
+    items.forEach(item => {
+      const fullPath = path.join(dir, item);
+      const stat = fs.statSync(fullPath);
+
+      if (stat.isDirectory()) {
+        files.push(...findMarkdownFiles(fullPath));
+      } else if (item.endsWith('.md') || item.endsWith('.mdx')) {
+        files.push(fullPath);
+      }
+    });
+
+    return files;
+  }
+
+  const mdFiles = findMarkdownFiles(websiteDir);
+  let updated = 0;
+
+  mdFiles.forEach(file => {
+    let content = fs.readFileSync(file, 'utf8');
+    const original = content;
+
+    // Update version references (but not version history sections)
+    // Use same SEMVER_PATTERN to catch pre-release versions like -RC, -alpha, -beta
+    const yamlVersionRegex = new RegExp(`ossaVersion:\\s*["']${SEMVER_PATTERN}["']`, 'g');
+    content = content.replace(yamlVersionRegex, `ossaVersion: "${version}"`);
+
+    const schemaRegex = new RegExp(`spec/v${SEMVER_PATTERN}/ossa-${SEMVER_PATTERN}\\.schema\\.json`, 'g');
+    content = content.replace(schemaRegex, `spec/v${version}/ossa-${version}.schema.json`);
+
+    // Also update spec directory links
+    const specLinkRegex = new RegExp(`spec/v${SEMVER_PATTERN}/`, 'g');
+    content = content.replace(specLinkRegex, `spec/v${version}/`);
+
+    if (content !== original) {
+      if (config.mode === 'check') {
+        result.errors.push(`${path.relative(config.root, file)} has outdated version references`);
+      } else {
+        fs.writeFileSync(file, content);
+        updated++;
+      }
+    }
+  });
+
+  if (updated > 0) {
+    result.changes.push(`Updated ${updated} website documentation files`);
+  } else if (mdFiles.length > 0) {
+    console.log('✓ Website documentation is current');
+  }
+}
+
+// ============================================================================
+// Main Execution
+// ============================================================================
+
+function main(): void {
+  console.log('🔄 OSSA Version Sync (Zod Edition)');
+  console.log('==================================\n');
+
+  const version = getCurrentVersion();
+  console.log(`📦 Current version: ${version}`);
+  console.log(`🔧 Mode: ${config.mode.toUpperCase()}\n`);
+
+  // Run checks/fixes
+  createSpecDirectory(version);
+  updateReadme(version);
+  updateReleasing(version);
+  updateChangelog(version);
+  updatePackageExports(version);
+  updateWebsiteDocs(version);
+
+  // Report results
+  console.log('\n' + '='.repeat(50));
+
+  if (config.mode === 'check') {
+    if (result.errors.length > 0) {
+      console.log('\n❌ Version consistency check FAILED:\n');
+      result.errors.forEach(err => console.log(`  • ${err}`));
+      console.log('\nRun with --fix to update all references');
+      process.exit(1);
+    } else {
+      console.log('\n✅ All version references are consistent!');
+      if (result.warnings.length > 0) {
+        console.log('\n⚠️  Warnings:\n');
+        result.warnings.forEach(warn => console.log(`  • ${warn}`));
+      }
+      process.exit(0);
+    }
+  } else {
+    if (result.changes.length > 0) {
+      console.log('\n✅ Version sync complete:\n');
+      result.changes.forEach(change => console.log(`  • ${change}`));
+      console.log('\n💡 Review changes and commit:');
+      console.log(`   git add .`);
+      console.log(`   git commit -m "chore: sync version references to v${version}"`);
+    } else {
+      console.log('\n✅ All version references are already current!');
+    }
+
+    if (result.errors.length > 0) {
+      console.log('\n❌ Errors:\n');
+      result.errors.forEach(err => console.log(`  • ${err}`));
+      process.exit(1);
+    }
+
+    if (result.warnings.length > 0) {
+      console.log('\n⚠️  Warnings:\n');
+      result.warnings.forEach(warn => console.log(`  • ${warn}`));
+    }
+  }
+}
+
+// Run
+try {
+  main();
+} catch (error) {
+  console.error('\n❌ Fatal Error:', error instanceof Error ? error.message : String(error));
+  if (error instanceof z.ZodError) {
+    console.error('\nValidation Errors:');
+    error.issues.forEach((err: z.ZodIssue) => console.error(`  • ${err.path.join('.')}: ${err.message}`));
+  }
+  process.exit(1);
+}