fraim-framework 2.0.26 → 2.0.30

package/registry/rules/telemetry.md

@@ -0,0 +1,67 @@
+# Telemetry & Session Management
+
+## Protocol Overview
+
+FRAIM enforces a strict **Session Handshake** protocol to ensure proper environment tracking and implicit activity monitoring. All Agents interacting with a FRAIM server MUST adhere to this protocol.
+
+### 1. Mandatory Handshake (`fraim_connect`)
+
+At the start of **every** session (i.e., when the agent starts up or connects to a new workspace), you MUST call the `fraim_connect` tool immediately.
+
+**Tool**: `fraim_connect`
+**Arguments**:
+- `machine`: Object containing hardware specs.
+    - `hostname`: (string) e.g., "dev-box-1"
+    - `platform`: (string) e.g., "win32", "darwin"
+    - `arch`: (string) e.g., "x64"
+    - `cpus`: (string/number) CPU details
+    - `memory`: (string/number) Total RAM
+- `repo`: Object containing repository context.
+    - `url`: (string) **Required**. The git remote URL.
+    - `owner`: (string) e.g., "user-or-org"
+    - `name`: (string) e.g., "my-repo"
+
+**Example Call**:
+```json
+{
+  "name": "fraim_connect",
+  "arguments": {
+    "machine": {
+      "hostname": "azure-vm-01",
+      "platform": "linux",
+      "arch": "x64"
+    },
+    "repo": {
+      "url": "https://github.com/fraim/framework.git",
+      "owner": "fraim",
+      "name": "framework"
+    }
+  }
+}
+```
+
+**Failure Consequence**:
+If you attempt to call other tools (e.g., `get_fraim_workflow`, `get_fraim_file`) *without* first establishing a session via `fraim_connect`, the server will reject your request with a **400 Bad Request** error:
+
+> "⛔ Session Not Started. Please call the 'fraim_connect' tool first to register your environment and begin the session."
+
+### 2. Implicit Activity Tracking
+
+Once a session is established, you do **not** need to manually report usage. The FRAIM server automatically tracks your activity based on the API calls you make.
+
+- **Keep-Alive**: Every tool call acts as a "heartbeat", updating your session's `lastActive` timestamp.
+- **Efficiency**: The server uses write-behind caching to minimize database writes, so you can make frequent calls without performance penalty.
+- **Persistence**: Usage data is persisted across server restarts.
+
+### 3. Data Collection Policy
+
+We collect minimal metadata to improve the FRAIM system and validate startup credits:
+- **Hardware**: To optimize resource allocation recommendations.
+- **Repository**: To map work to specific projects/organizations.
+- **Duration**: Calculated as `lastActive - startTime` to measure session length.
+- **Tool Usage**: Which tools are used (implicitly derived).
+
+**We do NOT collect**:
+- Source code content (except what is explicitly passed in specific tool arguments like reviews).
+- Environment variables.
+- Personal files.

package/registry/scripts/build-scripts-generator.ts

