contextos-agents 1.7.0 → 2.0.0-beta.3

package/.agents/core/skills/vercel-optimize/scripts/gate-investigations.mjs

@@ -1,142 +0,0 @@
-#!/usr/bin/env node
-/**
- * gate-investigations.mjs
- * Deterministic candidate gating engine for Vercel optimization recommendations.
- *
- * Usage:
- *   node scripts/gate-investigations.mjs <signals-file> [--threshold <n>] [--out <file>] [--help]
- */
-
-import { readFileSync, writeFileSync, existsSync } from 'node:fs';
-import { resolve } from 'node:path';
-
-function printHelp() {
-  console.log(`
-gate-investigations.mjs — Optimization Candidate Gating Engine
-
-Usage:
-  node scripts/gate-investigations.mjs <signals-file> [options]
-
-Arguments:
-  signals-file           JSON file generated by merge-signals.mjs (or collect-signals.mjs)
-
-Options:
-  --threshold <n>        Invocation volume threshold for candidate evaluation (default: 5000)
-  --out <file>           Output destination file (default: stdout)
-  --help, -h             Show this help message
-`);
-}
-
-const args = process.argv.slice(2);
-if (args.includes('--help') || args.includes('-h') || args.length === 0) {
-  printHelp();
-  process.exit(args.includes('--help') || args.includes('-h') ? 0 : 1);
-}
-
-let signalsFile = null;
-let threshold = 5000;
-let outFile = null;
-
-for (let i = 0; i < args.length; i++) {
-  const arg = args[i];
-  if (arg === '--threshold' && i + 1 < args.length) {
-    threshold = parseInt(args[++i], 10) || 5000;
-  } else if (arg === '--out' && i + 1 < args.length) {
-    outFile = args[++i];
-  } else if (!arg.startsWith('-') && !signalsFile) {
-    signalsFile = arg;
-  }
-}
-
-if (!signalsFile || !existsSync(signalsFile)) {
-  console.error(`Error: Signals file not found: ${signalsFile}`);
-  process.exit(1);
-}
-
-let data = {};
-try {
-  data = JSON.parse(readFileSync(resolve(process.cwd(), signalsFile), 'utf8'));
-} catch (e) {
-  console.error(`Error reading signals file: ${e.message}`);
-  process.exit(1);
-}
-
-const candidates = [];
-const routes = data.routes || [];
-
-for (const r of routes) {
-  if (r.invocations < threshold && r.p95DurationMs < 1000) {
-    continue;
-  }
-
-  // 1. Caching Opportunity Gate
-  if (r.method === 'GET' && r.invocations >= threshold && (r.cacheable || r.currentCacheControl === 'no-store' || !r.currentCacheControl)) {
-    candidates.push({
-      id: `cache-opp-${r.route.replace(/[^a-zA-Z0-9]/g, '-')}`,
-      scope: 'code',
-      category: 'caching',
-      route: r.route,
-      file: r.file || null,
-      priority: r.invocations > 100000 ? 'high' : 'medium',
-      metric: {
-        invocations: r.invocations,
-        p95DurationMs: r.p95DurationMs,
-        currentCacheControl: r.currentCacheControl
-      },
-      reason: `High volume GET route (${r.invocations.toLocaleString()} invocations) lacking edge/CDN cache headers.`
-    });
-  }
-
-  // 2. High Latency / Cold Start Gate
-  if (r.p95DurationMs >= 1000 || r.coldStartRate >= 0.1) {
-    candidates.push({
-      id: `latency-coldstart-${r.route.replace(/[^a-zA-Z0-9]/g, '-')}`,
-      scope: 'code',
-      category: 'compute-duration',
-      route: r.route,
-      file: r.file || null,
-      priority: r.p95DurationMs > 2000 ? 'high' : 'medium',
-      metric: {
-        p95DurationMs: r.p95DurationMs,
-        coldStartRate: r.coldStartRate,
-        invocations: r.invocations
-      },
-      reason: `P95 execution latency (${r.p95DurationMs}ms) or cold start rate (${Math.round(r.coldStartRate * 100)}%) warrants runtime or bundling optimization.`
-    });
-  }
-}
-
-// 3. Platform Scope Gates: Middleware & Fast Data Transfer
-const middlewareList = data.middleware || [];
-for (const mw of middlewareList) {
-  if (!mw.hasMatcher) {
-    candidates.push({
-      id: 'platform-middleware-unfiltered',
-      scope: 'platform',
-      category: 'middleware-overhead',
-      route: '/*',
-      file: mw.file,
-      priority: 'high',
-      metric: {
-        hasMatcher: false,
-        runtime: mw.runtime
-      },
-      reason: 'Middleware runs globally across all asset/data requests without a path matcher config.'
-    });
-  }
-}
-
-const gatedResult = {
-  timestamp: new Date().toISOString(),
-  projectId: data.projectId || 'unknown',
-  gateThreshold: threshold,
-  totalCandidates: candidates.length,
-  candidates
-};
-
-const outputJson = JSON.stringify(gatedResult, null, 2);
-if (outFile) {
-  writeFileSync(resolve(process.cwd(), outFile), outputJson, 'utf8');
-} else {
-  console.log(outputJson);
-}

