@bluefly/openstandardagents 0.2.4 → 0.2.7

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/lowercase-docs.ts

@@ -0,0 +1,43 @@
+#!/usr/bin/env tsx
+/**
+ * Convert all documentation filenames to lowercase
+ */
+
+import { readdirSync, renameSync, statSync } from 'fs';
+import { join, basename, dirname } from 'path';
+
+const DOCS_DIR = join(process.cwd(), 'website/content/docs');
+
+function lowercaseFiles(dir: string) {
+  const entries = readdirSync(dir);
+  
+  for (const entry of entries) {
+    const fullPath = join(dir, entry);
+    const stat = statSync(fullPath);
+    
+    if (stat.isDirectory()) {
+      // Recursively process subdirectories
+      lowercaseFiles(fullPath);
+      
+      // Rename directory if needed
+      const lowerEntry = entry.toLowerCase();
+      if (entry !== lowerEntry) {
+        const newPath = join(dirname(fullPath), lowerEntry);
+        console.log(`📁 Renaming: ${entry} → ${lowerEntry}`);
+        renameSync(fullPath, newPath);
+      }
+    } else if (entry.endsWith('.md')) {
+      // Rename file if needed
+      const lowerEntry = entry.toLowerCase();
+      if (entry !== lowerEntry) {
+        const newPath = join(dirname(fullPath), lowerEntry);
+        console.log(`📄 Renaming: ${entry} → ${lowerEntry}`);
+        renameSync(fullPath, newPath);
+      }
+    }
+  }
+}
+
+console.log('🔄 Converting documentation filenames to lowercase...\n');
+lowercaseFiles(DOCS_DIR);
+console.log('\n✅ Done!');

package/scripts/manage-milestone-mrs.ts

