pgserve 2.1.2 → 2.2.0

package/.genie/scripts/helpers/validate-links.js

@@ -1,207 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * Validate Markdown Links Helper
- *
- * Check markdown links for broken references (files and anchors).
- * Detects [text](path) links pointing to non-existent files or anchors.
- *
- * Usage:
- *   node validate-links.js <file-path>     # Check links in file
- *   node validate-links.js <directory>     # Check all .md files in directory
- *
- * Output:
- *   <file>:<line>: Broken link [text](path) - File not found
- *   <file>:<line>: Broken link [text](path#anchor) - Anchor not found
- */
-
-const fs = require('fs');
-const path = require('path');
-
-/**
- * Extract markdown links from text
- * Returns: [{ text, href, line }]
- */
-function extractLinks(content) {
-  const lines = content.split('\n');
-  const links = [];
-  const linkRegex = /\[([^\]]+)\]\(([^)]+)\)/g;
-
-  lines.forEach((line, idx) => {
-    let match;
-    while ((match = linkRegex.exec(line)) !== null) {
-      const text = match[1];
-      const href = match[2];
-
-      // Skip external URLs
-      if (href.startsWith('http://') || href.startsWith('https://')) {
-        continue;
-      }
-
-      links.push({ text, href, line: idx + 1 });
-    }
-  });
-
-  return links;
-}
-
-/**
- * Check if file exists
- */
-function fileExists(filePath, basePath) {
-  const fullPath = path.resolve(path.dirname(basePath), filePath);
-  return fs.existsSync(fullPath);
-}
-
-/**
- * Check if anchor exists in file
- */
-function anchorExists(filePath, anchor, basePath) {
-  try {
-    const fullPath = path.resolve(path.dirname(basePath), filePath);
-    const content = fs.readFileSync(fullPath, 'utf-8');
-
-    // Convert anchor to heading format
-    // #my-heading → ## My Heading or ### My Heading, etc.
-    const headingText = anchor.toLowerCase().replace(/-/g, ' ');
-    const headingRegex = new RegExp(`^#+\\s+${headingText.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}`, 'im');
-
-    return headingRegex.test(content);
-  } catch (err) {
-    return false;
-  }
-}
-
-/**
- * Validate links in file
- */
-function validateFile(filePath) {
-  try {
-    const content = fs.readFileSync(filePath, 'utf-8');
-    const links = extractLinks(content);
-    const issues = [];
-
-    links.forEach(({ text, href, line }) => {
-      // Split href into path and anchor
-      const [linkPath, anchor] = href.split('#');
-
-      // Check if it's just an anchor (same file)
-      if (!linkPath && anchor) {
-        if (!anchorExists(filePath, anchor, filePath)) {
-          issues.push({
-            file: filePath,
-            line,
-            text,
-            href,
-            error: `Anchor not found: #${anchor}`,
-          });
-        }
-        return;
-      }
-
-      // Check if file exists
-      if (!fileExists(linkPath, filePath)) {
-        issues.push({
-          file: filePath,
-          line,
-          text,
-          href,
-          error: 'File not found',
-        });
-        return;
-      }
-
-      // If anchor specified, check if it exists in target file
-      if (anchor && !anchorExists(linkPath, anchor, filePath)) {
-        issues.push({
-          file: filePath,
-          line,
-          text,
-          href,
-          error: `Anchor not found: #${anchor}`,
-        });
-      }
-    });
-
-    return issues;
-  } catch (err) {
-    return [{ file: filePath, error: `Failed to read file: ${err.message}` }];
-  }
-}
-
-/**
- * Validate all .md files in directory
- */
-function validateDirectory(dirPath) {
-  const allIssues = [];
-
-  function scanDir(dir) {
-    const entries = fs.readdirSync(dir, { withFileTypes: true });
-
-    entries.forEach(entry => {
-      const fullPath = path.join(dir, entry.name);
-
-      if (entry.isDirectory() && !entry.name.startsWith('.')) {
-        scanDir(fullPath);
-      } else if (entry.isFile() && entry.name.endsWith('.md')) {
-        const issues = validateFile(fullPath);
-        allIssues.push(...issues);
-      }
-    });
-  }
-
-  scanDir(dirPath);
-  return allIssues;
-}
-
-/**
- * Main
- */
-function main() {
-  const args = process.argv.slice(2);
-
-  if (args.length === 0) {
-    console.error(`
-Usage:
-  node validate-links.js <file-path>     # Check links in single file
-  node validate-links.js <directory>     # Check all .md files recursively
-
-Output:
-  <file>:<line>: Broken link [text](path) - error description
-
-Exit code:
-  0 = All links valid
-  1 = Broken links found
-`);
-    process.exit(1);
-  }
-
-  const target = args[0];
-
-  if (!fs.existsSync(target)) {
-    console.error(`Error: Path not found: ${target}`);
-    process.exit(1);
-  }
-
-  const stat = fs.statSync(target);
-  const issues = stat.isDirectory()
-    ? validateDirectory(target)
-    : validateFile(target);
-
-  if (issues.length === 0) {
-    console.log('All links valid');
-    process.exit(0);
-  }
-
-  issues.forEach(issue => {
-    if (issue.line) {
-      console.log(`${issue.file}:${issue.line}: Broken link [${issue.text}](${issue.href}) - ${issue.error}`);
-    } else {
-      console.log(`${issue.file}: ${issue.error}`);
-    }
-  });
-
-  process.exit(1);
-}
-
-main();