package/.agents/core/skills/vercel-optimize/scripts/merge-signals.mjs

@@ -1,143 +0,0 @@
-#!/usr/bin/env node
-/**
- * merge-signals.mjs
- * Merges Vercel telemetry production metrics with codebase route scan outputs.
- *
- * Usage:
- *   node scripts/merge-signals.mjs <signals-file> <codebase-file> [--out <file>] [--help]
- */
-
-import { readFileSync, writeFileSync, existsSync } from 'node:fs';
-import { resolve } from 'node:path';
-
-function printHelp() {
-  console.log(`
-merge-signals.mjs — Correlates Telemetry Metrics with Codebase Routes
-
-Usage:
-  node scripts/merge-signals.mjs <signals-file> <codebase-file> [options]
-
-Arguments:
-  signals-file           JSON file generated by collect-signals.mjs
-  codebase-file          JSON file generated by scan-codebase.mjs
-
-Options:
-  --out <file>           Output destination file (default: stdout)
-  --help, -h             Show this help message
-`);
-}
-
-const args = process.argv.slice(2);
-if (args.includes('--help') || args.includes('-h') || args.length < 2) {
-  printHelp();
-  process.exit(args.includes('--help') || args.includes('-h') ? 0 : 1);
-}
-
-const positional = [];
-let outFile = null;
-
-for (let i = 0; i < args.length; i++) {
-  const arg = args[i];
-  if (arg === '--out' && i + 1 < args.length) {
-    outFile = args[++i];
-  } else if (!arg.startsWith('-')) {
-    positional.push(arg);
-  }
-}
-
-if (positional.length < 2) {
-  console.error('Error: Both <signals-file> and <codebase-file> are required.');
-  process.exit(1);
-}
-
-const [signalsPath, codebasePath] = positional;
-if (!existsSync(signalsPath)) {
-  console.error(`Error: File not found: ${signalsPath}`);
-  process.exit(1);
-}
-if (!existsSync(codebasePath)) {
-  console.error(`Error: File not found: ${codebasePath}`);
-  process.exit(1);
-}
-
-let signalsData = {};
-let codebaseData = {};
-
-try {
-  signalsData = JSON.parse(readFileSync(resolve(process.cwd(), signalsPath), 'utf8'));
-} catch (e) {
-  console.error(`Error parsing signals JSON: ${e.message}`);
-  process.exit(1);
-}
-
-try {
-  codebaseData = JSON.parse(readFileSync(resolve(process.cwd(), codebasePath), 'utf8'));
-} catch (e) {
-  console.error(`Error parsing codebase JSON: ${e.message}`);
-  process.exit(1);
-}
-
-const telemetryRoutes = signalsData.routes || [];
-const codeRoutes = codebaseData.routes || [];
-
-// Correlate metrics with source files
-const mergedRoutes = [];
-
-for (const tr of telemetryRoutes) {
-  // Find matching route in codebase
-  const match = codeRoutes.find(cr => {
-    return cr.route === tr.route || cr.route === tr.route + '/' || tr.route === cr.route + '/';
-  });
-
-  mergedRoutes.push({
-    ...tr,
-    file: match ? match.file : null,
-    frameworkConfig: match ? {
-      type: match.type,
-      dynamic: match.dynamic,
-      revalidate: match.revalidate,
-      runtime: match.runtime
-    } : null
-  });
-}
-
-// Add codebase routes that had no telemetry records
-for (const cr of codeRoutes) {
-  const existing = mergedRoutes.some(mr => mr.file === cr.file || mr.route === cr.route);
-  if (!existing) {
-    mergedRoutes.push({
-      route: cr.route,
-      method: 'GET',
-      invocations: 0,
-      p95DurationMs: 0,
-      avgDurationMs: 0,
-      coldStartRate: 0,
-      errorRate: 0,
-      cacheable: cr.dynamic === 'force-static' || cr.revalidate != null,
-      file: cr.file,
-      frameworkConfig: {
-        type: cr.type,
-        dynamic: cr.dynamic,
-        revalidate: cr.revalidate,
-        runtime: cr.runtime
-      }
-    });
-  }
-}
-
-const merged = {
-  timestamp: new Date().toISOString(),
-  projectId: signalsData.projectId || 'unknown',
-  windowDays: signalsData.windowDays || 14,
-  framework: codebaseData.framework || 'unknown',
-  metrics: signalsData.metrics || {},
-  middleware: codebaseData.middleware || [],
-  routes: mergedRoutes
-};
-
-const outputJson = JSON.stringify(merged, null, 2);
-if (outFile) {
-  writeFileSync(resolve(process.cwd(), outFile), outputJson, 'utf8');
-} else {
-  console.log(outputJson);
-}

