@esoteric-logic/praxis-harness 2.16.0 → 3.0.0

package/bin/praxis.js

@@ -384,6 +384,77 @@ function uninstall() {
   console.log('');
 }
 
+// ── Scaffold ────────────────────────────────────────────────
+
+function scaffold() {
+  const subCmd = process.argv[3];
+  if (subCmd !== 'new') {
+    fail('Usage: praxis scaffold new <project-name> [--profile <name>] [--description "<text>"]');
+  }
+
+  const projectName = process.argv[4];
+  if (!projectName || projectName.startsWith('--')) {
+    fail('Specify a project name: praxis scaffold new <project-name>');
+  }
+
+  const PROJECTS_DIR = path.join(PKG_DIR, 'prompts', 'projects');
+  const TEMPLATE_DIR = path.join(PROJECTS_DIR, '_template');
+  const projectDir = path.join(PROJECTS_DIR, projectName);
+
+  if (fs.existsSync(projectDir)) {
+    fail(`Project already exists: ${projectDir}`);
+  }
+
+  // Parse flags
+  const args = process.argv.slice(5);
+  let profileName = '_base';
+  let description = '';
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--profile' && args[i + 1]) { profileName = args[++i]; }
+    if (args[i] === '--description' && args[i + 1]) { description = args[++i]; }
+  }
+
+  header(`Scaffolding project: ${projectName}`);
+
+  // Create project directory structure
+  fs.mkdirSync(path.join(projectDir, 'references'), { recursive: true });
+  fs.mkdirSync(path.join(projectDir, 'knowledge'), { recursive: true });
+
+  // Read template config
+  const templatePath = path.join(TEMPLATE_DIR, 'prompt-config.yaml');
+  if (!fs.existsSync(templatePath)) {
+    fail(`Template not found: ${templatePath}`);
+  }
+  let configContent = fs.readFileSync(templatePath, 'utf8');
+  configContent = configContent.replace('{{project_name}}', projectName);
+  configContent = configContent.replace('{{project_description}}', description);
+
+  configContent = configContent.replace('profile: null', `profile: ${profileName}`);
+
+  fs.writeFileSync(path.join(projectDir, 'prompt-config.yaml'), configContent, 'utf8');
+
+  ok(`Created ${projectDir}/prompt-config.yaml`);
+  ok(`Created ${projectDir}/references/`);
+  ok(`Created ${projectDir}/knowledge/`);
+  dim(`Profile: ${profileName}`);
+  if (description) dim(`Description: ${description}`);
+
+  // Preview compile
+  console.log('');
+  dim('Preview compiled output:');
+  spawnSync('node', [
+    path.join(PKG_DIR, 'bin', 'prompt-compile.js'),
+    projectName, '--preview',
+  ], { stdio: 'inherit', cwd: PKG_DIR });
+
+  console.log('');
+  header('Next steps');
+  dim(`1. Edit prompts/projects/${projectName}/prompt-config.yaml`);
+  dim(`2. Add reference files to prompts/projects/${projectName}/references/`);
+  dim(`3. Run: node bin/prompt-compile.js ${projectName}`);
+  console.log('');
+}
+
 // ── Help ─────────────────────────────────────────────────────
 
 function printHelp() {
@@ -397,6 +468,7 @@ Commands:
   update      Re-copy from latest npm package version
   health      Verify install integrity
   uninstall   Remove Praxis-owned files from ~/.claude/
+  scaffold    Scaffold a new prompt project
 
 Flags:
   --help, -h      Show this help
@@ -407,7 +479,7 @@ Flags:
 // ── Main ─────────────────────────────────────────────────────
 
 const arg = process.argv[2] || 'install';
-const commands = { install, update, health, uninstall };
+const commands = { install, update, health, uninstall, scaffold };
 
 if (arg === '--help' || arg === '-h') { printHelp(); }
 else if (arg === '--version' || arg === '-v') { console.log(VERSION); }

package/bin/prompt-compile.js

@@ -8,11 +8,17 @@ const yaml = require('js-yaml');
 const {
   TARGETS,
   PROMPTS_DIR,
+  WORK_DIR,
+  PERSONAL_DIR,
   loadPraxisConfig,
   loadProfile,
   mergeProfiles,
   loadBlocks,
   applyOverrides,
+  loadClientConfig,
+  discoverAllDeals,
+  resolveProject,
+  mergeClientDealConfig,
 } = require('../lib/loader');
 
 const {
@@ -25,6 +31,29 @@ const {
 
 const PROJECTS_DIR = path.join(PROMPTS_DIR, 'projects');
 
+/** Discover all compilable projects — clients hierarchy + legacy flat projects. */
+function discoverAllProjects() {
+  const results = [];
+
+  // New hierarchy: clients/*/deals/*/
+  for (const entry of discoverAllDeals()) {
+    results.push({ name: entry.displayName, dir: entry.dealDir, client: entry.client, deal: entry.deal, clientDir: entry.clientDir });
+  }
+
+  // Legacy: projects/*/  (skip _template, skip projects that also exist in clients)
+  if (fs.existsSync(PROJECTS_DIR)) {
+    const dealNames = new Set(results.map((r) => r.deal));
+    const legacyDirs = fs.readdirSync(PROJECTS_DIR)
+      .filter((d) => d !== '_template' && fs.statSync(path.join(PROJECTS_DIR, d)).isDirectory())
+      .filter((d) => !dealNames.has(d));
+
+    for (const name of legacyDirs) {
+      results.push({ name, dir: path.join(PROJECTS_DIR, name), client: null, deal: name, clientDir: null });
+    }
+  }
+  return results;
+}
+
 const CHAR_BUDGETS = {
   'claude-code': Infinity,
   'claude-project': 2500,
@@ -58,10 +87,10 @@ 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: 'system-prompt.md', budget: Infinity, required: true, label: 'System Prompt (Source)' },
     { 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' },
+    { file: 'space-instructions-perplexity.md', budget: CHAR_BUDGETS['perplexity-space'], required: false, label: 'Perplexity Space' },
+    { file: 'project-instructions-claude-desktop.md', budget: CHAR_BUDGETS['claude-project'], required: false, label: 'Claude Desktop' },
   ];
 
   const results = [];
@@ -121,15 +150,35 @@ function validateStandalone(projectName, projectDir, projectConfig) {
 }
 
 /** Compile a project. Returns { mode, results[] } for summary table. */
-function compileProject(projectName, targets) {
-  const projectDir = path.join(PROJECTS_DIR, projectName);
-  const configPath = path.join(projectDir, 'prompt-config.yaml');
+function compileProject(projectName, targets, projectDirOverride, clientDirOverride) {
+  // Resolve project path — supports "client/deal", "deal", or direct dir override
+  let projectDir;
+  let clientDir = clientDirOverride || null;
+  if (projectDirOverride) {
+    projectDir = projectDirOverride;
+  } else {
+    const resolved = resolveProject(projectName);
+    if (!resolved.dealDir || !fs.existsSync(resolved.dealDir)) {
+      fail(`Project not found: ${projectName}\nRun /px-prompt <project-name> to create one.`);
+    }
+    projectDir = resolved.dealDir;
+    clientDir = resolved.clientDir;
+  }
 
+  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'));
+  let projectConfig = yaml.load(fs.readFileSync(configPath, 'utf8'));
+
+  // Merge client config if in hierarchy
+  if (clientDir) {
+    const clientConfig = loadClientConfig(clientDir);
+    if (clientConfig) {
+      projectConfig = mergeClientDealConfig(clientConfig, projectConfig);
+    }
+  }
 
   if (projectConfig.mode === 'standalone') {
     return validateStandalone(projectName, projectDir, projectConfig);
@@ -165,8 +214,8 @@ function compileProject(projectName, targets) {
 
   const outputNames = {
     'claude-code': 'CLAUDE.md',
-    'claude-project': 'project-instructions.md',
-    'perplexity-space': 'space-instructions.md',
+    'claude-project': 'project-instructions-claude-desktop.md',
+    'perplexity-space': 'space-instructions-perplexity.md',
   };
 
   const results = [];
@@ -242,41 +291,96 @@ function main() {
     console.log('  --diff             Show what changed before writing');
     console.log('  --strict           Exit with error on budget overruns or unresolved vars');
     console.log('  --sync             Compile all projects with diff, show summary table');
+    console.log('  --dashboard        Rich project index with budgets and staleness');
     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) {
+    const allProjects = discoverAllProjects();
+    if (allProjects.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');
+    console.log(`${'Project'.padEnd(28)} ${'Mode'.padEnd(12)} ${'System Prompt'.padEnd(15)} ${'Claude Desktop'.padEnd(15)} ${'Perplexity'.padEnd(15)} ${'CLAUDE.md'.padEnd(12)} Refs`);
+    console.log('-'.repeat(105));
+    for (const proj of allProjects) {
+      const cfgPath = path.join(proj.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);
+        const p = path.join(proj.dir, f);
         if (!fs.existsSync(p)) return '—';
         return `${fs.readFileSync(p, 'utf8').length} chars`;
       };
-      const refsDir = path.join(dir, 'references');
+      const refsDir = path.join(proj.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}`
+        `${proj.name.padEnd(28)} ${mode.padEnd(12)} ${fileStatus('system-prompt.md').padEnd(15)} ${fileStatus('project-instructions-claude-desktop.md').padEnd(15)} ${fileStatus('space-instructions-perplexity.md').padEnd(15)} ${fileStatus('CLAUDE.md').padEnd(12)} ${refCount}`
       );
     }
     process.exit(0);
   }
 
+  // --dashboard mode: rich project index with staleness and budgets
+  if (args.includes('--dashboard')) {
+    const allProjects = discoverAllProjects();
+    if (allProjects.length === 0) {
+      console.log('No projects found.');
+      process.exit(0);
+    }
+
+    const STALE_DAYS = 30;
+    const now = Date.now();
+
+    console.log('\n\x1b[1mPROMPT ENGINE DASHBOARD\x1b[0m');
+    console.log('\x1b[90m' + '━'.repeat(110) + '\x1b[0m');
+    console.log(
+      `${'Project'.padEnd(24)} ${'Mode'.padEnd(12)} ${'Perplexity'.padEnd(14)} ${'Claude Proj'.padEnd(14)} ${'CLAUDE.md'.padEnd(14)} ${'Refs'.padEnd(6)} ${'Updated'.padEnd(12)} Stale?`
+    );
+    console.log('\x1b[90m' + '─'.repeat(110) + '\x1b[0m');
+
+    for (const proj of allProjects) {
+      const cfgPath = path.join(proj.dir, 'prompt-config.yaml');
+      const cfg = fs.existsSync(cfgPath) ? yaml.load(fs.readFileSync(cfgPath, 'utf8')) : {};
+      const mode = cfg.mode || 'compiled';
+
+      const fileBudget = (f, budget) => {
+        const p = path.join(proj.dir, f);
+        if (!fs.existsSync(p)) return '\x1b[90m—\x1b[0m';
+        const chars = fs.readFileSync(p, 'utf8').length;
+        const icon = chars > budget ? '\x1b[33m⚠\x1b[0m' : '\x1b[32m✓\x1b[0m';
+        return `${chars} ${budget < Infinity ? icon : ''}`;
+      };
+
+      const refsDir = path.join(proj.dir, 'references');
+      const refCount = fs.existsSync(refsDir)
+        ? fs.readdirSync(refsDir).filter((f) => f.endsWith('.md')).length
+        : 0;
+
+      let latestMtime = 0;
+      const allFiles = fs.readdirSync(proj.dir).filter((f) => f.endsWith('.md') || f.endsWith('.yaml'));
+      for (const f of allFiles) {
+        const stat = fs.statSync(path.join(proj.dir, f));
+        if (stat.mtimeMs > latestMtime) latestMtime = stat.mtimeMs;
+      }
+      const updated = latestMtime > 0 ? new Date(latestMtime).toISOString().slice(0, 10) : '—';
+      const daysSince = latestMtime > 0 ? Math.floor((now - latestMtime) / 86400000) : 999;
+      const stale = daysSince > STALE_DAYS ? '\x1b[31mYes\x1b[0m' : '\x1b[32mNo\x1b[0m';
+
+      console.log(
+        `${proj.name.padEnd(24)} ${mode.padEnd(12)} ${fileBudget('space-instructions-perplexity.md', CHAR_BUDGETS['perplexity-space']).padEnd(23)} ${fileBudget('project-instructions-claude-desktop.md', CHAR_BUDGETS['claude-project']).padEnd(23)} ${fileBudget('CLAUDE.md', Infinity).padEnd(23)} ${String(refCount).padEnd(6)} ${updated.padEnd(12)} ${stale}`
+      );
+    }
+
+    console.log('\x1b[90m' + '━'.repeat(110) + '\x1b[0m');
+    console.log('\x1b[90mStaleness: >30 days since last file change. Budgets: ✓ under, ⚠ over.\x1b[0m\n');
+    process.exit(0);
+  }
+
   // Parse global flags
   PREVIEW_MODE = args.includes('--preview');
   DIFF_MODE = args.includes('--diff');
@@ -307,16 +411,15 @@ function main() {
   }
 
   if (args.includes('--all') || isSync) {
-    const projectDirs = fs.readdirSync(PROJECTS_DIR)
-      .filter((d) => d !== '_template' && fs.statSync(path.join(PROJECTS_DIR, d)).isDirectory());
+    const allProjects = discoverAllProjects();
 
-    if (projectDirs.length === 0) {
-      fail('No projects found in prompts/projects/');
+    if (allProjects.length === 0) {
+      fail('No projects found.');
     }
 
     const allResults = [];
-    for (const projectName of projectDirs) {
-      const result = compileProject(projectName, targets);
+    for (const proj of allProjects) {
+      const result = compileProject(proj.name, targets, proj.dir, proj.clientDir);
       if (result) allResults.push(result);
     }
 

package/bin/prompt-knowledge.js

@@ -0,0 +1,152 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Renders knowledge-file templates for a project.
+ *
+ * Reads `knowledge_packs` from the project's prompt-config.yaml.
+ * Each entry specifies a template and vars. Renders to projects/<name>/knowledge/.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const yaml = require('js-yaml');
+const { interpolate, findUnresolved } = require('../lib/assemblers');
+const { parseFrontmatter, loadPraxisConfig, resolveProject, loadClientConfig, mergeClientDealConfig } = require('../lib/loader');
+
+const PKG_DIR = path.resolve(__dirname, '..');
+const TEMPLATES_DIR = path.join(PKG_DIR, 'prompts', 'templates', 'knowledge');
+
+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\u2713\x1b[0m ${msg}`);
+}
+
+function main() {
+  const args = process.argv.slice(2);
+
+  if (args.length === 0 || args.includes('--help')) {
+    console.log('Usage: prompt-knowledge <project-name> [--preview] [--diff] [--list-templates]');
+    process.exit(0);
+  }
+
+  if (args.includes('--list-templates')) {
+    if (!fs.existsSync(TEMPLATES_DIR)) {
+      console.log('No templates found.');
+      process.exit(0);
+    }
+    const templates = fs.readdirSync(TEMPLATES_DIR).filter((f) => f.endsWith('.md'));
+    if (templates.length === 0) {
+      console.log('No templates found.');
+      process.exit(0);
+    }
+    console.log('\nAvailable knowledge templates:\n');
+    for (const t of templates) {
+      const content = fs.readFileSync(path.join(TEMPLATES_DIR, t), 'utf8');
+      const { meta } = parseFrontmatter(content);
+      console.log(`  ${(meta.id || t).padEnd(28)} ${meta.description || '(no description)'}`);
+      if (meta.vars) {
+        console.log(`    vars: ${meta.vars.join(', ')}`);
+      }
+    }
+    console.log('');
+    process.exit(0);
+  }
+
+  const preview = args.includes('--preview');
+  const diff = args.includes('--diff');
+  const projectName = args.find((a) => !a.startsWith('--'));
+
+  if (!projectName) fail('Specify a project name.');
+
+  const resolved = resolveProject(projectName);
+  if (!resolved.dealDir || !fs.existsSync(resolved.dealDir)) {
+    fail(`Project not found: ${projectName}`);
+  }
+  const projectDir = resolved.dealDir;
+  const configPath = path.join(projectDir, 'prompt-config.yaml');
+
+  if (!fs.existsSync(configPath)) {
+    fail(`Project config not found: ${configPath}`);
+  }
+
+  let projectConfig = yaml.load(fs.readFileSync(configPath, 'utf8'));
+
+  // Merge client config if in hierarchy
+  if (resolved.clientDir) {
+    const clientConfig = loadClientConfig(resolved.clientDir);
+    if (clientConfig) {
+      projectConfig = mergeClientDealConfig(clientConfig, projectConfig);
+    }
+  }
+
+  const praxisConfig = loadPraxisConfig();
+  const globalVars = {
+    ...praxisConfig,
+    ...(projectConfig.vars || {}),
+    project: projectConfig.project || projectConfig.deal || projectName,
+  };
+
+  const packs = projectConfig.knowledge_packs || [];
+  if (packs.length === 0) {
+    console.log(`No knowledge_packs defined in ${configPath}`);
+    process.exit(0);
+  }
+
+  const knowledgeDir = path.join(projectDir, 'knowledge');
+  if (!preview && !fs.existsSync(knowledgeDir)) {
+    fs.mkdirSync(knowledgeDir, { recursive: true });
+  }
+
+  console.log(`\nRendering knowledge packs for: ${projectName}\n`);
+
+  for (const pack of packs) {
+    const templatePath = path.join(TEMPLATES_DIR, `${pack.template}.md`);
+    if (!fs.existsSync(templatePath)) {
+      warn(`Template not found: ${pack.template} \u2014 skipping`);
+      continue;
+    }
+
+    const templateContent = fs.readFileSync(templatePath, 'utf8');
+    const { body } = parseFrontmatter(templateContent);
+
+    const vars = { ...globalVars, ...(pack.vars || {}) };
+    const output = interpolate(body, vars);
+
+    const unresolved = findUnresolved(output);
+    if (unresolved.length > 0) {
+      warn(`Unresolved in ${pack.output}: ${unresolved.join(', ')} \u2014 these become placeholders for manual fill`);
+    }
+
+    const outputPath = path.join(knowledgeDir, pack.output);
+
+    if (preview) {
+      console.log(`--- ${pack.output} (${output.length} chars, targets: ${(pack.targets || ['all']).join(', ')}) ---`);
+      console.log(output);
+      console.log('');
+    } else if (diff && fs.existsSync(outputPath)) {
+      const existing = fs.readFileSync(outputPath, 'utf8');
+      if (existing === output) {
+        ok(`${pack.output} \u2014 unchanged`);
+      } else {
+        fs.writeFileSync(outputPath, output, 'utf8');
+        ok(`${pack.output} \u2014 updated (${output.length} chars)`);
+      }
+    } else {
+      fs.writeFileSync(outputPath, output, 'utf8');
+      ok(`${pack.output} \u2014 ${output.length} chars \u2192 ${outputPath}`);
+    }
+  }
+
+  console.log('\nDone.');
+}
+
+main();

package/lib/assemblers.js

@@ -55,6 +55,13 @@ function assembleClaudeCode(blocks, projectConfig, vars) {
     for (const block of domainBlocks) lines.push(block.content, '');
   }
 
+  // Skills
+  const skillBlocks = blocks.filter((b) => b.category === 'skills');
+  if (skillBlocks.length > 0) {
+    lines.push('## Skills & Techniques');
+    for (const block of skillBlocks) lines.push(block.content, '');
+  }
+
   // Formats
   const formatBlocks = blocks.filter((b) => b.category === 'formats');
   if (formatBlocks.length > 0) {
@@ -117,24 +124,28 @@ function assembleClaudeProject(blocks, projectConfig, vars) {
   const behaviorBlocks = blocks.filter((b) => b.category === 'behaviors');
   if (behaviorBlocks.length > 0) {
     lines.push('## Behavioral Constraints');
-    for (const block of behaviorBlocks) lines.push('- ' + block.content);
-    lines.push('');
+    for (const block of behaviorBlocks) lines.push(block.content, '');
   }
 
   // Layer 3: Domain Expertise
   const domainBlocks = blocks.filter((b) => b.category === 'domains');
   if (domainBlocks.length > 0) {
     lines.push('## Domain Expertise');
-    for (const block of domainBlocks) lines.push('- ' + block.content);
-    lines.push('');
+    for (const block of domainBlocks) lines.push(block.content, '');
+  }
+
+  // Layer 3a: Skills & Techniques
+  const skillBlocks = blocks.filter((b) => b.category === 'skills');
+  if (skillBlocks.length > 0) {
+    lines.push('## Skills & Techniques');
+    for (const block of skillBlocks) lines.push(block.content, '');
   }
 
   // Layer 3b: Output Format
   const formatBlocks = blocks.filter((b) => b.category === 'formats');
   if (formatBlocks.length > 0) {
     lines.push('## Output Format');
-    for (const block of formatBlocks) lines.push('- ' + block.content);
-    lines.push('');
+    for (const block of formatBlocks) lines.push(block.content, '');
   }
 
   // Additional context
@@ -203,6 +214,14 @@ function assemblePerplexitySpace(blocks, projectConfig, vars) {
     lines.push('');
   }
 
+  // Capabilities (skills)
+  const skillBlocks = blocks.filter((b) => b.category === 'skills');
+  if (skillBlocks.length > 0) {
+    lines.push('## Capabilities');
+    for (const block of skillBlocks) lines.push(block.content);
+    lines.push('');
+  }
+
   // Research Domains
   const append = (projectConfig.overrides || {}).perplexity_space_append || {};
   if (append.research_domains) {