@@ -0,0 +1,279 @@
+#!/usr/bin/env tsx
+/**
+ * Manage Merge Requests for a specific milestone
+ * Helps clean up and organize MRs for controlled releases
+ */
+
+import { Gitlab } from '@gitbeaker/node';
+import { Command } from 'commander';
+
+const gitlab = new Gitlab({
+  token: process.env.GITLAB_TOKEN || process.env.GITLAB_ACCESS_TOKEN,
+  host: 'https://gitlab.com',
+});
+
+const PROJECT_ID = '76265294'; // blueflyio/openstandardagents
+
+interface MRInfo {
+  iid: number;
+  title: string;
+  state: string;
+  target_branch: string;
+  source_branch: string;
+  milestone?: { title: string };
+  has_conflicts: boolean;
+  merge_status: string;
+  web_url: string;
+}
+
+async function listMRsInMilestone(milestone: string) {
+  console.log(`\n📋 Listing MRs in milestone: ${milestone}\n`);
+
+  const mrs = await gitlab.MergeRequests.all({
+    projectId: PROJECT_ID,
+    state: 'opened',
+    milestone,
+  });
+
+  if (mrs.length === 0) {
+    console.log('No open MRs found in this milestone.');
+    return;
+  }
+
+  console.log(`Found ${mrs.length} open MRs:\n`);
+
+  for (const mr of mrs) {
+    const status = mr.has_conflicts ? '❌ CONFLICTS' : '✅ Clean';
+    const target = mr.target_branch === 'development' ? '✅ dev' : `⚠️  ${mr.target_branch}`;
+    
+    console.log(`!${mr.iid}: ${mr.title}`);
+    console.log(`   Target: ${target} | Status: ${status}`);
+    console.log(`   ${mr.web_url}\n`);
+  }
+}
+
+async function listMRsNotInMilestone(milestone: string) {
+  console.log(`\n📋 Listing open MRs NOT in milestone: ${milestone}\n`);
+
+  const allMRs = await gitlab.MergeRequests.all({
+    projectId: PROJECT_ID,
+    state: 'opened',
+  });
+
+  const outsideMRs = allMRs.filter(
+    (mr: any) => !mr.milestone || mr.milestone.title !== milestone
+  );
+
+  if (outsideMRs.length === 0) {
+    console.log('All open MRs are in the milestone.');
+    return;
+  }
+
+  console.log(`Found ${outsideMRs.length} MRs outside milestone:\n`);
+
+  for (const mr of outsideMRs) {
+    const milestoneText = mr.milestone ? mr.milestone.title : 'No milestone';
+    console.log(`!${mr.iid}: ${mr.title}`);
+    console.log(`   Milestone: ${milestoneText}`);
+    console.log(`   Target: ${mr.target_branch}`);
+    console.log(`   ${mr.web_url}\n`);
+  }
+}
+
+async function retargetMR(mrId: number, targetBranch: string) {
+  console.log(`\n🎯 Retargeting MR !${mrId} to ${targetBranch}...\n`);
+
+  try {
+    await gitlab.MergeRequests.edit(PROJECT_ID, mrId, {
+      target_branch: targetBranch,
+    });
+
+    console.log(`✅ Successfully retargeted MR !${mrId} to ${targetBranch}`);
+  } catch (error: any) {
+    console.error(`❌ Failed to retarget MR: ${error.message}`);
+    process.exit(1);
+  }
+}
+
+async function closeMR(mrId: number, reason: string) {
+  console.log(`\n🚫 Closing MR !${mrId}...\n`);
+
+  try {
+    // Add comment explaining closure
+    await gitlab.MergeRequestNotes.create(PROJECT_ID, mrId, {
+      body: `Closing this MR: ${reason}\n\nIf this work is still needed, please rebase and assign to the appropriate milestone.`,
+    });
+
+    // Close the MR
+    await gitlab.MergeRequests.edit(PROJECT_ID, mrId, {
+      state_event: 'close',
+    });
+
+    console.log(`✅ Successfully closed MR !${mrId}`);
+  } catch (error: any) {
+    console.error(`❌ Failed to close MR: ${error.message}`);
+    process.exit(1);
+  }
+}
+
+async function rebaseMR(mrId: number) {
+  console.log(`\n🔄 Rebasing MR !${mrId}...\n`);
+
+  try {
+    await gitlab.MergeRequests.rebase(PROJECT_ID, mrId);
+    console.log(`✅ Rebase initiated for MR !${mrId}`);
+    console.log('   Check the MR page for rebase status.');
+  } catch (error: any) {
+    console.error(`❌ Failed to rebase MR: ${error.message}`);
+    process.exit(1);
+  }
+}
+
+async function assignMilestone(mrId: number, milestone: string) {
+  console.log(`\n🏷️  Assigning MR !${mrId} to milestone ${milestone}...\n`);
+
+  try {
+    // Get milestone ID
+    const milestones = await gitlab.ProjectMilestones.all(PROJECT_ID);
+    const targetMilestone = milestones.find((m: any) => m.title === milestone);
+
+    if (!targetMilestone) {
+      throw new Error(`Milestone "${milestone}" not found`);
+    }
+
+    await gitlab.MergeRequests.edit(PROJECT_ID, mrId, {
+      milestone_id: targetMilestone.id,
+    });
+
+    console.log(`✅ Successfully assigned MR !${mrId} to milestone ${milestone}`);
+  } catch (error: any) {
+    console.error(`❌ Failed to assign milestone: ${error.message}`);
+    process.exit(1);
+  }
+}
+
+async function bulkRetarget(milestone: string, targetBranch: string) {
+  console.log(`\n🎯 Bulk retargeting all MRs in ${milestone} to ${targetBranch}...\n`);
+
+  const mrs = await gitlab.MergeRequests.all({
+    projectId: PROJECT_ID,
+    state: 'opened',
+    milestone,
+  });
+
+  console.log(`Found ${mrs.length} MRs to retarget\n`);
+
+  for (const mr of mrs) {
+    if (mr.target_branch !== targetBranch) {
+      console.log(`Retargeting !${mr.iid}: ${mr.title}`);
+      await retargetMR(mr.iid, targetBranch);
+    } else {
+      console.log(`Skipping !${mr.iid}: already targets ${targetBranch}`);
+    }
+  }
+
+  console.log(`\n✅ Bulk retarget complete`);
+}
+
+async function bulkRebase(milestone: string) {
+  console.log(`\n🔄 Bulk rebasing all MRs in ${milestone}...\n`);
+
+  const mrs = await gitlab.MergeRequests.all({
+    projectId: PROJECT_ID,
+    state: 'opened',
+    milestone,
+  });
+
+  console.log(`Found ${mrs.length} MRs to rebase\n`);
+
+  for (const mr of mrs) {
+    if (mr.has_conflicts) {
+      console.log(`Rebasing !${mr.iid}: ${mr.title} (has conflicts)`);
+      await rebaseMR(mr.iid);
+      // Wait a bit between rebases
+      await new Promise((resolve) => setTimeout(resolve, 2000));
+    } else {
+      console.log(`Skipping !${mr.iid}: no conflicts`);
+    }
+  }
+
+  console.log(`\n✅ Bulk rebase complete`);
+}
+
+// CLI
+const program = new Command();
+
+program
+  .name('manage-milestone-mrs')
+  .description('Manage merge requests for milestone-based releases')
+  .version('1.0.0');
+
+program
+  .command('list')
+  .description('List all MRs in a milestone')
+  .requiredOption('-m, --milestone <milestone>', 'Milestone name (e.g., v0.2.6)')
+  .action(async (options) => {
+    await listMRsInMilestone(options.milestone);
+  });
+
+program
+  .command('list-outside')
+  .description('List all MRs NOT in a milestone')
+  .requiredOption('-m, --milestone <milestone>', 'Milestone name (e.g., v0.2.6)')
+  .action(async (options) => {
+    await listMRsNotInMilestone(options.milestone);
+  });
+
+program
+  .command('retarget')
+  .description('Retarget an MR to a different branch')
+  .requiredOption('-i, --id <id>', 'MR ID (e.g., 123)')
+  .requiredOption('-t, --target <branch>', 'Target branch (e.g., development)')
+  .action(async (options) => {
+    await retargetMR(parseInt(options.id), options.target);
+  });
+
+program
+  .command('close')
+  .description('Close an MR with a reason')
+  .requiredOption('-i, --id <id>', 'MR ID (e.g., 123)')
+  .requiredOption('-r, --reason <reason>', 'Reason for closing')
+  .action(async (options) => {
+    await closeMR(parseInt(options.id), options.reason);
+  });
+
+program
+  .command('rebase')
+  .description('Rebase an MR')
+  .requiredOption('-i, --id <id>', 'MR ID (e.g., 123)')
+  .action(async (options) => {
+    await rebaseMR(parseInt(options.id));
+  });
+
+program
+  .command('assign')
+  .description('Assign an MR to a milestone')
+  .requiredOption('-i, --id <id>', 'MR ID (e.g., 123)')
+  .requiredOption('-m, --milestone <milestone>', 'Milestone name (e.g., v0.2.6)')
+  .action(async (options) => {
+    await assignMilestone(parseInt(options.id), options.milestone);
+  });
+
+program
+  .command('bulk-retarget')
+  .description('Retarget all MRs in a milestone to a branch')
+  .requiredOption('-m, --milestone <milestone>', 'Milestone name (e.g., v0.2.6)')
+  .requiredOption('-t, --target <branch>', 'Target branch (e.g., development)')
+  .action(async (options) => {
+    await bulkRetarget(options.milestone, options.target);
+  });
+
+program
+  .command('bulk-rebase')
+  .description('Rebase all MRs with conflicts in a milestone')
+  .requiredOption('-m, --milestone <milestone>', 'Milestone name (e.g., v0.2.6)')
+  .action(async (options) => {
+    await bulkRebase(options.milestone);
+  });
+
+program.parse();

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/rebase-all-mrs.sh

