@bluefly/openstandardagents 0.2.5-RC → 0.2.8

package/dist/utils/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../../src/utils/version.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AASH,MAAM,WAAW,WAAW;IAC1B,0CAA0C;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,8BAA8B;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,8BAA8B;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,8BAA8B;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,iDAAiD;IACjD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,6CAA6C;IAC7C,SAAS,EAAE,MAAM,CAAC;IAClB,uDAAuD;IACvD,UAAU,EAAE,MAAM,CAAC;IACnB,gDAAgD;IAChD,UAAU,EAAE,MAAM,CAAC;IACnB,uCAAuC;IACvC,UAAU,EAAE,MAAM,CAAC;CACpB;AAoCD;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,YAAY,UAAQ,GAAG,WAAW,CAiDhE;AAED;;GAEG;AACH,wBAAgB,UAAU,IAAI,MAAM,CAEnC;AAED;;GAEG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAED;;GAEG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAED;;GAEG;AACH,wBAAgB,YAAY,IAAI,MAAM,CAErC;AAED;;GAEG;AACH,wBAAgB,YAAY,IAAI,OAAO,CAEtC;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,IAAI,MAAM,EAAE,CAc/C;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,CAG9D"}

package/dist/utils/version.js

@@ -0,0 +1,156 @@
+/**
+ * OSSA Version Utilities
+ *
+ * Provides dynamic version detection from package.json
+ * NEVER hardcode version strings - use these utilities
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { fileURLToPath } from 'url';
+// Cache the version info once resolved
+let cachedVersionInfo = null;
+/**
+ * Find package.json by searching upward from a starting directory
+ */
+function findPackageJson(startDir) {
+    let current = startDir;
+    for (let i = 0; i < 10; i++) {
+        const candidate = path.resolve(current, 'package.json');
+        if (fs.existsSync(candidate)) {
+            return candidate;
+        }
+        const parent = path.dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    return null;
+}
+/**
+ * Parse version string into components
+ */
+function parseVersion(version) {
+    // Handle versions like "0.2.8", "0.2.8-RC", "0.2.8-beta.1"
+    const match = version.match(/^(\d+)\.(\d+)\.(\d+)(?:-(.+))?$/);
+    if (!match) {
+        throw new Error(`Invalid version format: ${version}`);
+    }
+    return {
+        major: parseInt(match[1], 10),
+        minor: parseInt(match[2], 10),
+        patch: parseInt(match[3], 10),
+        prerelease: match[4]
+    };
+}
+/**
+ * Get OSSA version information dynamically from package.json
+ *
+ * @param forceRefresh - If true, bypasses cache and re-reads package.json
+ * @returns VersionInfo object with all version details
+ *
+ * @example
+ * const { version, schemaPath, apiVersion } = getVersionInfo();
+ * console.log(`Using OSSA ${version}`);
+ * console.log(`Schema at: ${schemaPath}`);
+ */
+export function getVersionInfo(forceRefresh = false) {
+    if (cachedVersionInfo && !forceRefresh) {
+        return cachedVersionInfo;
+    }
+    let version = '0.2.8'; // Ultimate fallback
+    // Try to find package.json
+    // Strategy 1: From this file's location (works in dist)
+    try {
+        const __filename = fileURLToPath(import.meta.url);
+        const __dirname = path.dirname(__filename);
+        const pkgPath = findPackageJson(__dirname);
+        if (pkgPath) {
+            const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+            version = pkg.version;
+        }
+    }
+    catch {
+        // Strategy 2: From process.cwd()
+        try {
+            const pkgPath = findPackageJson(process.cwd());
+            if (pkgPath) {
+                const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+                version = pkg.version;
+            }
+        }
+        catch {
+            // Use fallback
+        }
+    }
+    // Strategy 3: Check environment variable override
+    if (process.env.OSSA_VERSION) {
+        version = process.env.OSSA_VERSION;
+    }
+    const parsed = parseVersion(version);
+    const schemaDir = `v${version}`;
+    const schemaFile = `ossa-${version}.schema.json`;
+    cachedVersionInfo = {
+        version,
+        ...parsed,
+        schemaDir,
+        schemaFile,
+        schemaPath: `spec/${schemaDir}/${schemaFile}`,
+        apiVersion: `ossa.io/${schemaDir}`
+    };
+    return cachedVersionInfo;
+}
+/**
+ * Get just the version string (convenience function)
+ */
+export function getVersion() {
+    return getVersionInfo().version;
+}
+/**
+ * Get the schema path (convenience function)
+ */
+export function getSchemaPath() {
+    return getVersionInfo().schemaPath;
+}
+/**
+ * Get the API version for manifests (convenience function)
+ */
+export function getApiVersion() {
+    return getVersionInfo().apiVersion;
+}
+/**
+ * Get the schema directory (e.g., "v0.2.8")
+ */
+export function getSchemaDir() {
+    return getVersionInfo().schemaDir;
+}
+/**
+ * Check if version is a prerelease
+ */
+export function isPrerelease() {
+    return getVersionInfo().prerelease !== undefined;
+}
+/**
+ * Get supported schema versions (for migration, validation)
+ * Returns versions in descending order (newest first)
+ */
+export function getSupportedVersions() {
+    const current = getVersionInfo();
+    // Generate supported versions dynamically
+    // Current version + 2 previous minor versions
+    const versions = [current.version];
+    // Add previous minor versions if they exist
+    for (let i = 1; i <= 2; i++) {
+        if (current.minor - i >= 0) {
+            versions.push(`${current.major}.${current.minor - i}.0`);
+        }
+    }
+    return versions;
+}
+/**
+ * Resolve absolute path to schema file
+ */
+export function resolveSchemaPath(projectRoot) {
+    const root = projectRoot || process.cwd();
+    return path.resolve(root, getVersionInfo().schemaPath);
+}
+//# sourceMappingURL=version.js.map

package/dist/utils/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../../src/utils/version.ts"],"names":[],"mappings":"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"}

package/docs/brand-guide/01-brand-overview.md

@@ -0,0 +1,37 @@
+# OSSA Brand Overview
+
+> Version 1.0.0 | Last Updated: November 2025
+
+## Mission
+
+**Make AI agents interoperable across all platforms and frameworks.**
+
+OSSA (Open Standard for Scalable AI Agents) provides a vendor-neutral specification standard that enables AI agents to communicate and collaborate seamlessly.
+
+## Vision
+
+**Become the OpenAPI for AI agents** - the universally adopted standard for defining, deploying, and connecting autonomous AI systems.
+
+## Core Values
+
+### 1. Open & Vendor-Neutral
+Community-driven, no vendor lock-in, Apache 2.0 license
+
+### 2. Interoperable  
+Common language across frameworks, runtime-independent
+
+### 3. Trustworthy
+Compliance-ready, security built-in, enterprise-grade
+
+### 4. Simple & Practical
+Clear specification, production-ready implementations
+
+## Key Messages
+
+**Primary:** "The OpenAPI for AI Agents"
+
+**For Enterprises:** Deploy anywhere, switch frameworks anytime, maintain compliance always
+
+**For Developers:** Write once, deploy anywhere - portable and future-proof
+
+**For Framework Builders:** Build on an open standard

package/docs/brand-guide/02-logo-usage.md

@@ -0,0 +1,43 @@
+# OSSA Logo Usage Guidelines
+
+> Version 1.0.0 | Last Updated: November 2025
+
+## Primary Logo
+
+Dynamic gradient-based mark representing interconnected AI agents.
+
+**Location:** `/website/public/brand/ossa-logo.svg`
+
+**Colors:** Gradient from Cyan Blue (#1CB9ED) → Deep Purple (#4A3ECD) → Light Purple (#9060EA)
+
+## Logo Variations
+
+- **Full Color:** White/light backgrounds
+- **Monochrome White:** Dark backgrounds (#FFFFFF)
+- **Monochrome Dark:** Light backgrounds, print (#2D1B69)
+- **Grayscale:** Print only (#374151)
+
+## Minimum Sizes
+
+- **Digital:** 120px width min (180px recommended)
+- **Print:** 1 inch min (1.5 inches recommended)
+- **Icon:** 16px, 32px, 64px, 128px
+
+## Clear Space
+
+Maintain clear space = **0.5× logo height** on all sides
+
+## Incorrect Usage
+
+❌ Don't change colors
+❌ Don't distort/stretch
+❌ Don't add effects
+❌ Don't modify
+❌ Don't use low-quality
+
+## Background Guidelines
+
+✅ White, light gray, light blue, dark purple, black
+❌ Bright colors, busy patterns, low-contrast
+
+**Rule:** 4.5:1 minimum contrast ratio

package/docs/brand-guide/03-color-palette.md

@@ -0,0 +1,70 @@
+# OSSA Color Palette
+
+> Version 1.0.0 | Last Updated: November 2025
+
+## Primary Brand Colors
+
+### Deep Purple (Primary)
+**Base:** `#4A3ECD`
+**Usage:** Primary actions, branding, emphasis
+**Scale:** 50-950 (see full guide)
+
+### Cyan Blue (Secondary)  
+**Base:** `#1CB9ED`
+**Usage:** Secondary actions, accents, gradients
+**Scale:** 50-950
+
+### Light Purple (Accent)
+**Base:** `#9060EA`  
+**Usage:** Decorative accents, gradient endpoints
+**Scale:** 50-950
+
+### Dark Purple (Depth)
+**Base:** `#2D1B69`
+**Usage:** Dark backgrounds, dark mode, contrast
+**Scale:** 50-950
+
+## Semantic Colors
+
+- **Success:** `#10B981` (Green)
+- **Warning:** `#F59E0B` (Amber)
+- **Error:** `#EF4444` (Red)
+- **Info:** `#06B6D4` (Cyan)
+
+## Neutrals (Grays)
+
+**Scale:** `#F9FAFB` (50) to `#111827` (900)
+
+**Common Uses:**
+- Primary text: Gray-700 (#374151) or Gray-900
+- Secondary text: Gray-600 (#4B5563)
+- Borders: Gray-200 (#E5E7EB) or Gray-300
+- Backgrounds: White, Gray-50, Gray-100
+
+## Gradients
+
+### Brand Gradient
+```css
+background: linear-gradient(135deg, #1CB9ED 0%, #1CB9ED 40%, #4A3ECD 70%, #9060EA 100%);
+```
+
+### Hero Gradient
+```css
+background: linear-gradient(135deg, #1CB9ED 0%, #1CB9ED 35%, #4A3ECD 65%, #9060EA 100%);
+```
+
+## Accessibility
+
+All combinations meet WCAG AA minimum (AAA preferred):
+- Normal text: 4.5:1 minimum (7:1 target)
+- Large text: 3:1 minimum (4.5:1 target)
+- UI components: 3:1 minimum
+
+**White text on:**
+- Primary-500+: ✅ AAA (7.5:1)
+- Secondary-600+: ✅ AA (4.7:1)
+- Dark Purple-700+: ✅ AAA (10:1+)
+
+**Black text on:**
+- Gray-50 to Gray-300: ✅ AAA (8:1+)
+- Primary-50 to Primary-400: ✅ AAA (7:1+)

package/docs/brand-guide/04-typography.md

@@ -0,0 +1,82 @@
+# OSSA Typography Guidelines
+
+> Version 1.0.0 | Last Updated: November 2025
+
+## Font Families
+
+### Primary: Inter (Sans-serif)
+**Usage:** UI, headings, body text, marketing
+**Weights:** 400 (Regular), 500 (Medium), 600 (Semi-Bold), 700 (Bold), 800 (Extra-Bold)
+**Why:** Exceptional legibility, optimized for screens, 200+ languages
+
+### Monospace: JetBrains Mono
+**Usage:** Code blocks, inline code, technical content
+**Weights:** 400 (Regular), 500 (Medium), 600 (Semi-Bold)
+**Why:** Developer-focused, excellent ligatures, clear character distinction
+
+## Type Scale
+
+| Element | Size | Line Height | Weight | Color |
+|---------|------|-------------|--------|-------|
+| **Display** | 72px (4.5rem) | 1.1 | 800 | Gray-900 or Gradient |
+| **H1** | 56px (3.5rem) | 1.2 | 700 | Gray-900 or Primary-500 |
+| **H2** | 40px (2.5rem) | 1.3 | 700 | Gray-900 |
+| **H3** | 32px (2rem) | 1.4 | 600 | Gray-900 |
+| **H4** | 24px (1.5rem) | 1.5 | 600 | Gray-800 |
+| **H5** | 20px (1.25rem) | 1.5 | 600 | Gray-800 |
+| **H6** | 18px (1.125rem) | 1.5 | 600 | Gray-700 |
+| **Body** | 16px (1rem) | 1.6 | 400 | Gray-700 |
+| **Body Large** | 18px (1.125rem) | 1.6 | 400 | Gray-700 |
+| **Small** | 14px (0.875rem) | 1.5 | 400 | Gray-600 |
+| **Extra Small** | 12px (0.75rem) | 1.5 | 400 | Gray-500 |
+
+## Letter Spacing
+
+- **Display:** -0.02em (tighter for large sizes)
+- **H1:** -0.01em (slightly tighter)
+- **H2-H6, Body:** 0 (normal)
+- **All Caps:** 0.05em (improve readability)
+
+## Code Typography
+
+### Inline Code
+- Font: JetBrains Mono, 0.875em
+- Color: Primary-700 (#322598)
+- Background: Primary-50 (#F5F4FD)
+- Padding: 0.2em 0.4em
+- Border Radius: 4px
+
+### Code Blocks
+- Font: JetBrains Mono, 14px (0.875rem)
+- Color: #D4D4D4 (light gray on dark)
+- Background: #1E1E1E (dark gray)
+- Line Height: 1.6
+- Padding: 16px
+- Border Radius: 8px
+
+## Responsive Typography
+
+**Mobile (< 768px):**
+- Display: 40px
+- H1: 36px
+- H2: 28px
+
+**Tablet (768-1279px):**
+- Display: 56px
+- H1: 48px
+- H2: 32px
+
+**Desktop (1280px+):**
+- Use full scale (above)
+
+## Accessibility
+
+✅ Line height: 1.5 minimum for body (we use 1.6)
+✅ Contrast: All text meets WCAG AA minimum (AAA preferred)
+✅ Font size: Never below 12px (prefer 14px minimum)
+✅ Zoom: Support up to 200% without loss of functionality
+
+**Text Contrast:**
+- Primary text: Gray-700 on white (10.5:1 AAA)
+- Secondary text: Gray-600 on white (7.4:1 AAA)
+- Links: Primary-500 on white (6.1:1 AA)

package/docs/brand-guide/05-voice-and-tone.md

@@ -0,0 +1,108 @@
+# OSSA Voice & Tone Guidelines
+
+> Version 1.0.0 | Last Updated: November 2025
+
+## Brand Voice
+
+OSSA's voice is consistent across all communications:
+
+### 1. Professional
+Enterprise-grade standard with technical authority
+- Use precise technical language
+- Cite specifications and standards
+- Maintain formal structure in documentation
+
+### 2. Clear
+Technical but accessible
+- Define acronyms on first use
+- Use analogies ("The OpenAPI for AI agents")
+- Break complex topics into chunks
+
+### 3. Confident
+Proven and production-ready
+- Use active voice
+- Make definitive statements when true
+- Reference real-world deployments
+
+### 4. Inclusive
+Community-driven and open to everyone
+- Use "we" for community
+- Welcome all skill levels
+- Use gender-neutral language
+
+### 5. Practical
+Real-world solutions, not theory
+- Provide working code examples
+- Link to reference implementations
+- Give step-by-step instructions
+
+## Tone Variations
+
+### Technical Documentation
+**Audience:** Developers, architects, engineers
+**Tone:** Precise, formal, comprehensive
+- Formal structure
+- Technical precision
+- Complete information
+- Reference links
+
+### Marketing & Website
+**Audience:** Decision-makers, evaluators
+**Tone:** Confident, clear, persuasive
+- Benefit-focused
+- Clear value propositions
+- Social proof
+- Strong CTAs
+
+### Community & Support
+**Audience:** Contributors, users
+**Tone:** Helpful, encouraging, collaborative
+- Welcoming and supportive
+- Providing guidance
+- Encouraging participation
+
+### Error Messages
+**Audience:** Users encountering issues
+**Tone:** Clear, helpful, solution-oriented
+- State problem clearly
+- Explain why it happened
+- Provide actionable solutions
+- Link to documentation
+
+## Writing Guidelines
+
+**Active vs. Passive:**
+✅ Prefer active voice for clarity
+❌ Avoid passive unless actor unknown
+
+**Pronouns:**
+- We = OSSA project, community
+- You = Reader, user, developer
+- They/Them = Generic third-party
+
+**Contractions:**
+- Technical Docs: Avoid contractions
+- Marketing: Acceptable for approachability
+
+**Numbers:**
+- Spell out 1-9
+- Use numerals for 10+
+- Always numerals for technical specs
+
+## Prohibited Language
+
+❌ Ableist language (crazy, insane, lame)
+❌ Violent metaphors (killer, crushed, decimated)
+❌ Gendered language (guys, manpower, he/she)
+❌ Exclusive language (obviously, clearly, simply, just)
+❌ Vague intensifiers (very, really, extremely)
+
+## Key Messages
+
+**Primary:** "The OpenAPI for AI Agents"
+
+**For Enterprises:** "Deploy anywhere, switch frameworks anytime, maintain compliance always."
+
+**For Developers:** "Write once, deploy anywhere. Portable and future-proof."
+
+**For Framework Builders:** "Build on an open standard. We provide the contract, you provide the innovation."

package/docs/brand-guide/06-visual-elements.md

@@ -0,0 +1,137 @@
+# OSSA Visual Elements
+
+> Version 1.0.0 | Last Updated: November 2025
+
+## Gradients
+
+### Brand Gradient (Primary)
+```css
+background: linear-gradient(135deg, #1CB9ED 0%, #1CB9ED 40%, #4A3ECD 70%, #9060EA 100%);
+```
+**Usage:** Headers, hero sections, primary emphasis
+
+### Hero Gradient
+```css
+background: linear-gradient(135deg, #1CB9ED 0%, #1CB9ED 35%, #4A3ECD 65%, #9060EA 100%);
+```
+
+### Button Gradient
+```css
+background: linear-gradient(135deg, #1CB9ED 0%, #1CB9ED 45%, #4A3ECD 75%, #9060EA 100%);
+```
+
+## Icons
+
+**Style:** Outline/Stroke icons (Heroicons style)
+**Stroke Width:** 1.5px (default), 2px (emphasis)
+**Sizes:** 16px, 20px, 24px, 32px, 48px, 64px
+**Library:** Heroicons or Lucide React
+
+**Usage:**
+- Navigation: 24px
+- Actions: 20px
+- Status: 24px
+- External links: 16px
+
+## Shadows
+
+```css
+--shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.04);
+--shadow-md: 0 2px 8px rgba(0, 0, 0, 0.04);
+--shadow-lg: 0 8px 24px rgba(0, 0, 0, 0.08);
+--shadow-xl: 0 16px 48px rgba(0, 0, 0, 0.12);
+--shadow-brand: 0 8px 16px rgba(74, 62, 205, 0.3);
+```
+
+## Border Radius
+
+```css
+--radius-sm: 4px;    /* Badges */
+--radius-md: 8px;    /* Buttons, inputs */
+--radius-lg: 12px;   /* Cards */
+--radius-xl: 16px;   /* Modals */
+--radius-2xl: 24px;  /* Hero elements */
+--radius-full: 9999px; /* Avatars, pills */
+```
+
+## Spacing
+
+**Base Grid:** 4px
+
+```css
+--space-1: 4px    --space-6: 24px
+--space-2: 8px    --space-8: 32px
+--space-3: 12px   --space-10: 40px
+--space-4: 16px   --space-12: 48px
+--space-5: 20px   --space-16: 64px
+```
+
+## Buttons
+
+### Primary Button
+- Background: Primary-500 or Gradient
+- Text: White
+- Padding: 12px 24px
+- Border Radius: 8px
+- Hover: Primary-600 + shadow-lg + translateY(-1px)
+- Focus: Ring (3px, Primary-300)
+
+### Secondary Button
+- Background: Secondary-500
+- Text: White
+- Hover: Secondary-600
+
+### Outline Button
+- Border: 2px Primary-500
+- Text: Primary-500
+- Hover: Background Primary-500, text white
+
+### Ghost Button
+- Text: Primary-500
+- Hover: Background Primary-50
+
+## Cards
+
+**Default Card:**
+- Background: White
+- Border: 1px Gray-200
+- Border Radius: 12px
+- Padding: 24px
+- Shadow: shadow-sm
+
+**Interactive Card (Hover):**
+- Border: Primary
+- Shadow: shadow-xl
+- Transform: translateY(-4px)
+
+**Featured Card:**
+- Background: Gradient (subtle, low opacity)
+- Border: 2px Primary-200
+
+## Badges
+
+**Style:**
+- Padding: 4px 12px
+- Border Radius: 9999px
+- Font Size: 12px
+- Font Weight: 600
+- Text Transform: Uppercase
+- Letter Spacing: 0.05em
+
+**Variants:** Primary, Success, Warning, Error, Neutral
+
+## Animations
+
+**Timing:**
+- Fast: 150ms ease (hover, color changes)
+- Base: 200ms ease (default)
+- Slow: 300ms ease (page transitions, modals)
+
+**Respect:** `prefers-reduced-motion`
+
+## Accessibility
+
+✅ Contrast: WCAG AA minimum (4.5:1 text, 3:1 UI)
+✅ Focus: Visible 3px rings, 3:1 contrast
+✅ Touch Targets: 44×44px minimum (48×48px preferred)
+✅ Alt Text: All logos and images