package/.agents/core/skills/vercel-optimize/scripts/scan-codebase.mjs

@@ -1,174 +0,0 @@
-#!/usr/bin/env node
-/**
- * scan-codebase.mjs
- * Scans repository routes, middleware, and rendering directives for Vercel optimization.
- *
- * Usage:
- *   node scripts/scan-codebase.mjs <repo-root> [--out <file>] [--help]
- */
-
-import { readdirSync, statSync, readFileSync, writeFileSync, existsSync } from 'node:fs';
-import { resolve, join, relative, basename } from 'node:path';
-
-function printHelp() {
-  console.log(`
-scan-codebase.mjs — Vercel Codebase Route & Config Scanner
-
-Usage:
-  node scripts/scan-codebase.mjs <repo-root> [options]
-
-Arguments:
-  repo-root              Path to the repository root directory to scan
-
-Options:
-  --out <file>           Output file path (default: stdout)
-  --help, -h             Show this help message
-`);
-}
-
-const args = process.argv.slice(2);
-if (args.includes('--help') || args.includes('-h') || args.length === 0) {
-  printHelp();
-  process.exit(0);
-}
-
-let repoRoot = null;
-let outFile = null;
-
-for (let i = 0; i < args.length; i++) {
-  const arg = args[i];
-  if (arg === '--out' && i + 1 < args.length) {
-    outFile = args[++i];
-  } else if (!arg.startsWith('-') && !repoRoot) {
-    repoRoot = resolve(process.cwd(), arg);
-  }
-}
-
-if (!repoRoot || !existsSync(repoRoot)) {
-  console.error(`Error: Repository path not found: ${repoRoot}`);
-  process.exit(1);
-}
-
-// Detect framework
-let framework = 'unknown';
-const pkgPath = join(repoRoot, 'package.json');
-if (existsSync(pkgPath)) {
-  try {
-    const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
-    const deps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
-    if (deps.next) framework = 'nextjs';
-    else if (deps['@sveltejs/kit']) framework = 'sveltekit';
-    else if (deps.nuxt) framework = 'nuxt';
-    else if (deps.astro) framework = 'astro';
-    else if (deps.react) framework = 'react';
-  } catch {
-    // Ignore error
-  }
-}
-
-const routes = [];
-const middleware = [];
-
-function walk(dir) {
-  let entries;
-  try {
-    entries = readdirSync(dir, { withFileTypes: true });
-  } catch {
-    return;
-  }
-  for (const entry of entries) {
-    if (entry.name === 'node_modules' || entry.name === '.git' || entry.name === '.next' || entry.name === 'dist') {
-      continue;
-    }
-    const fullPath = join(dir, entry.name);
-    if (entry.isDirectory()) {
-      walk(fullPath);
-    } else if (entry.isFile()) {
-      const relPath = relative(repoRoot, fullPath).replace(/\\/g, '/');
-      const filename = basename(entry.name);
-
-      // Check middleware
-      if (/^middleware\.(ts|js|mjs)$/.test(filename) || /^src\/middleware\.(ts|js|mjs)$/.test(relPath)) {
-        try {
-          const content = readFileSync(fullPath, 'utf8');
-          middleware.push({
-            file: relPath,
-            hasMatcher: content.includes('matcher:'),
-            runtime: content.includes("runtime = 'edge'") ? 'edge' : 'nodejs'
-          });
-        } catch {}
-      }
-
-      // Check App Router route handlers
-      if (/^(route|page)\.(ts|tsx|js|jsx)$/.test(filename) && (relPath.includes('app/') || relPath.includes('src/app/'))) {
-        try {
-          const content = readFileSync(fullPath, 'utf8');
-          const isRoute = filename.startsWith('route');
-          const isDynamic = content.includes("dynamic = 'force-dynamic'") || content.includes('export const dynamic = "force-dynamic"');
-          const isStatic = content.includes("dynamic = 'force-static'") || content.includes('export const dynamic = "force-static"');
-          const hasRevalidate = /revalidate\s*=\s*(\d+)/.test(content);
-          const revalidateVal = hasRevalidate ? parseInt(content.match(/revalidate\s*=\s*(\d+)/)[1], 10) : null;
-          const runtime = content.includes("runtime = 'edge'") ? 'edge' : 'nodejs';
-
-          // Extract route pattern
-          let routeUrl = relPath
-            .replace(/^(src\/)?app/, '')
-            .replace(/\/(route|page)\.(ts|tsx|js|jsx)$/, '');
-          if (!routeUrl.startsWith('/')) routeUrl = '/' + routeUrl;
-          if (routeUrl === '') routeUrl = '/';
-
-          routes.push({
-            type: isRoute ? 'api-route' : 'page-route',
-            route: routeUrl,
-            file: relPath,
-            dynamic: isDynamic ? 'force-dynamic' : (isStatic ? 'force-static' : 'auto'),
-            revalidate: revalidateVal,
-            runtime
-          });
-        } catch {}
-      }
-
-      // Check Pages Router API handlers
-      if ((relPath.includes('pages/api/') || relPath.includes('src/pages/api/')) && /\.(ts|js)$/.test(filename)) {
-        try {
-          const content = readFileSync(fullPath, 'utf8');
-          let routeUrl = relPath
-            .replace(/^(src\/)?pages/, '')
-            .replace(/\.(ts|js)$/, '');
-          if (routeUrl.endsWith('/index')) routeUrl = routeUrl.slice(0, -6);
-
-          routes.push({
-            type: 'api-route',
-            route: routeUrl,
-            file: relPath,
-            dynamic: 'pages-api',
-            runtime: content.includes("runtime = 'edge'") ? 'edge' : 'nodejs'
-          });
-        } catch {}
-      }
-    }
-  }
-}
-
-walk(repoRoot);
-
-const result = {
-  timestamp: new Date().toISOString(),
-  repoRoot: relative(process.cwd(), repoRoot).replace(/\\/g, '/') || '.',
-  framework,
-  summary: {
-    totalRoutes: routes.length,
-    apiRoutes: routes.filter(r => r.type === 'api-route').length,
-    pageRoutes: routes.filter(r => r.type === 'page-route').length,
-    middlewareCount: middleware.length
-  },
-  middleware,
-  routes
-};
-
-const outputJson = JSON.stringify(result, null, 2);
-if (outFile) {
-  writeFileSync(resolve(process.cwd(), outFile), outputJson, 'utf8');
-} else {
-  console.log(outputJson);
-}

