godpowers 0.15.0

package/lib/design-detector.js

@@ -0,0 +1,167 @@
+/**
+ * Design Detector
+ *
+ * Determines whether a project requires a DESIGN.md (i.e., has a UI surface).
+ * Reads .godpowers/stack/DECISION.md and inspects package.json / pyproject.toml
+ * / etc. for frontend frameworks.
+ *
+ * Public API:
+ *   isUiProject(projectRoot) -> { required, frameworks, signals }
+ *   isImpeccableInstalled(projectRoot) -> { installed, locations }
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const FRONTEND_FRAMEWORKS = [
+  // Web
+  { name: 'react', signal: 'react' },
+  { name: 'next.js', signal: 'next' },
+  { name: 'nuxt', signal: 'nuxt' },
+  { name: 'vue', signal: 'vue' },
+  { name: 'svelte', signal: 'svelte' },
+  { name: 'sveltekit', signal: '@sveltejs/kit' },
+  { name: 'angular', signal: '@angular/core' },
+  { name: 'remix', signal: '@remix-run' },
+  { name: 'solid', signal: 'solid-js' },
+  { name: 'solidstart', signal: '@solidjs/start' },
+  { name: 'astro', signal: 'astro' },
+  { name: 'qwik', signal: '@builder.io/qwik' },
+  // Mobile
+  { name: 'react-native', signal: 'react-native' },
+  { name: 'flutter', signal: 'flutter' },
+  { name: 'expo', signal: 'expo' },
+  // Desktop
+  { name: 'electron', signal: 'electron' },
+  { name: 'tauri', signal: '@tauri-apps' },
+  // CSS / Design libs (signal of UI work)
+  { name: 'tailwindcss', signal: 'tailwindcss' },
+  { name: 'styled-components', signal: 'styled-components' },
+  { name: 'emotion', signal: '@emotion/react' },
+  { name: 'shadcn', signal: 'class-variance-authority' },
+  { name: 'mui', signal: '@mui/material' },
+  { name: 'chakra', signal: '@chakra-ui/react' },
+  { name: 'mantine', signal: '@mantine/core' }
+];
+
+/**
+ * Detect frontend frameworks via package manifests.
+ */
+function detectFrameworks(projectRoot) {
+  const detected = [];
+  const pkgPath = path.join(projectRoot, 'package.json');
+  if (fs.existsSync(pkgPath)) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+      const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+      for (const fw of FRONTEND_FRAMEWORKS) {
+        if (Object.keys(deps).some(d => d === fw.signal || d.startsWith(fw.signal + '/'))) {
+          detected.push(fw.name);
+        }
+      }
+    } catch (e) {
+      // ignore JSON parse errors
+    }
+  }
+  // Flutter via pubspec.yaml
+  if (fs.existsSync(path.join(projectRoot, 'pubspec.yaml'))) {
+    const content = fs.readFileSync(path.join(projectRoot, 'pubspec.yaml'), 'utf8');
+    if (content.includes('flutter:')) detected.push('flutter');
+  }
+  // Native iOS/Android (heuristic)
+  if (fs.existsSync(path.join(projectRoot, 'ios')) && fs.existsSync(path.join(projectRoot, 'android'))) {
+    detected.push('mobile-native');
+  }
+  return [...new Set(detected)];
+}
+
+/**
+ * Read STACK/DECISION.md and look for UI framework selections.
+ */
+function detectFromStack(projectRoot) {
+  const stackPath = path.join(projectRoot, '.godpowers', 'stack', 'DECISION.md');
+  if (!fs.existsSync(stackPath)) return [];
+  const content = fs.readFileSync(stackPath, 'utf8').toLowerCase();
+  const detected = [];
+  for (const fw of FRONTEND_FRAMEWORKS) {
+    if (content.includes(fw.name.toLowerCase()) || content.includes(fw.signal.toLowerCase())) {
+      detected.push(fw.name);
+    }
+  }
+  return [...new Set(detected)];
+}
+
+/**
+ * Top-level detection: combines manifests + STACK.md + heuristic signals.
+ */
+function isUiProject(projectRoot) {
+  const fromManifests = detectFrameworks(projectRoot);
+  const fromStack = detectFromStack(projectRoot);
+  const all = [...new Set([...fromManifests, ...fromStack])];
+  const signals = [];
+  if (fromManifests.length > 0) signals.push('package-manifests');
+  if (fromStack.length > 0) signals.push('stack-decision');
+  if (fs.existsSync(path.join(projectRoot, 'public'))) signals.push('public-dir');
+  if (fs.existsSync(path.join(projectRoot, 'src/components'))) signals.push('src-components-dir');
+  if (fs.existsSync(path.join(projectRoot, 'app'))) signals.push('app-dir');
+  return {
+    required: all.length > 0,
+    frameworks: all,
+    signals
+  };
+}
+
+/**
+ * Detect if impeccable is installed.
+ * Checks: node_modules, .claude/skills, .cursor/skills, .gemini/skills, etc.
+ */
+function isImpeccableInstalled(projectRoot) {
+  const locations = [];
+  const candidates = [
+    'node_modules/impeccable',
+    'node_modules/@google/design.md',
+    '.claude/skills/impeccable',
+    '.cursor/skills/impeccable',
+    '.gemini/skills/impeccable',
+    '.opencode/skills/impeccable',
+    '.kiro/skills/impeccable',
+    '.qoder/skills/impeccable',
+    '.rovodev/skills/impeccable',
+    '.trae/skills/impeccable',
+    '.trae-cn/skills/impeccable',
+    '.agents/skills/impeccable',
+    '.github/skills/impeccable'
+  ];
+  for (const c of candidates) {
+    if (fs.existsSync(path.join(projectRoot, c))) {
+      locations.push(c);
+    }
+  }
+  // Also check user-home installs
+  const home = process.env.HOME || '';
+  if (home) {
+    const homeCandidates = [
+      '.claude/skills/impeccable',
+      '.cursor/skills/impeccable',
+      '.gemini/skills/impeccable',
+      '.agents/skills/impeccable'
+    ];
+    for (const c of homeCandidates) {
+      if (fs.existsSync(path.join(home, c))) {
+        locations.push(`~/${c}`);
+      }
+    }
+  }
+  return {
+    installed: locations.length > 0,
+    locations
+  };
+}
+
+module.exports = {
+  isUiProject,
+  isImpeccableInstalled,
+  detectFrameworks,
+  detectFromStack,
+  FRONTEND_FRAMEWORKS
+};