@@ -1,215 +1,216 @@
-#!/usr/bin/env node
-
-/**
- * FRAIM Build Scripts Generator
- * 
- * Generates generic build scripts and validation patterns.
- * These are generic enough to apply to any project.
- * 
- * Usage:
- *   npx tsx .ai-agents/scripts/build-scripts-generator.ts
- */
-
-import { writeFileSync, existsSync, mkdirSync } from 'fs';
-import { join } from 'path';
-import { loadFraimConfig } from '../../../src/fraim/config-loader.js';
-
-/**
- * Generate package.json scripts section
- */
-export function generatePackageScripts(config: any): any {
-  return {
-    "build": "tsc && npm run validate:openapi",
-    "validate:openapi": "npx tsx fraim/generators/validate-openapi-limits.ts",
-    "start": "node dist/src/server.js",
-    "start:mcp": "node dist/src/mcp-server.js",
-    "dev": "npx tsx --watch src/server.ts",
-    "dev:mcp": "tsx src/mcp-server.ts",
-    "generate:openapi": "npx tsx fraim/generators/openapi-generator.ts",
-    "test": "npx tsx --test test*.ts",
-    "lint": "eslint *.ts",
-    "lint:fix": "eslint *.ts --fix"
-  };
-}
-
-/**
- * Generate code quality check script (generic version)
- */
-export function generateCodeQualityScript(outputDir: string): void {
-  if (!existsSync(outputDir)) {
-    mkdirSync(outputDir, { recursive: true });
-  }
-
-  const scriptContent = `#!/bin/bash
-
-# FRAIM Generic Code Quality Check
-# Validates code quality, build, and ChatGPT limits
-
-set -e
-
-MODE=\${1:-full}
-FAILED=0
-WARNINGS=0
-
-echo "================================================"
-echo "🔍 CODE QUALITY CHECK ($MODE mode)"
-echo "================================================"
-echo ""
-
-# Build check
-if [ "$MODE" = "full" ] || [ "$MODE" = "build" ]; then
-  echo "📦 Building project..."
-  if npm run build; then
-    echo "✅ Build passed"
-  else
-    echo "❌ Build failed"
-    FAILED=1
-  fi
-  echo ""
-fi
-
-# Lint check
-if [ "$MODE" = "full" ] || [ "$MODE" = "lint" ]; then
-  echo "🔍 Linting code..."
-  if npm run lint; then
-    echo "✅ Lint passed"
-  else
-    echo "⚠️  Lint warnings (non-blocking)"
-    WARNINGS=1
-  fi
-  echo ""
-fi
-
-# OpenAPI validation (ChatGPT limits)
-if [ "$MODE" = "full" ] || [ "$MODE" = "openapi" ]; then
-  echo "📋 Validating OpenAPI and ChatGPT limits..."
-  if npm run validate:openapi; then
-    echo "✅ OpenAPI validation passed"
-  else
-    echo "❌ OpenAPI validation failed"
-    FAILED=1
-  fi
-  echo ""
-fi
-
-# Summary
-echo "================================================"
-echo "📊 QUALITY CHECK SUMMARY ($MODE mode)"
-echo "================================================"
-echo ""
-
-if [ $FAILED -eq 1 ]; then
-  echo "❌ CHECKS FAILED"
-  echo ""
-  echo "Fix the errors above before proceeding."
-  exit 1
-elif [ $WARNINGS -eq 1 ]; then
-  echo "⚠️  CHECKS PASSED WITH WARNINGS"
-  echo ""
-  echo "Review warnings above."
-  exit 0
-else
-  echo "✅ ALL CHECKS PASSED"
-  echo ""
-  exit 0
-fi
-`;
-
-  const scriptPath = join(outputDir, 'code-quality-check.sh');
-  writeFileSync(scriptPath, scriptContent);
-
-  // Make executable (Unix)
-  if (process.platform !== 'win32') {
-    const { execSync } = require('child_process');
-    execSync(`chmod +x ${scriptPath}`);
-  }
-
-  console.log(`✅ Generated code quality check script at ${scriptPath}`);
-}
-
-/**
- * Generate build copy scripts (generic)
- */
-export function generateCopyScripts(outputDir: string): void {
-  if (!existsSync(outputDir)) {
-    mkdirSync(outputDir, { recursive: true });
-  }
-
-  // Copy AI agents script (if .ai-agents exists)
-  const copyAiAgents = `#!/usr/bin/env node
-
-/**
- * Copy .ai-agents directory to dist
- * Generic build script for FRAIM projects
- */
-
-const fs = require('fs');
-const path = require('path');
-
-const sourceDir = path.join(__dirname, '..', '.ai-agents');
-const destDir = path.join(__dirname, '..', 'dist', '.ai-agents');
-
-if (fs.existsSync(sourceDir)) {
-  // Recursive copy
-  function copyRecursive(src, dest) {
-    if (!fs.existsSync(dest)) {
-      fs.mkdirSync(dest, { recursive: true });
-    }
-    
-    const entries = fs.readdirSync(src, { withFileTypes: true });
-    
-    for (const entry of entries) {
-      const srcPath = path.join(src, entry.name);
-      const destPath = path.join(dest, entry.name);
-      
-      if (entry.isDirectory()) {
-        copyRecursive(srcPath, destPath);
-      } else {
-        fs.copyFileSync(srcPath, destPath);
-      }
-    }
-  }
-  
-  copyRecursive(sourceDir, destDir);
-  console.log('✅ Copied .ai-agents to dist/.ai-agents');
-} else {
-  console.log('ℹ️  .ai-agents directory not found, skipping');
-}
-`;
-
-  writeFileSync(join(outputDir, 'copy-ai-agents.js'), copyAiAgents);
-  console.log(`✅ Generated copy-ai-agents.js`);
-}
-
-/**
- * Main generator function
- */
-export function generateBuildScripts(config: any, outputDir: string = 'scripts/build'): void {
-  console.log('🚀 FRAIM Build Scripts Generator\n');
-  console.log(`📁 Output directory: ${outputDir}\n`);
-
-  // Ensure output directory exists
-  if (!existsSync(outputDir)) {
-    mkdirSync(outputDir, { recursive: true });
-  }
-
-  // Generate code quality check
-  console.log('📝 Generating code quality check script...');
-  generateCodeQualityScript(outputDir);
-
-  // Generate build scripts
-  console.log('\n📝 Generating build scripts...');
-  generateCopyScripts(outputDir);
-
-  console.log('\n✅ Build scripts generation complete!');
-  console.log('\n📋 Next steps:');
-  console.log('1. Add scripts to package.json');
-  console.log('2. Run: npm run validate:openapi');
-  console.log('3. Run: ./scripts/build/code-quality-check.sh');
-}
-
-// Run if executed directly
-if (import.meta.url === `file://${process.argv[1]}`) {
-  const config = loadFraimConfig();
-  generateBuildScripts(config);
-}
+#!/usr/bin/env node
+
+/**
+ * FRAIM Build Scripts Generator
+ * 
+ * Generates generic build scripts and validation patterns.
+ * These are generic enough to apply to any project.
+ * 
+ * Usage:
+ *   npx tsx scripts/build-scripts-generator.ts
+ */
+
+import { writeFileSync, existsSync, mkdirSync } from 'fs';
+import { join } from 'path';
+import { loadFraimConfig } from '../../src/fraim/config-loader.js';
+
+/**
+ * Generate package.json scripts section
+ */
+export function generatePackageScripts(config: any): any {
+  return {
+    "build": "tsc && npm run validate:openapi",
+    "validate:openapi": "npx tsx " + "reg" + "istry/scripts/validate-openapi-limits.ts",
+    "start": "node dist/src/server.js",
+    "start:mcp": "node dist/src/mcp-server.js",
+    "dev": "npx tsx --watch src/server.ts",
+    "dev:mcp": "tsx src/mcp-server.ts",
+    "generate:openapi": "npx tsx " + "reg" + "istry/scripts/openapi-generator.ts",
+    "test": "npx tsx --test test*.ts",
+    "lint": "eslint *.ts",
+    "lint:fix": "eslint *.ts --fix"
+  };
+}
+
+/**
+ * Generate code quality check script (generic version)
+ */
+export function generateCodeQualityScript(outputDir: string): void {
+  if (!existsSync(outputDir)) {
+    mkdirSync(outputDir, { recursive: true });
+  }
+
+  const scriptContent = `#!/bin/bash
+
+# FRAIM Generic Code Quality Check
+# Validates code quality, build, and ChatGPT limits
+
+set -e
+
+MODE=\${1:-full}
+FAILED=0
+WARNINGS=0
+
+echo "================================================"
+echo "🔍 CODE QUALITY CHECK ($MODE mode)"
+echo "================================================"
+echo ""
+
+# Build check
+if [ "$MODE" = "full" ] || [ "$MODE" = "build" ]; then
+  echo "📦 Building project..."
+  if npm run build; then
+    echo "✅ Build passed"
+  else
+    echo "❌ Build failed"
+    FAILED=1
+  fi
+  echo ""
+fi
+
+# Lint check
+if [ "$MODE" = "full" ] || [ "$MODE" = "lint" ]; then
+  echo "🔍 Linting code..."
+  if npm run lint; then
+    echo "✅ Lint passed"
+  else
+    echo "⚠️  Lint warnings (non-blocking)"
+    WARNINGS=1
+  fi
+  echo ""
+fi
+
+# OpenAPI validation (ChatGPT limits)
+if [ "$MODE" = "full" ] || [ "$MODE" = "openapi" ]; then
+  echo "📋 Validating OpenAPI and ChatGPT limits..."
+  if npm run validate:openapi; then
+    echo "✅ OpenAPI validation passed"
+  else
+    echo "❌ OpenAPI validation failed"
+    FAILED=1
+  fi
+  echo ""
+fi
+
+# Summary
+echo "================================================"
+echo "📊 QUALITY CHECK SUMMARY ($MODE mode)"
+echo "================================================"
+echo ""
+
+if [ $FAILED -eq 1 ]; then
+  echo "❌ CHECKS FAILED"
+  echo ""
+  echo "Fix the errors above before proceeding."
+  exit 1
+elif [ $WARNINGS -eq 1 ]; then
+  echo "⚠️  CHECKS PASSED WITH WARNINGS"
+  echo ""
+  echo "Review warnings above."
+  exit 0
+else
+  echo "✅ ALL CHECKS PASSED"
+  echo ""
+  exit 0
+fi
+`;
+
+  const scriptPath = join(outputDir, 'code-quality-check.sh');
+  writeFileSync(scriptPath, scriptContent);
+
+  // Make executable (Unix)
+  if (process.platform !== 'win32') {
+    const { execSync } = require('child_process');
+    execSync(`chmod +x ${scriptPath}`);
+  }
+
+  console.log(`✅ Generated code quality check script at ${scriptPath}`);
+}
+
+/**
+ * Generate build copy scripts (generic)
+ */
+export function generateCopyScripts(outputDir: string): void {
+  if (!existsSync(outputDir)) {
+    mkdirSync(outputDir, { recursive: true });
+  }
+
+  // Copy AI agents script (if .fraim exists)
+  const copyAiAgents = `#!/usr/bin/env node
+
+/**
+ * Copy registry directory to dist
+ * Generic build script for FRAIM projects
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const sourceDir = path.join(__dirname, '..', '..', 'registry');
+const destDir = path.join(__dirname, '..', '..', 'dist', 'registry');
+
+if (fs.existsSync(sourceDir)) {
+  // Recursive copy
+  function copyRecursive(src, dest) {
+    if (!fs.existsSync(dest)) {
+      fs.mkdirSync(dest, { recursive: true });
+    }
+    
+    const entries = fs.readdirSync(src, { withFileTypes: true });
+    
+    for (const entry of entries) {
+      const srcPath = path.join(src, entry.name);
+      const destPath = path.join(dest, entry.name);
+      
+      if (entry.isDirectory()) {
+        copyRecursive(srcPath, destPath);
+      } else {
+        fs.copyFileSync(srcPath, destPath);
+      }
+    }
+  }
+  
+  copyRecursive(sourceDir, destDir);
+  console.log('✅ Copied registry to dist/registry');
+} else {
+  console.log('ℹ️  registry directory not found, skipping');
+}
+`;
+
+  writeFileSync(join(outputDir, 'copy-ai-agents.js'), copyAiAgents);
+  console.log(`✅ Generated copy-ai-agents.js`);
+}
+
+/**
+ * Main generator function
+ */
+export function generateBuildScripts(config: any, outputDir: string = "scr" + "ipts/build"): void {
+  console.log('🚀 FRAIM Build Scripts Generator\n');
+  console.log(`📁 Output directory: ${outputDir}\n`);
+
+  // Ensure output directory exists
+  if (!existsSync(outputDir)) {
+    mkdirSync(outputDir, { recursive: true });
+  }
+
+  // Generate code quality check
+  console.log('📝 Generating code quality check script...');
+  generateCodeQualityScript(outputDir);
+
+  // Generate build scripts
+  console.log('\n📝 Generating build scripts...');
+  generateCopyScripts(outputDir);
+
+  console.log('\n✅ Build scripts generation complete!');
+  console.log('\n📋 Next steps:');
+  console.log('1. Add scripts to package.json');
+  console.log('2. Run: npm run validate:openapi');
+  console.log('3. Run: ./scripts/build/code-quality-check.sh');
+}
+
+// Run if executed directly
+// @ts-ignore
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const config = loadFraimConfig();
+  generateBuildScripts(config);
+}