@esoteric-logic/praxis-harness 2.13.0 → 2.15.0

package/bin/prompt-blocks.js

@@ -0,0 +1,145 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const yaml = require('js-yaml');
+
+const { BLOCKS_DIR, PROFILES_DIR, parseFrontmatter } = require('../lib/loader');
+
+/** Collect all blocks from the blocks directory. */
+function loadAllBlocks() {
+  const blocks = [];
+  if (!fs.existsSync(BLOCKS_DIR)) return blocks;
+
+  for (const category of fs.readdirSync(BLOCKS_DIR)) {
+    const catDir = path.join(BLOCKS_DIR, category);
+    if (!fs.statSync(catDir).isDirectory()) continue;
+
+    for (const file of fs.readdirSync(catDir)) {
+      if (!file.endsWith('.md')) continue;
+      const content = fs.readFileSync(path.join(catDir, file), 'utf8');
+      const { meta, body } = parseFrontmatter(content);
+      const hasCondensed = body.includes('<!-- CONDENSED -->');
+      blocks.push({
+        id: meta.id || file.replace('.md', ''),
+        category,
+        platforms: meta.platforms || [],
+        charEstimate: meta.char_estimate || null,
+        description: meta.description || '',
+        tags: meta.tags || [],
+        hasCondensed,
+        actualChars: body.length,
+        file: `prompts/blocks/${category}/${file}`,
+      });
+    }
+  }
+  return blocks;
+}
+
+/** Collect all profiles and their block references. */
+function loadAllProfiles() {
+  const profiles = {};
+  if (!fs.existsSync(PROFILES_DIR)) return profiles;
+
+  for (const file of fs.readdirSync(PROFILES_DIR)) {
+    if (!file.endsWith('.yaml')) continue;
+    const name = file.replace('.yaml', '');
+    const content = yaml.load(fs.readFileSync(path.join(PROFILES_DIR, file), 'utf8'));
+    const blockIds = content.blocks
+      ? Object.values(content.blocks).filter(Array.isArray).flat()
+      : [];
+    profiles[name] = { ...content, blockIds };
+  }
+  return profiles;
+}
+
+// ── CLI ──────────────────────────────────────────────────────
+
+function main() {
+  const args = process.argv.slice(2);
+
+  if (args.includes('--help')) {
+    console.log('Usage: prompt-blocks [options]');
+    console.log('Options:');
+    console.log('  --category <cat>   Filter by category (identity, behaviors, domains, formats, context)');
+    console.log('  --profile <name>   Show blocks used by a specific profile');
+    console.log('  --unused           Show blocks not referenced by any profile');
+    console.log('  --tags             Group output by tags');
+    process.exit(0);
+  }
+
+  const blocks = loadAllBlocks();
+  const profiles = loadAllProfiles();
+
+  // Resolve profile inheritance to get full block lists
+  for (const [name, profile] of Object.entries(profiles)) {
+    if (profile.extends && profiles[profile.extends]) {
+      const baseIds = profiles[profile.extends].blockIds || [];
+      profile.blockIds = [...new Set([...baseIds, ...profile.blockIds])];
+    }
+  }
+
+  // All block IDs referenced by any profile
+  const allProfileBlockIds = new Set();
+  for (const profile of Object.values(profiles)) {
+    for (const id of profile.blockIds) allProfileBlockIds.add(id);
+  }
+
+  // Filter by category
+  const catIdx = args.indexOf('--category');
+  let filtered = blocks;
+  if (catIdx !== -1 && args[catIdx + 1]) {
+    const cat = args[catIdx + 1];
+    filtered = blocks.filter((b) => b.category === cat);
+  }
+
+  // Filter by profile
+  const profIdx = args.indexOf('--profile');
+  if (profIdx !== -1 && args[profIdx + 1]) {
+    const profName = args[profIdx + 1];
+    const profile = profiles[profName];
+    if (!profile) {
+      console.error(`Profile not found: ${profName}`);
+      process.exit(1);
+    }
+    const profileIds = new Set(profile.blockIds);
+    filtered = blocks.filter((b) => profileIds.has(b.id));
+  }
+
+  // Unused mode
+  if (args.includes('--unused')) {
+    filtered = blocks.filter((b) => !allProfileBlockIds.has(b.id));
+    if (filtered.length === 0) {
+      console.log('All blocks are referenced by at least one profile.');
+      return;
+    }
+    console.log(`${filtered.length} unused block(s):\n`);
+  }
+
+  // Display
+  console.log(`${'ID'.padEnd(28)} ${'Category'.padEnd(12)} ${'Platforms'.padEnd(35)} ${'Chars'.padEnd(8)} Condensed`);
+  console.log('-'.repeat(95));
+
+  for (const block of filtered) {
+    const platforms = block.platforms.join(', ') || 'all';
+    const chars = block.charEstimate ? String(block.charEstimate) : '—';
+    const condensed = block.hasCondensed ? 'yes' : '—';
+    console.log(
+      `${block.id.padEnd(28)} ${block.category.padEnd(12)} ${platforms.padEnd(35)} ${chars.padEnd(8)} ${condensed}`
+    );
+  }
+
+  console.log(`\nTotal: ${filtered.length} blocks`);
+
+  // Show profile usage summary
+  if (!args.includes('--unused') && profIdx === -1) {
+    console.log('\nProfile usage:');
+    for (const [name, profile] of Object.entries(profiles)) {
+      if (name === '_base') continue;
+      console.log(`  ${name}: ${profile.blockIds.length} blocks`);
+    }
+  }
+}
+
+main();