@@ -0,0 +1,75 @@
+#!/bin/bash
+#
+# Rebase all open MRs onto their target branches
+# This script fetches and rebases each source branch
+#
+
+set -e
+
+TOKEN="${GITLAB_TOKEN:-${SERVICE_ACCOUNT_OSSA_TOKEN:-${GITLAB_PUSH_TOKEN}}}"
+PROJECT="blueflyio/openstandardagents"
+
+if [ -z "$TOKEN" ]; then
+  echo "❌ Error: GITLAB_TOKEN or SERVICE_ACCOUNT_OSSA_TOKEN required"
+  exit 1
+fi
+
+echo "🔄 Fetching open merge requests..."
+MRs=$(curl -sS --header "PRIVATE-TOKEN: $TOKEN" \
+  "https://gitlab.com/api/v4/projects/${PROJECT//\//%2F}/merge_requests?state=opened&per_page=20" | \
+  jq -r '.[] | "\(.iid)|\(.source_branch)|\(.target_branch)"')
+
+echo ""
+echo "Found MRs to rebase:"
+echo "$MRs" | while IFS='|' read -r iid source target; do
+  echo "  MR !$iid: $source -> $target"
+done
+
+echo ""
+read -p "Continue with rebasing? (y/N) " -n 1 -r
+echo
+if [[ ! $REPLY =~ ^[Yy]$ ]]; then
+  echo "Cancelled."
+  exit 0
+fi
+
+echo "$MRs" | while IFS='|' read -r iid source target; do
+  echo ""
+  echo "=== Rebasing MR !$iid: $source -> $target ==="
+  
+  # Fetch both branches
+  git fetch origin "$source" "$target" 2>&1 | grep -v "^From" || true
+  
+  # Check if source branch exists locally
+  if git show-ref --verify --quiet "refs/heads/$source"; then
+    echo "  Branch $source exists locally, using worktree..."
+    git worktree add "../rebase-$source" "$source" 2>/dev/null || {
+      echo "  Worktree exists, removing..."
+      git worktree remove "../rebase-$source" 2>/dev/null || true
+      git worktree add "../rebase-$source" "$source"
+    }
+    cd "../rebase-$source"
+  else
+    echo "  Creating worktree for $source..."
+    git worktree add "../rebase-$source" "origin/$source"
+    cd "../rebase-$source"
+  fi
+  
+  # Rebase onto target
+  echo "  Rebasing onto origin/$target..."
+  if git rebase "origin/$target" 2>&1 | tee /tmp/rebase-output.log; then
+    echo "  ✅ Rebase successful"
+    echo "  Pushing..."
+    git push origin "$source" --force-with-lease 2>&1 | grep -v "^To " || true
+    echo "  ✅ MR !$iid rebased and pushed"
+  else
+    echo "  ❌ Rebase failed - check conflicts"
+    echo "  Worktree: $(pwd)"
+    echo "  Fix conflicts and run: git rebase --continue && git push origin $source --force-with-lease"
+  fi
+  
+  cd - > /dev/null
+done
+
+echo ""
+echo "✅ Rebase process complete!"

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