package/.agents/core/skills/vercel-optimize/skill.yaml

@@ -1,18 +0,0 @@
-name: vercel-optimize
-type: runtime
-description: Observability-first Vercel performance and cost reduction optimization skill.
-tags:
-  - vercel
-  - nextjs
-  - performance
-  - cost
-version: 1.2.0
-requires:
-  - nextjs
-resources:
-  - SKILL.md
-  - VALIDATION.json
-  - scripts/collect-signals.mjs
-  - scripts/gate-investigations.mjs
-  - scripts/merge-signals.mjs
-  - scripts/scan-codebase.mjs

package/.agents/core/skills/web-accessibility/EXAMPLES.md

@@ -1,39 +0,0 @@
-# web-accessibility Examples — Anti-patterns vs ContextOS Standard
-
-## Example 1: Semantic Buttons vs Clickable Divs
-
-### Anti-pattern: Clickable Div
-
-```tsx
-// BAD: Cannot be focused with Tab, does not respond to Enter or Space, silent to screen readers
-<div className="button" onClick={handleSubmit}>Submit</div>
-```
-
-### Best practice: ContextOS Standard (Semantic Button Element)
-
-```tsx
-// GOOD: Keyboard focusable, native Enter/Space handling, properly announced by assistive tech
-<button type="button" onClick={handleSubmit} className="btn btn-primary">
-  Submit
-</button>
-```
-
----
-
-## Example 2: Icon-only Buttons
-
-### Anti-pattern: Unlabelled Icon Button
-
-```tsx
-// BAD: Screen reader announces "button", user has zero idea what it does
-<button onClick={onClose}><XIcon /></button>
-```
-
-### Best practice: ContextOS Standard (Accessible Label)
-
-```tsx
-// GOOD: Explicit aria-label and hidden decorative icon
-<button type="button" onClick={onClose} aria-label="Close modal window">
-  <XIcon aria-hidden="true" />
-</button>
-```