package/.genie/scripts/helpers/validate-paths.js

@@ -1,373 +0,0 @@
-#!/usr/bin/env node
-/**
- * Path Validator - Scans codebase for broken LITERAL file path references
- *
- * Usage:
- *   genie helper validate-paths [--verbose]
- *   genie helper validate-paths --staged  (only scan staged files)
- *
- * Focuses on:
- * - Literal file paths in strings (not imports)
- * - File system operations (readFileSync, existsSync, etc.)
- * - Configuration file paths
- * - Documentation references
- *
- * Ignores:
- * - import/require statements (handled by TypeScript)
- * - Node.js built-in modules
- * - npm packages
- *
- * Exit codes:
- *   0 - All paths valid
- *   1 - Broken paths found
- */
-
-const fs = require('fs');
-const path = require('path');
-const { execSync } = require('child_process');
-
-const WORKSPACE_ROOT = process.cwd();
-const VERBOSE = process.argv.includes('--verbose');
-const STAGED_ONLY = process.argv.includes('--staged');
-
-// Node.js built-in modules (to ignore)
-const BUILTIN_MODULES = new Set([
-  'fs', 'path', 'os', 'util', 'events', 'stream', 'crypto', 'http', 'https',
-  'net', 'url', 'querystring', 'zlib', 'child_process', 'cluster', 'readline',
-  'assert', 'buffer', 'string_decoder', 'tty', 'vm', 'dns', 'dgram', 'timers',
-  'punycode', 'process', 'console', 'module', 'perf_hooks', 'worker_threads',
-  'v8', 'trace_events', 'async_hooks', 'inspector'
-]);
-
-// Results
-const results = {
-  scanned: 0,
-  broken: [],
-  valid: [],
-  exceptions: [],
-};
-
-/**
- * Security: Validate resolved path is within workspace
- * Allows relative paths that resolve inside workspace
- */
-function isPathSafe(resolvedPath) {
-  try {
-    const relative = path.relative(WORKSPACE_ROOT, resolvedPath);
-    // Path is safe if it doesn't escape workspace
-    return !relative.startsWith('..') && !path.isAbsolute(relative);
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Check if it's a module import (not a file path)
- */
-function isModuleImport(pathStr) {
-  // Built-in module
-  if (BUILTIN_MODULES.has(pathStr)) return true;
-
-  // npm package (doesn't start with . or /)
-  if (!/^[./]/.test(pathStr)) return true;
-
-  // Relative import without extension (TypeScript module)
-  if (/^\.\.?\//.test(pathStr) && !/\.(js|ts|json|md|yaml|yml|html|css)$/.test(pathStr)) {
-    return true;
-  }
-
-  return false;
-}
-
-/**
- * Check if path is expected to not exist
- */
-function isException(pathStr) {
-  const exceptions = {
-    runtime: [
-      '.genie/state/current-session.json',
-      '.genie/state/stats-history.json',
-      '.genie/state/forge.log',
-      'dist/cli/genie.js', // Built at compile time
-      'dist/mcp/server.js', // Built at compile time
-    ],
-    userWorkspace: [
-      '.genie/cli/config.yaml',
-      '.genie/config.yaml',
-      '.mcp.json',
-      '.genie/CONTEXT.md',
-      '.genie/MASTER-PLAN.md',
-      '.genie/SESSION-STATE.md',
-      '.genie/TODO.md',
-      '.genie/sleepy-state.json',
-    ],
-    examples: [
-      // Example paths in documentation
-      /^\/path\/to\//,
-      /^\.\/file\./,
-      /\bexample\b/i,
-      /\bmy-custom-/,
-      /\bcustom-deployment/,
-      /\bold-workflow/,
-      /\bdeprecated-spell/,
-      /\bprototype\./,
-      /\/wish\.md$/,
-      /\/identity\.md$/,
-    ],
-    templates: [
-      /\$\{/, /<[^>]+>/, /\[.*?\]/,
-    ],
-  };
-
-  if (exceptions.runtime.includes(pathStr)) return 'runtime';
-  if (exceptions.userWorkspace.includes(pathStr)) return 'user-workspace';
-  if (exceptions.examples.some(regex => regex.test(pathStr))) return 'example';
-  if (exceptions.templates.some(regex => regex.test(pathStr))) return 'template';
-
-  return null;
-}
-
-/**
- * Extract literal file paths from content
- * Only paths that look like actual files (with extensions)
- */
-function extractFilePaths(content, filePath) {
-  const paths = new Set();
-
-  // Skip import/require statements (they're handled by TypeScript/Node.js)
-  const contentWithoutImports = content
-    .replace(/^import\s+.*?from\s+['\"][^'\"]+['\"]/gm, '')
-    .replace(/^export\s+.*?from\s+['\"][^'\"]+['\"]/gm, '')
-    .replace(/require\(['\"][^'\"]+['\"][\),]/g, '');
-
-  // Pattern: file paths with extensions in strings
-  const filePathPattern = /['\"`]([^'\"`]*\.(?:md|json|yaml|yml|sh|html|css|txt|log|cjs))['\"]/g;
-
-  let match;
-  while ((match = filePathPattern.exec(contentWithoutImports)) !== null) {
-    const pathStr = match[1];
-
-    // Skip if it's clearly a module import (TypeScript modules without extension)
-    if (isModuleImport(pathStr)) continue;
-
-    // Skip URLs
-    if (/^https?:\/\//.test(pathStr)) continue;
-
-    // Skip very short paths (likely false positives like ".md" in endsWith('.md'))
-    if (pathStr.length < 5) continue;
-
-    // Skip template variables and patterns
-    if (/^\$\{|\}$/.test(pathStr)) continue;
-
-    // Skip if it's just an extension (e.g., ".md" from .endsWith('.md'))
-    if (/^\.[\w]+$/.test(pathStr)) continue;
-
-    // Skip glob patterns (**, *, ?, {, })
-    if (/[\*\?\{\}]/.test(pathStr)) continue;
-
-    // Skip template filenames (e.g., ".template.md")
-    if (/^\.template\./.test(pathStr)) continue;
-
-    paths.add(pathStr);
-  }
-
-  return Array.from(paths);
-}
-
-/**
- * Validate a path
- */
-function validatePath(pathStr, sourceFile) {
-  // Check exceptions first
-  const exceptionType = isException(pathStr);
-  if (exceptionType) {
-    results.exceptions.push({ path: pathStr, source: sourceFile, type: exceptionType });
-    return { valid: true, reason: exceptionType };
-  }
-
-  // Resolve path
-  let resolvedPath;
-  if (pathStr.startsWith('.genie/') || pathStr.startsWith('src/') || pathStr.startsWith('dist/')) {
-    // Workspace-relative paths (always resolve from workspace root)
-    resolvedPath = path.resolve(WORKSPACE_ROOT, pathStr);
-  } else if (pathStr.startsWith('./') || pathStr.startsWith('../')) {
-    // Relative to source file
-    resolvedPath = path.resolve(path.dirname(sourceFile), pathStr);
-  } else if (pathStr.startsWith('/')) {
-    // Absolute
-    resolvedPath = pathStr;
-  } else {
-    // Default: relative to workspace root
-    resolvedPath = path.resolve(WORKSPACE_ROOT, pathStr);
-  }
-
-  // Security check (after resolving)
-  if (!isPathSafe(resolvedPath)) {
-    return { valid: false, reason: 'unsafe-path', resolvedPath };
-  }
-
-  // Check if exists
-  try {
-    fs.accessSync(resolvedPath, fs.constants.R_OK);
-    results.valid.push({ path: pathStr, source: sourceFile });
-    return { valid: true, resolvedPath };
-  } catch {
-    return { valid: false, reason: 'not-found', resolvedPath };
-  }
-}
-
-/**
- * Scan a file
- */
-function scanFile(filePath) {
-  results.scanned++;
-
-  try {
-    const content = fs.readFileSync(filePath, 'utf8');
-    const paths = extractFilePaths(content, filePath);
-
-    for (const pathStr of paths) {
-      const result = validatePath(pathStr, filePath);
-
-      if (!result.valid) {
-        results.broken.push({
-          path: pathStr,
-          source: filePath.replace(WORKSPACE_ROOT + '/', ''),
-          reason: result.reason,
-          resolved: result.resolvedPath,
-        });
-      }
-    }
-  } catch (err) {
-    if (VERBOSE) {
-      console.error(`Error scanning ${filePath}: ${err.message}`);
-    }
-  }
-}
-
-/**
- * Scan directory recursively
- */
-function scanDirectory(dir, extensions) {
-  try {
-    const entries = fs.readdirSync(dir, { withFileTypes: true });
-
-    for (const entry of entries) {
-      const fullPath = path.join(dir, entry.name);
-
-      if (entry.isDirectory()) {
-        // Skip
-        if (['node_modules', '.git', 'dist'].includes(entry.name)) continue;
-        if (fullPath.includes('.genie/reports')) continue;
-        if (fullPath.includes('.genie/wishes')) continue;
-        if (fullPath.includes('.genie/qa')) continue;
-
-        scanDirectory(fullPath, extensions);
-      } else if (entry.isFile()) {
-        if (extensions.some(ext => entry.name.endsWith(ext))) {
-          scanFile(fullPath);
-        }
-      }
-    }
-  } catch (err) {
-    if (VERBOSE) {
-      console.error(`Error scanning ${dir}: ${err.message}`);
-    }
-  }
-}
-
-/**
- * Get staged files only
- */
-function getStagedFiles() {
-  try {
-    const output = execSync('git diff --cached --name-only --diff-filter=ACMR', {
-      encoding: 'utf8',
-      cwd: WORKSPACE_ROOT
-    });
-    return output.trim().split('\n').filter(Boolean).map(f => path.join(WORKSPACE_ROOT, f));
-  } catch {
-    return [];
-  }
-}
-
-/**
- * Main
- */
-function main() {
-  console.log('🔍 Path Validator - Scanning for broken file references\n');
-
-  if (STAGED_ONLY) {
-    // Only scan staged files
-    console.log('📂 Scanning staged files only...');
-    const stagedFiles = getStagedFiles();
-
-    if (stagedFiles.length === 0) {
-      console.log('No staged files to scan\n');
-      process.exit(0);
-    }
-
-    stagedFiles.forEach(file => {
-      if (fs.existsSync(file) && (file.endsWith('.ts') || file.endsWith('.js') || file.endsWith('.md'))) {
-        scanFile(file);
-      }
-    });
-  } else {
-    // Full codebase scan
-    console.log('📂 Scanning source files...');
-    scanDirectory(path.join(WORKSPACE_ROOT, 'src'), ['.ts', '.js']);
-
-    console.log('📂 Scanning documentation...');
-    scanDirectory(path.join(WORKSPACE_ROOT, '.genie'), ['.md']);
-    if (fs.existsSync(path.join(WORKSPACE_ROOT, 'docs'))) {
-      scanDirectory(path.join(WORKSPACE_ROOT, 'docs'), ['.md']);
-    }
-
-    // Scan scripts
-    if (fs.existsSync(path.join(WORKSPACE_ROOT, '.genie/scripts'))) {
-      console.log('📂 Scanning scripts...');
-      scanDirectory(path.join(WORKSPACE_ROOT, '.genie/scripts'), ['.sh', '.js', '.cjs']);
-    }
-  }
-
-  // Report
-  console.log(`\n✅ Scanned ${results.scanned} files\n`);
-
-  if (results.broken.length > 0) {
-    console.log(`❌ Found ${results.broken.length} broken path reference(s):\n`);
-
-    results.broken.forEach(({ path, source, reason, resolved }) => {
-      console.log(`  📄 ${path}`);
-      console.log(`     Source: ${source}`);
-      console.log(`     Reason: ${reason}`);
-      if (resolved && reason === 'not-found') {
-        console.log(`     Expected: ${resolved}`);
-      }
-      console.log();
-    });
-
-    process.exit(1);
-  } else {
-    console.log('✅ No broken paths found!');
-    console.log(`✅ Validated ${results.valid.length} file path references`);
-
-    if (VERBOSE) {
-      console.log(`\nℹ️  Exceptions: ${results.exceptions.length} (runtime/user-workspace files)`);
-
-      // Show some examples
-      if (results.valid.length > 0) {
-        console.log(`\nℹ️  Sample valid paths:`);
-        results.valid.slice(0, 5).forEach(({ path }) => {
-          console.log(`  ✓ ${path}`);
-        });
-        if (results.valid.length > 5) {
-          console.log(`  ... and ${results.valid.length - 5} more`);
-        }
-      }
-    }
-
-    process.exit(0);
-  }
-}
-
-main();

package/.genie/spells/README.md

@@ -1,9 +0,0 @@
-
-# Forge Workflows (Global)
-
-Global Forge workflows applicable across domains. Core `forge` agent delegates here when a domain-agnostic flow is sufficient. Domain-specific flows live under each collective (e.g., `code/workflows/forge.md`).
-
-## Structure
-- One file per workflow under `workflows/forge/`
-- Keep flows atomic, with clear inputs, steps, and evidence
-

package/.genie/spells/ace-protocol.md

@@ -1,118 +0,0 @@
-# ACE Protocol - Evidence-Based Editing Requirements
-
-**Purpose:** Mandatory behavioral triggers for all framework edits. ACE (Agentic Context Engineering) ensures data-driven optimization.
-
-**Load Priority:** 2 (immediately after know-yourself.md)
-
----
-
-## 🔴 MANDATORY: Before Editing ANY File
-
-**Use semantic deduplication to prevent duplicate learnings:**
-
-```bash
-genie helper embeddings "new learning text" file.md "Section Name"
-```
-
-**Decision Rules:**
-- `similarity > 0.85` → **DUPLICATE** - Merge with existing or skip
-- `similarity 0.70-0.85` → **RELATED** - Evaluate carefully, usually merge
-- `similarity < 0.70` → **DIFFERENT** - Safe to add new learning
-
-**When to use:**
-- Before adding ANY new learning to spells/agents
-- When user teaches new pattern
-- When learn agent is invoked
-- Part of grow-and-refine protocol
-
----
-
-## 🔴 MANDATORY: Before Committing ANY Change
-
-**Measure token impact of all framework changes:**
-
-```bash
-genie helper count-tokens file.md
-
-# Compare before/after (for savings calculation)
-genie helper count-tokens --before=old.md --after=new.md
-```
-
-**Record in commit message:**
-- Tokens before/after
-- Net change (+/- tokens)
-- Justify growth if adding content
-
-**When to use:**
-- Before every framework commit
-- When validating token efficiency (Amendment #6)
-- Required by Amendment #8
-
----
-
-## 🔴 MANDATORY: After Executing ANY QA Scenario
-
-**Track learning effectiveness with counter updates:**
-
-```bash
-# Record helpful outcome (scenario passed, learning helped)
-genie helper bullet-counter learn-042 --helpful
-
-# Record harmful outcome (scenario failed, learning caused issue)
-genie helper bullet-counter learn-042 --harmful
-
-# Query current counters
-genie helper bullet-counter learn-042
-```
-
-**Value Ratio Formula:**
-```
-ratio = helpful / max(harmful, 1)
-```
-
-**Categorization Thresholds:**
-- `ratio ≥ 3.0` → **HIGH_VALUE** - Strengthen with examples, reinforce
-- `ratio 1.0-3.0` → **MEDIUM_VALUE** - Keep as-is, working well
-- `ratio 0.5-1.0` → **LOW_VALUE** - Refine wording or clarify
-- `ratio < 0.5` → **HARMFUL** - Remove or completely rewrite
-
-**When to use:**
-- After manual QA scenario execution
-- During multi-epoch testing (future automation)
-- When gathering evidence for optimization decisions
-
----
-
-## Why This Matters
-
-**Without ACE:**
-- Duplicate learnings accumulate → context bloat
-- Framework grows without measurement → token waste
-- Intuition-based optimization → no evidence
-
-**With ACE:**
-- Semantic dedup catches paraphrases → no duplicates
-- Token measurement before commit → controlled growth
-- Evidence-based optimization → data-driven improvements
-
-**Current Status:**
-- ✅ All ACE helpers operational (embeddings, bullet-counter, count-tokens)
-- ✅ 912 learnings structured with counters `[id] helpful=N harmful=M: content`
-- ⚠️ Multi-epoch automation pending (Phase 5: Issue #384)
-
----
-
-## Cross-References
-
-**Related Amendments:**
-- Amendment #6: Token Efficiency - Fast, Fit, Smart, Sexy
-- Amendment #8: Token Counting Protocol - Official Helper Only
-- Amendment #12: ACE Protocol - Evidence-Based Framework Optimization
-
-**Related Spells:**
-- `learn.md` - Detailed ACE workflows and grow-and-refine protocol
-- `know-yourself.md` - Core identity and self-awareness
-
-**Documentation:**
-- ACE architecture: `/tmp/genie-ace-architecture-complete.md`
-- Phase 5 automation: GitHub Issue #384