package/lib/design-spec.js

@@ -0,0 +1,348 @@
+/**
+ * Design Spec
+ *
+ * Parser and validator for the Google Labs design.md format.
+ * (https://github.com/google-labs-code/design.md)
+ *
+ * A DESIGN.md has YAML frontmatter (tokens) + markdown body (rationale).
+ *
+ * Public API:
+ *   parse(content) -> { frontmatter, body, errors }
+ *   validate(parsed) -> { findings }
+ *   resolveTokens(parsed) -> { findings }  // checks {colors.x} references
+ *   sectionOrder(body) -> { findings }     // verifies canonical order
+ *   contrastCheck(parsed) -> { findings }  // basic WCAG contrast on components
+ *   lint(content) -> { findings, valid }   // run all checks
+ */
+
+const intent = require('./intent');
+
+const VALID_SECTIONS = [
+  'Overview', 'Brand & Style',
+  'Colors',
+  'Typography',
+  'Layout', 'Layout & Spacing',
+  'Elevation & Depth', 'Elevation',
+  'Shapes',
+  'Components',
+  "Do's and Don'ts", 'Dos and Donts'
+];
+
+const SECTION_ORDER = [
+  ['Overview', 'Brand & Style'],
+  ['Colors'],
+  ['Typography'],
+  ['Layout', 'Layout & Spacing'],
+  ['Elevation & Depth', 'Elevation'],
+  ['Shapes'],
+  ['Components'],
+  ["Do's and Don'ts", 'Dos and Donts']
+];
+
+const COMPONENT_PROPS = [
+  'backgroundColor', 'textColor', 'typography',
+  'rounded', 'padding', 'size', 'height', 'width'
+];
+
+/**
+ * Parse a DESIGN.md file: separate YAML frontmatter from markdown body.
+ */
+function parse(content) {
+  const errors = [];
+  if (!content.startsWith('---')) {
+    return { frontmatter: null, body: content, errors: ['Missing YAML frontmatter (file must start with `---`).'] };
+  }
+  const end = content.indexOf('\n---', 3);
+  if (end === -1) {
+    return { frontmatter: null, body: content, errors: ['Frontmatter not closed (missing closing `---`).'] };
+  }
+  const yamlBlock = content.slice(3, end).trim();
+  const body = content.slice(end + 4).trim();
+  let frontmatter = null;
+  try {
+    frontmatter = intent.parseSimpleYaml(yamlBlock);
+  } catch (e) {
+    errors.push(`Frontmatter YAML parse error: ${e.message}`);
+  }
+  return { frontmatter, body, errors };
+}
+
+/**
+ * Validate frontmatter schema: required fields, recognized types.
+ */
+function validate(parsed) {
+  const findings = [];
+  if (!parsed.frontmatter) {
+    findings.push({ severity: 'error', code: 'D-FRONTMATTER', message: 'No frontmatter parsed.' });
+    return { findings };
+  }
+  const fm = parsed.frontmatter;
+  if (!fm.name) {
+    findings.push({ severity: 'error', code: 'D-NAME', message: 'Missing required `name` in frontmatter.' });
+  }
+  if (!fm.description) {
+    findings.push({ severity: 'warning', code: 'D-DESCRIPTION', message: 'Missing `description` in frontmatter.' });
+  }
+  // Color values: must be hex sRGB or oklch() or token reference
+  if (fm.colors && typeof fm.colors === 'object') {
+    for (const [name, val] of Object.entries(fm.colors)) {
+      const v = String(val).trim();
+      if (!isValidColor(v) && !isTokenRef(v)) {
+        findings.push({
+          severity: 'warning',
+          code: 'D-COLOR-FORMAT',
+          message: `Color "${name}" has unusual format: "${v}". Expected hex sRGB or oklch().`
+        });
+      }
+    }
+  }
+  // Typography entries should have fontFamily and fontSize
+  if (fm.typography && typeof fm.typography === 'object') {
+    for (const [name, val] of Object.entries(fm.typography)) {
+      if (typeof val !== 'object') {
+        findings.push({
+          severity: 'error',
+          code: 'D-TYPO-OBJECT',
+          message: `Typography "${name}" must be an object with fontFamily/fontSize/etc.`
+        });
+        continue;
+      }
+      if (!val.fontFamily) {
+        findings.push({
+          severity: 'warning',
+          code: 'D-TYPO-FAMILY',
+          message: `Typography "${name}" missing fontFamily.`
+        });
+      }
+      if (!val.fontSize) {
+        findings.push({
+          severity: 'warning',
+          code: 'D-TYPO-SIZE',
+          message: `Typography "${name}" missing fontSize.`
+        });
+      }
+    }
+  }
+  // Component properties: warn on unknown
+  if (fm.components && typeof fm.components === 'object') {
+    for (const [name, val] of Object.entries(fm.components)) {
+      if (typeof val !== 'object') continue;
+      for (const propKey of Object.keys(val)) {
+        if (!COMPONENT_PROPS.includes(propKey)) {
+          findings.push({
+            severity: 'info',
+            code: 'D-COMP-PROP',
+            message: `Component "${name}" has unknown property "${propKey}". Valid: ${COMPONENT_PROPS.join(', ')}.`
+          });
+        }
+      }
+    }
+  }
+  return { findings };
+}
+
+/**
+ * Resolve token references like {colors.primary}.
+ * Returns findings for unresolved references.
+ */
+function resolveTokens(parsed) {
+  const findings = [];
+  if (!parsed.frontmatter) return { findings };
+  const fm = parsed.frontmatter;
+  const refRegex = /\{([\w.-]+)\}/g;
+  function get(p) {
+    return p.split('.').reduce((acc, k) => (acc ? acc[k] : undefined), fm);
+  }
+  function scan(obj, contextPath) {
+    for (const [k, v] of Object.entries(obj)) {
+      const here = `${contextPath}.${k}`;
+      if (typeof v === 'string') {
+        let m;
+        const r = new RegExp(refRegex.source, 'g');
+        while ((m = r.exec(v)) !== null) {
+          const target = m[1];
+          if (get(target) === undefined) {
+            findings.push({
+              severity: 'error',
+              code: 'D-TOKEN-REF',
+              message: `Unresolved token reference "${m[0]}" at ${here}.`
+            });
+          }
+        }
+      } else if (typeof v === 'object' && v !== null) {
+        scan(v, here);
+      }
+    }
+  }
+  if (fm.components) scan(fm.components, 'components');
+  return { findings };
+}
+
+/**
+ * Verify section order: sections present must appear in canonical order.
+ */
+function sectionOrder(body) {
+  const findings = [];
+  const headings = [];
+  for (const line of body.split('\n')) {
+    const m = line.match(/^##\s+(.+?)\s*$/);
+    if (m) headings.push(m[1].trim());
+  }
+  // Map each heading to its canonical index
+  let lastIdx = -1;
+  for (const h of headings) {
+    let idx = -1;
+    for (let i = 0; i < SECTION_ORDER.length; i++) {
+      if (SECTION_ORDER[i].some(name => name.toLowerCase() === h.toLowerCase())) {
+        idx = i;
+        break;
+      }
+    }
+    if (idx === -1) {
+      findings.push({
+        severity: 'info',
+        code: 'D-SECTION-UNKNOWN',
+        message: `Unknown section "${h}". Allowed: ${VALID_SECTIONS.join(', ')}.`
+      });
+      continue;
+    }
+    if (idx < lastIdx) {
+      findings.push({
+        severity: 'error',
+        code: 'D-SECTION-ORDER',
+        message: `Section "${h}" appears out of order.`
+      });
+    }
+    lastIdx = idx;
+  }
+  // Duplicate sections = error
+  const seen = new Set();
+  for (const h of headings) {
+    if (seen.has(h.toLowerCase())) {
+      findings.push({
+        severity: 'error',
+        code: 'D-SECTION-DUP',
+        message: `Duplicate section "${h}".`
+      });
+    }
+    seen.add(h.toLowerCase());
+  }
+  return { findings };
+}
+
+/**
+ * Compute WCAG contrast ratio for hex colors (basic implementation).
+ * Returns ratio (1-21) or null if color cannot be parsed.
+ */
+function contrastRatio(fg, bg) {
+  function parseHex(c) {
+    const m = c.match(/^#([0-9a-f]{6})$/i);
+    if (!m) return null;
+    return [
+      parseInt(m[1].slice(0, 2), 16) / 255,
+      parseInt(m[1].slice(2, 4), 16) / 255,
+      parseInt(m[1].slice(4, 6), 16) / 255
+    ];
+  }
+  function relLum(rgb) {
+    const lin = rgb.map(c => c <= 0.03928 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4));
+    return 0.2126 * lin[0] + 0.7152 * lin[1] + 0.0722 * lin[2];
+  }
+  const fgC = parseHex(fg);
+  const bgC = parseHex(bg);
+  if (!fgC || !bgC) return null;
+  const lFg = relLum(fgC);
+  const lBg = relLum(bgC);
+  const lighter = Math.max(lFg, lBg);
+  const darker = Math.min(lFg, lBg);
+  return (lighter + 0.05) / (darker + 0.05);
+}
+
+/**
+ * Basic WCAG check on text-on-background components.
+ * Resolves token refs to hex; OKLCH not supported here (warning).
+ */
+function contrastCheck(parsed) {
+  const findings = [];
+  if (!parsed.frontmatter || !parsed.frontmatter.components) return { findings };
+  const fm = parsed.frontmatter;
+  function resolve(value) {
+    if (!value) return null;
+    const m = String(value).match(/^\{([\w.-]+)\}$/);
+    if (!m) return value;
+    return m[1].split('.').reduce((acc, k) => (acc ? acc[k] : undefined), fm);
+  }
+  for (const [name, props] of Object.entries(fm.components)) {
+    if (typeof props !== 'object') continue;
+    const fg = resolve(props.textColor);
+    const bg = resolve(props.backgroundColor);
+    if (!fg || !bg) continue;
+    if (typeof fg !== 'string' || typeof bg !== 'string') continue;
+    if (!fg.startsWith('#') || !bg.startsWith('#')) {
+      // OKLCH or unknown; skip (rendering engine handles)
+      continue;
+    }
+    const ratio = contrastRatio(fg, bg);
+    if (ratio === null) continue;
+    if (ratio < 4.5) {
+      findings.push({
+        severity: 'error',
+        code: 'D-CONTRAST',
+        message: `Component "${name}" contrast ${ratio.toFixed(2)}:1 fails WCAG AA (4.5:1).`
+      });
+    } else if (ratio < 7) {
+      findings.push({
+        severity: 'info',
+        code: 'D-CONTRAST',
+        message: `Component "${name}" contrast ${ratio.toFixed(2)}:1 passes AA but not AAA (7:1).`
+      });
+    }
+  }
+  return { findings };
+}
+
+/**
+ * Convenience: run all checks.
+ */
+function lint(content) {
+  const parsed = parse(content);
+  const findings = [
+    ...parsed.errors.map(e => ({ severity: 'error', code: 'D-PARSE', message: e })),
+    ...validate(parsed).findings,
+    ...sectionOrder(parsed.body || '').findings,
+    ...resolveTokens(parsed).findings,
+    ...contrastCheck(parsed).findings
+  ];
+  const valid = !findings.some(f => f.severity === 'error');
+  return { findings, valid };
+}
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+function isValidColor(v) {
+  if (/^#[0-9a-f]{6}$/i.test(v)) return true;
+  if (/^#[0-9a-f]{8}$/i.test(v)) return true;
+  if (/^oklch\s*\(/i.test(v)) return true;
+  if (/^rgb\s*\(/i.test(v)) return true;
+  if (/^hsl\s*\(/i.test(v)) return true;
+  return false;
+}
+
+function isTokenRef(v) {
+  return /^\{[\w.-]+\}$/.test(v);
+}
+
+module.exports = {
+  parse,
+  validate,
+  resolveTokens,
+  sectionOrder,
+  contrastCheck,
+  contrastRatio,
+  lint,
+  VALID_SECTIONS,
+  SECTION_ORDER,
+  COMPONENT_PROPS
+};