contextos-agents 2.0.0 → 2.1.1

package/catalog/skills/vercel-optimize/scripts/merge-signals.mjs

@@ -0,0 +1,143 @@
+#!/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/catalog/skills/vercel-optimize/scripts/scan-codebase.mjs

@@ -0,0 +1,174 @@
+#!/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/catalog/skills/vercel-optimize/skill.yaml

@@ -0,0 +1,15 @@
+schemaVersion: 2
+name: vercel-optimize
+category: devops
+type: runtime
+description: Observability-first Vercel performance and cost reduction optimization skill.
+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/catalog/skills/web-accessibility/EXAMPLES.md

@@ -0,0 +1,39 @@
+# 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/catalog/skills/web-accessibility/SKILL.md

@@ -0,0 +1,151 @@
+---
+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';
+
+interface AccessibleModalProps {
+  isOpen: boolean;
+  onClose: () => void;
+  titleId: string;
+  children: React.ReactNode;
+}
+
+/**
+ * Accessible Modal Dialog (W3C ARIA APG Compliant)
+ * Uses native HTMLDialogElement with .showModal() to guarantee:
+ * 1. Native inert background (blocks screen reader and click bleed-through).
+ * 2. Native keyboard focus trap (strictly keeps Tab cycles within dialog).
+ * 3. Native Escape key cancellation and focus restoration to trigger element.
+ */
+export function AccessibleModal({ isOpen, onClose, titleId, children }: AccessibleModalProps) {
+  const dialogRef = useRef<HTMLDialogElement>(null);
+
+  useEffect(() => {
+    const dialog = dialogRef.current;
+    if (!dialog) return;
+
+    if (isOpen) {
+      if (!dialog.open) {
+        dialog.showModal();
+      }
+    } else {
+      if (dialog.open) {
+        dialog.close();
+      }
+    }
+  }, [isOpen]);
+
+  return (
+    <dialog
+      ref={dialogRef}
+      aria-labelledby={titleId}
+      onCancel={(e) => {
+        e.preventDefault();
+        onClose();
+      }}
+      className="w-full max-w-lg rounded-xl bg-background p-6 shadow-2xl border backdrop:bg-black/60 outline-none"
+    >
+      {children}
+    </dialog>
+  );
+}
+```
+
+### 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.

package/catalog/skills/web-accessibility/TROUBLESHOOTING.md

@@ -0,0 +1,19 @@
+# web-accessibility Troubleshooting & Common Mistakes
+
+## 1. Trapping Keyboard Users in Inactive Elements
+
+- **Symptom**: Tab key moves focus into invisible elements hidden offscreen.
+- **Root Cause**: Using display: none vs opacity: 0 or left: -9999px.
+- **Fix**: Always apply display: none / hidden or inert attribute to elements that are currently not visible.
+
+## 2. Color Contrast Violations
+
+- **Symptom**: Text is unreadable for users with low vision or in bright sunlight.
+- **Root Cause**: Contrast ratio between text and background color is below WCAG AA thresholds.
+- **Fix**: Ensure contrast ratio is at least 4.5:1 for body text and 3:1 for large text / graphical controls.
+
+## 3. Silent Dynamic Updates
+
+- **Symptom**: Asynchronous error messages or notifications appear on screen without screen reader announcement.
+- **Root Cause**: Missing ARIA live region.
+- **Fix**: Wrap notification banners in aria-live="polite" and role="status".

package/catalog/skills/web-accessibility/VALIDATION.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "rules_followed": {
+      "type": "boolean"
+    }
+  },
+  "required": [
+    "rules_followed"
+  ]
+}

package/catalog/skills/web-accessibility/skill.yaml

@@ -0,0 +1,14 @@
+schemaVersion: 2
+id: web-accessibility
+name: Web Accessibility
+category: frontend
+type: instruction-only
+requires: []
+optional: [react, nextjs]
+conflicts: []
+weight: 7
+resources:
+  - EXAMPLES.md
+  - SKILL.md
+  - TROUBLESHOOTING.md
+  - VALIDATION.json

package/package.json

@@ -1,6 +1,6 @@
 {
     "name":  "contextos-agents",
-    "version":  "2.0.0",
+    "version":  "2.1.1",
     "description":  "Deterministic context and policy compiler for supported AI coding agents.",
     "bin":  {
                 "contextos":  "./bin/index.js",
@@ -10,6 +10,7 @@
     "files":  [
                   "NOTICE",
                   "bin",
+                  "catalog",
                   "registry.json",
                   "registry.schema.json",
                   "registry.v2.schema.json",
@@ -43,11 +44,13 @@
                     "compile":  "node .agents/ctx.js compile",
                     "export":  "node .agents/ctx.js export gemini",
                     "validate":  "node .agents/ctx.js validate",
+                    "validate:catalog":  "node .agents/ctx.js validate --catalog",
                     "lint:md":  "markdownlint README.md CONTRIBUTING.md GUIDE.md \".agents/core/skills/**/*.md\" --ignore \".agents/generated/**\" --config .markdownlint.json",
                     "check:secrets":  "node scripts/check-secrets.js --all",
                     "setup:hooks":  "node scripts/install-hooks.js",
                     "watch":  "node .agents/watch.js",
-                    "test":  "node --test --test-concurrency=1 tests/install.test.js tests/lockfile.test.js tests/safe-writer.test.js tests/adapter-safety.test.js tests/update.test.js tests/uninstall.test.js tests/plugin-security.test.js tests/export.test.js tests/skills.test.js tests/validate.test.js tests/plugins.test.js tests/benchmark.test.js tests/benchmark-api.test.js tests/profile.test.js tests/resolver.test.js tests/cli-registry.test.js tests/profile-enforcement.test.js tests/doctor-hardening.test.js tests/manifest-compiler.test.js tests/canonical-resolver.test.js tests/workspace-graph.test.js tests/profiles-v2.test.js tests/safe-path.test.js tests/project-lock.test.js tests/journaled-transaction.test.js tests/pure-adapters.test.js tests/prompt-skill-system.test.js tests/runtime-state-machine.test.js tests/verification-reviewer-pipeline.test.js tests/durable-concurrency-locks.test.js tests/transactional-git.test.js tests/sandbox-execution.test.js tests/plugin-supply-chain.test.js tests/platform-hardening.test.js tests/customization-dx.test.js tests/claims-governance.test.js tests/benchmark-v2.test.js tests/init-engine.test.js tests/mutation-paths.test.js tests/tarball-smoke.test.js",
+                    "test:skills":  "node scripts/verify-skill-examples.js",
+                    "test":  "node --test --test-concurrency=1 tests/install.test.js tests/lockfile.test.js tests/safe-writer.test.js tests/adapter-safety.test.js tests/update.test.js tests/uninstall.test.js tests/plugin-security.test.js tests/export.test.js tests/skills.test.js tests/validate.test.js tests/plugins.test.js tests/benchmark.test.js tests/benchmark-api.test.js tests/profile.test.js tests/resolver.test.js tests/cli-registry.test.js tests/profile-enforcement.test.js tests/doctor-hardening.test.js tests/manifest-compiler.test.js tests/canonical-resolver.test.js tests/workspace-graph.test.js tests/profiles-v2.test.js tests/safe-path.test.js tests/project-lock.test.js tests/journaled-transaction.test.js tests/pure-adapters.test.js tests/prompt-skill-system.test.js tests/runtime-state-machine.test.js tests/verification-reviewer-pipeline.test.js tests/durable-concurrency-locks.test.js tests/transactional-git.test.js tests/sandbox-execution.test.js tests/plugin-supply-chain.test.js tests/platform-hardening.test.js tests/customization-dx.test.js tests/claims-governance.test.js tests/benchmark-v2.test.js tests/init-engine.test.js tests/mutation-paths.test.js tests/tarball-smoke.test.js tests/catalog-export-integration.test.js tests/consumer-gate.test.js tests/adapter-compatibility.test.js tests/consumer-init.test.js tests/skill-examples.test.js tests/scan.test.js tests/hooks.test.js tests/recovery-cli.test.js tests/doctor-v2.test.js tests/resolver-parity.test.js tests/watch-coalescing.test.js",
                     "prepublishOnly":  "npm run validate \u0026\u0026 npm run build"
                 },
     "keywords":  [