package/.agents/core/skills/web-accessibility/SKILL.md

@@ -1,170 +0,0 @@
----
-name: Web Accessibility
-description: >
-  ContextOS skill for Web Accessibility (WCAG 2.1 AA/AAA), ARIA dialog patterns, keyboard focus traps, and Web Interface Guidelines.
----
-
-# Web Accessibility & Interface Guidelines
-
-## Overview
-
-Enforces universal accessibility compliance (WCAG 2.1 AA / AAA), rigorous semantic markup, keyboard navigability with focus traps, screen reader live regions, and Web Interface Guidelines standards.
-
-## When to Use
-
-Activate whenever building, styling, or reviewing user interfaces, forms, modals, menus, navigation drawers, custom interactive widgets, or media elements.
-
-## Negative Constraints (What NOT to Do)
-
-1. **NEVER use `outline: none` without a custom `:focus-visible` replacement**: Keyboard users must always have a distinct, high-contrast visual focus ring.
-2. **NEVER use non-semantic elements (`<div onClick>`) for interactive triggers**: Always use native `<button>` or `<a href>`.
-3. **NEVER create modals or dialogs without keyboard focus traps**: Focus must remain trapped inside open dialogs during Tab / Shift-Tab navigation and restore to trigger on close.
-4. **NEVER rely exclusively on color to indicate state or errors**: Always pair colors with text labels, icons, or ARIA attributes (`aria-invalid="true"`).
-5. **NEVER trap screen readers with missing form labels or error associations**: Every input must link to `<label htmlFor="id">` and errors via `aria-describedby`.
-6. **NEVER play animations without honoring `prefers-reduced-motion`**: Respect user OS motion reduction preferences.
-
-## Rules & Patterns
-
-### 1. Focus Visible & High-Contrast Focus Rings
-
-```css
-button:focus-visible,
-a:focus-visible,
-input:focus-visible {
-  outline: 2px solid #6366f1;
-  outline-offset: 2px;
-  border-radius: 4px;
-}
-
-button:focus:not(:focus-visible) {
-  outline: none;
-}
-```
-
-### 2. Accessible Modal & Focus Trap Contract
-
-```tsx
-import React, { useEffect, useRef } from 'react';
-import { createPortal } from 'react-dom';
-
-interface ModalProps {
-  isOpen: boolean;
-  onClose: () => void;
-  titleId: string;
-  children: React.ReactNode;
-}
-
-export function AccessibleModal({ isOpen, onClose, titleId, children }: ModalProps) {
-  const dialogRef = useRef<HTMLDivElement>(null);
-  const triggerRef = useRef<HTMLElement | null>(null);
-
-  useEffect(() => {
-    if (!isOpen) return;
-    triggerRef.current = document.activeElement as HTMLElement;
-
-    const handleKeyDown = (e: KeyboardEvent) => {
-      if (e.key === 'Escape') {
-        e.preventDefault();
-        onClose();
-      }
-
-      if (e.key === 'Tab') {
-        const focusables = dialogRef.current?.querySelectorAll<HTMLElement>(
-          'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
-        ) || [];
-        if (!focusables.length) return;
-
-        const first = focusables[0];
-        const last = focusables[focusables.length - 1];
-
-        if (e.shiftKey && document.activeElement === first) {
-          e.preventDefault();
-          last.focus();
-        } else if (!e.shiftKey && document.activeElement === last) {
-          e.preventDefault();
-          first.focus();
-        }
-      }
-    };
-
-    document.addEventListener('keydown', handleKeyDown);
-    return () => {
-      document.removeEventListener('keydown', handleKeyDown);
-      triggerRef.current?.focus();
-    };
-  }, [isOpen, onClose]);
-
-  if (!isOpen) return null;
-
-  return createPortal(
-    <div className="fixed inset-0 z-50 flex items-center justify-center bg-black/60 p-4">
-      <div 
-        ref={dialogRef}
-        role="dialog"
-        aria-modal="true"
-        aria-labelledby={titleId}
-        className="w-full max-w-lg rounded-xl bg-background p-6 shadow-2xl border"
-      >
-        {children}
-      </div>
-    </div>,
-    document.body
-  );
-}
-```
-
-### 3. Accessible Forms & Error Association
-
-```tsx
-export function EmailInput({ error, ...props }: { error?: string } & React.InputHTMLAttributes<HTMLInputElement>) {
-  const inputId = 'user-email';
-  const errorId = 'user-email-error';
-
-  return (
-    <div className="flex flex-col gap-1.5">
-      <label htmlFor={inputId} className="text-sm font-medium">
-        Email Address <span aria-hidden="true" className="text-destructive">*</span>
-      </label>
-      <input
-        id={inputId}
-        type="email"
-        autoComplete="email"
-        required
-        aria-invalid={Boolean(error)}
-        aria-describedby={error ? errorId : undefined}
-        className="rounded-md border p-2 text-sm focus-visible:ring-2"
-        {...props}
-      />
-      {error && (
-        <p id={errorId} role="alert" className="text-xs text-destructive">
-          {error}
-        </p>
-      )}
-    </div>
-  );
-}
-```
-
-## Code Examples
-
-See `EXAMPLES.md` for detailed dialog, menu, and form examples.
-
-## Validation Checklist
-
-- [ ] All interactive elements are fully operable via Keyboard (`Tab`, `Enter`, `Space`, `Escape`).
-- [ ] Visual `:focus-visible` styling is distinct and high contrast (≥ 3:1).
-- [ ] Modals use `role="dialog"`, `aria-modal="true"`, focus trap, and restore focus on close.
-- [ ] Text contrast ratios satisfy WCAG AA (≥ 4.5:1 for normal text, ≥ 3:1 for large text).
-- [ ] Forms pair inputs with `<label htmlFor>`, valid `autocomplete` tokens, and `aria-invalid`.
-- [ ] Non-text media contains descriptive `alt` attributes or `aria-hidden="true"` for decorative icons.
-
-## Common Mistakes
-
-- Hiding outline focus indicators globally without `:focus-visible` fallback.
-- Forgetting to trap focus in modal dialogs or not returning focus to trigger when modal closes.
-- Missing `aria-expanded` attributes on disclosure buttons and dropdown toggles.
-
-## Integration Notes
-
-- Pairs with `ui-ux-pro` and `impeccable-design` for visual contrast and component standards.
-- Pairs with `react` and `nextjs` for accessible dialogs and focus restoration across route transitions.