package/bin/prompt-compile.js

@@ -0,0 +1,313 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const yaml = require('js-yaml');
+
+const {
+  TARGETS,
+  PROMPTS_DIR,
+  loadPraxisConfig,
+  loadProfile,
+  mergeProfiles,
+  loadBlocks,
+  applyOverrides,
+} = require('../lib/loader');
+
+const {
+  interpolate,
+  findUnresolved,
+  assembleClaudeCode,
+  assembleClaudeProject,
+  assemblePerplexitySpace,
+} = require('../lib/assemblers');
+
+const PROJECTS_DIR = path.join(PROMPTS_DIR, 'projects');
+
+const CHAR_BUDGETS = {
+  'claude-code': Infinity,
+  'claude-project': 2500,
+  'perplexity-space': 4000,
+};
+
+// Global flags set by CLI parser
+let PREVIEW_MODE = false;
+let DIFF_MODE = false;
+let STRICT_MODE = false;
+
+// ── Helpers ──────────────────────────────────────────────────
+
+function fail(msg) {
+  console.error(`\x1b[31mERROR:\x1b[0m ${msg}`);
+  process.exit(1);
+}
+
+function warn(msg) {
+  console.error(`\x1b[33mWARN:\x1b[0m ${msg}`);
+}
+
+function ok(msg) {
+  console.log(`\x1b[32m✓\x1b[0m ${msg}`);
+}
+
+// ── Main ─────────────────────────────────────────────────────
+
+/** Validate a standalone project — check files exist, report char budgets. */
+function validateStandalone(projectName, projectDir, projectConfig) {
+  console.log(`\nValidating standalone: ${projectName}`);
+
+  const inventory = [
+    { file: 'system-prompt.md', budget: Infinity, required: true, label: 'System Prompt (Claude Projects)' },
+    { file: 'CLAUDE.md', budget: Infinity, required: false, label: 'Claude Code' },
+    { file: 'space-instructions.md', budget: CHAR_BUDGETS['perplexity-space'], required: false, label: 'Perplexity Space' },
+    { file: 'project-instructions.md', budget: CHAR_BUDGETS['claude-project'], required: false, label: 'Claude Project' },
+  ];
+
+  let missingGenerable = [];
+
+  for (const item of inventory) {
+    const filePath = path.join(projectDir, item.file);
+    if (fs.existsSync(filePath)) {
+      const content = fs.readFileSync(filePath, 'utf8');
+      const charCount = content.length;
+      const lineCount = content.split('\n').length;
+      const sizeInfo = item.budget < Infinity
+        ? `${charCount} chars (budget: ${item.budget})`
+        : `${charCount} chars, ${lineCount} lines`;
+
+      if (charCount > item.budget) {
+        warn(`${item.file} exceeds budget: ${charCount} chars (limit: ${item.budget})`);
+      } else {
+        ok(`${item.file} — ${sizeInfo}`);
+      }
+    } else if (item.required) {
+      warn(`${item.file} MISSING — standalone projects require a system prompt`);
+    } else {
+      missingGenerable.push(item.file);
+    }
+  }
+
+  if (missingGenerable.length > 0) {
+    console.log(`\n  Missing platform outputs: ${missingGenerable.join(', ')}`);
+    console.log('  Run /px-prompt ' + projectName + ' to auto-generate from system-prompt.md');
+  }
+
+  // Version consistency check
+  const systemPromptPath = path.join(projectDir, 'system-prompt.md');
+  if (fs.existsSync(systemPromptPath) && projectConfig.version) {
+    const spContent = fs.readFileSync(systemPromptPath, 'utf8');
+    const versionMatch = spContent.match(/^version:\s*["']?([^"'\n]+)/m);
+    if (versionMatch && versionMatch[1].trim() !== String(projectConfig.version).trim()) {
+      warn(`Version mismatch: prompt-config.yaml says "${projectConfig.version}" but system-prompt.md says "${versionMatch[1].trim()}"`);
+    }
+  }
+
+  // Check for reference files
+  const refsDir = path.join(projectDir, 'references');
+  if (fs.existsSync(refsDir)) {
+    const refs = fs.readdirSync(refsDir).filter((f) => f.endsWith('.md'));
+    if (refs.length > 0) {
+      ok(`${refs.length} reference file(s): ${refs.join(', ')}`);
+    }
+  }
+}
+
+function compileProject(projectName, targets) {
+  const projectDir = path.join(PROJECTS_DIR, projectName);
+  const configPath = path.join(projectDir, 'prompt-config.yaml');
+
+  if (!fs.existsSync(configPath)) {
+    fail(`Project config not found: ${configPath}\nRun /px-prompt <project-name> to create one.`);
+  }
+
+  const projectConfig = yaml.load(fs.readFileSync(configPath, 'utf8'));
+
+  // Standalone mode: validate files, report budgets, skip compilation
+  if (projectConfig.mode === 'standalone') {
+    validateStandalone(projectName, projectDir, projectConfig);
+    return;
+  }
+
+  const praxisConfig = loadPraxisConfig();
+
+  // Build vars map: project vars + praxis config + project name
+  const vars = {
+    ...praxisConfig,
+    ...(projectConfig.vars || {}),
+    project: projectConfig.project || projectName,
+  };
+
+  // Load profile: from named profile, project-local blocks, or _base fallback
+  let profile;
+  if (projectConfig.profile) {
+    profile = loadProfile(projectConfig.profile, fail);
+  } else if (projectConfig.blocks) {
+    const base = loadProfile('_base', fail);
+    profile = mergeProfiles(base, { blocks: projectConfig.blocks });
+  } else {
+    profile = loadProfile('_base', fail);
+  }
+  profile = applyOverrides(profile, projectConfig.overrides);
+
+  const profileName = projectConfig.profile || 'project-local';
+  console.log(`\nCompiling: ${projectName} (profile: ${profileName})`);
+
+  const assemblers = {
+    'claude-code': assembleClaudeCode,
+    'claude-project': assembleClaudeProject,
+    'perplexity-space': assemblePerplexitySpace,
+  };
+
+  const outputNames = {
+    'claude-code': 'CLAUDE.md',
+    'claude-project': 'project-instructions.md',
+    'perplexity-space': 'space-instructions.md',
+  };
+
+  for (const target of targets) {
+    const blocks = loadBlocks(profile, target, warn);
+    let output = assemblers[target](blocks, projectConfig, vars);
+
+    // Interpolate variables
+    output = interpolate(output, vars);
+
+    // Validate no unresolved placeholders
+    const unresolved = findUnresolved(output);
+    if (unresolved.length > 0) {
+      if (STRICT_MODE) {
+        fail(`[strict] Unresolved placeholders in ${target}: ${unresolved.join(', ')}`);
+      }
+      warn(`Unresolved placeholders in ${target}: ${unresolved.join(', ')}`);
+    }
+
+    // Check character budget
+    const budget = CHAR_BUDGETS[target];
+    if (output.length > budget) {
+      if (STRICT_MODE) {
+        fail(`[strict] ${target} exceeds budget: ${output.length} chars (limit: ${budget})`);
+      }
+      warn(`${target} output exceeds budget: ${output.length} chars (limit: ${budget})`);
+    }
+
+    const outputPath = path.join(projectDir, outputNames[target]);
+
+    // Preview mode: print to stdout instead of writing
+    if (PREVIEW_MODE) {
+      console.log(`\n--- ${outputNames[target]} (${output.length} chars) ---`);
+      console.log(output);
+      continue;
+    }
+
+    // Diff mode: show diff against existing file before writing
+    if (DIFF_MODE && fs.existsSync(outputPath)) {
+      const existing = fs.readFileSync(outputPath, 'utf8');
+      if (existing === output) {
+        ok(`${outputNames[target]} — unchanged (${output.length} chars)`);
+        continue;
+      }
+      console.log(`\n--- ${outputNames[target]} changed ---`);
+      const existingLines = existing.split('\n');
+      const outputLines = output.split('\n');
+      const addedCount = outputLines.filter((l) => !existingLines.includes(l)).length;
+      const removedCount = existingLines.filter((l) => !outputLines.includes(l)).length;
+      console.log(`  +${addedCount} lines added, -${removedCount} lines removed`);
+    }
+
+    fs.writeFileSync(outputPath, output, 'utf8');
+    ok(`${outputNames[target]} — ${output.length} chars → ${outputPath}`);
+  }
+}
+
+// ── CLI ──────────────────────────────────────────────────────
+
+function main() {
+  const args = process.argv.slice(2);
+
+  if (args.length === 0 || args.includes('--help')) {
+    console.log('Usage: prompt-compile <project-name|--all> [options]');
+    console.log('Options:');
+    console.log('  --target <target>  claude-code|claude-project|perplexity-space|all');
+    console.log('  --preview          Print output to stdout without writing files');
+    console.log('  --diff             Show what changed before writing');
+    console.log('  --strict           Exit with error on budget overruns or unresolved vars');
+    console.log('  --list             List all projects with mode and file status');
+    process.exit(0);
+  }
+
+  // --list mode: show all projects
+  if (args.includes('--list')) {
+    const projectDirs = fs.readdirSync(PROJECTS_DIR)
+      .filter((d) => d !== '_template' && fs.statSync(path.join(PROJECTS_DIR, d)).isDirectory());
+    if (projectDirs.length === 0) {
+      console.log('No projects found.');
+      process.exit(0);
+    }
+    console.log(`${'Project'.padEnd(20)} ${'Mode'.padEnd(12)} ${'System Prompt'.padEnd(15)} ${'Claude Proj'.padEnd(15)} ${'Perplexity'.padEnd(15)} ${'CLAUDE.md'.padEnd(12)} Refs`);
+    console.log('-'.repeat(95));
+    for (const name of projectDirs) {
+      const dir = path.join(PROJECTS_DIR, name);
+      const cfgPath = path.join(dir, 'prompt-config.yaml');
+      const cfg = fs.existsSync(cfgPath) ? yaml.load(fs.readFileSync(cfgPath, 'utf8')) : {};
+      const mode = cfg.mode || 'compiled';
+      const fileStatus = (f) => {
+        const p = path.join(dir, f);
+        if (!fs.existsSync(p)) return '—';
+        return `${fs.readFileSync(p, 'utf8').length} chars`;
+      };
+      const refsDir = path.join(dir, 'references');
+      const refCount = fs.existsSync(refsDir)
+        ? fs.readdirSync(refsDir).filter((f) => f.endsWith('.md')).length
+        : 0;
+      console.log(
+        `${name.padEnd(20)} ${mode.padEnd(12)} ${fileStatus('system-prompt.md').padEnd(15)} ${fileStatus('project-instructions.md').padEnd(15)} ${fileStatus('space-instructions.md').padEnd(15)} ${fileStatus('CLAUDE.md').padEnd(12)} ${refCount}`
+      );
+    }
+    process.exit(0);
+  }
+
+  // Parse global flags
+  PREVIEW_MODE = args.includes('--preview');
+  DIFF_MODE = args.includes('--diff');
+  STRICT_MODE = args.includes('--strict');
+
+  // Parse --target flag
+  const targetIdx = args.indexOf('--target');
+  let targets = TARGETS;
+  if (targetIdx !== -1 && args[targetIdx + 1]) {
+    const targetArg = args[targetIdx + 1];
+    if (TARGETS.includes(targetArg)) {
+      targets = [targetArg];
+    } else if (targetArg !== 'all') {
+      fail(`Unknown target: ${targetArg}. Use: ${TARGETS.join(', ')}, all`);
+    }
+  }
+
+  // Determine project(s) to compile
+  const flagValues = new Set();
+  if (targetIdx !== -1 && args[targetIdx + 1]) {
+    flagValues.add(args[targetIdx + 1]);
+  }
+  const projectArg = args.find((a) => !a.startsWith('--') && !flagValues.has(a));
+
+  if (args.includes('--all')) {
+    const projectDirs = fs.readdirSync(PROJECTS_DIR)
+      .filter((d) => d !== '_template' && fs.statSync(path.join(PROJECTS_DIR, d)).isDirectory());
+
+    if (projectDirs.length === 0) {
+      fail('No projects found in prompts/projects/');
+    }
+
+    for (const projectName of projectDirs) {
+      compileProject(projectName, targets);
+    }
+  } else if (projectArg) {
+    compileProject(projectArg, targets);
+  } else {
+    fail('Specify a project name or use --all');
+  }
+
+  console.log('\nDone.');
+}
+
+main();

package/kits/web-designer/rules/web-design.md

@@ -9,25 +9,30 @@ paths:
   - "design-system/**"
   - "styles/**"
 ---
+
 # Web Design — Rules
-# Scope: Frontend component and design system files
-# Part of: web-designer AI-Kit
+
+Scope: Frontend component and design system files.
+Part of: web-designer AI-Kit.
 
 ## Invariants (BLOCK on violation)
 
 ### Design Tokens
+
 - No inline styles in component files — use design tokens or Tailwind utilities.
 - No hardcoded color values (`#fff`, `rgb(...)`) — must reference token variables
   (`var(--color-primary)`, Tailwind classes, or theme values).
 - Check: `grep -rn "color:" src/components/ | grep -v "var(--" | grep -v "tailwind"`
 
 ### Semantic HTML
+
 - No `<div>` click handlers — use `<button>` for actions, `<a>` for navigation.
 - Check: `grep -rn 'onClick.*<div' src/components/`
 - Every interactive element must have explicit keyboard handling (`onKeyDown` or
   native keyboard support via semantic elements).
 
 ### Accessibility
+
 - Every `<img>` must have an `alt` attribute (empty `alt=""` for decorative images).
 - Form inputs must have associated `<label>` elements or `aria-label`.
 - Color contrast must meet WCAG AA minimum (4.5:1 for text, 3:1 for large text).
@@ -35,6 +40,7 @@ paths:
 ## Conventions (WARN on violation)
 
 ### Component Structure
+
 - Component files follow `ComponentName/index.tsx` + `ComponentName.module.css`
   (or `ComponentName.tsx` with Tailwind — pick one pattern per project, don't mix).
 - Design tokens live in `design-system/tokens/` or equivalent.
@@ -42,21 +48,25 @@ paths:
   live in `src/components/[page-name]/`.
 
 ### Animation and Motion
+
 - Animation durations use token values, not magic numbers.
 - Respect `prefers-reduced-motion` — wrap animations in media query.
 - CSS transitions preferred over JS animation libraries for simple effects.
 
 ### Performance
+
 - Images have explicit `width` and `height` to prevent CLS (Cumulative Layout Shift).
 - Lazy-load images below the fold (`loading="lazy"`).
 - No layout-triggering CSS in animation loops (`top`, `left`, `width`, `height` — use `transform` and `opacity`).
 
 ### Design System Hygiene
+
 - New components must use existing tokens before creating new ones.
 - If a new token is needed: add to the token file, not inline.
 - Component variants use a consistent API pattern (props, not className overrides).
 
 ## Verification Commands
+
 ```bash
 # Token compliance — find hardcoded colors
 grep -rn "color:" src/components/ | grep -v "var(--" | grep -v "token" | grep -v "tailwind"
@@ -75,5 +85,6 @@ npx axe-core src/ --exit
 ```
 
 ## Removal Condition
+
 Remove when the project's design system is mature with >90% component coverage
 and design review is handled by a dedicated design tool or CI pipeline.