@plures/praxis 1.2.0 → 1.2.10

package/src/cli/commands/validate.ts

@@ -0,0 +1,264 @@
+/**
+ * Praxis CLI - Validate Command
+ *
+ * Validates contract coverage for rules and constraints in the registry.
+ */
+
+import { PraxisRegistry } from '../../core/rules.js';
+import {
+  validateContracts,
+  formatValidationReport,
+  formatValidationReportJSON,
+  formatValidationReportSARIF,
+  writeLogicLedgerEntry,
+  type ArtifactIndex,
+  type Contract,
+} from '../../decision-ledger/index.js';
+import { ContractMissing } from '../../decision-ledger/index.js';
+import type { PraxisEvent, PraxisFact } from '../../core/protocol.js';
+import type { ContractGap } from '../../decision-ledger/types.js';
+
+interface ValidateOptions {
+  output?: 'console' | 'json' | 'sarif';
+  strict?: boolean;
+  registry?: string;
+  tests?: boolean;
+  spec?: boolean;
+  emitFacts?: boolean;
+  gapOutput?: string;
+  ledger?: string;
+  author?: string;
+}
+
+/**
+ * Validate command implementation.
+ *
+ * @param options Command options
+ */
+export async function validateCommand(options: ValidateOptions): Promise<void> {
+  const outputFormat = options.output || 'console';
+  const strict = options.strict || false;
+
+  // In a real implementation, this would load the registry from the project
+  // For now, we'll create a demo registry to show how it works
+  const registry = await loadRegistry(options.registry);
+  const artifactIndex = await buildArtifactIndex(registry, {
+    includeTests: options.tests ?? true,
+    includeSpec: options.spec ?? true,
+  });
+
+  // Validate contracts
+  const report = validateContracts(registry, {
+    strict,
+    requiredFields: ['behavior', 'examples', 'invariants'],
+    missingSeverity: strict ? 'error' : 'warning',
+    artifactIndex,
+  });
+
+  if (options.emitFacts) {
+    const facts = gapsToFacts(report.incomplete);
+    const events = gapsToEvents(report.incomplete);
+    await emitGapArtifacts({ facts, events, gapOutput: options.gapOutput });
+  }
+
+  if (options.ledger) {
+    await writeLedgerSnapshots(registry, {
+      rootDir: options.ledger,
+      author: options.author ?? 'system',
+      artifactIndex,
+    });
+  }
+
+  // Format and output the report
+  switch (outputFormat) {
+    case 'json':
+      console.log(formatValidationReportJSON(report));
+      break;
+    case 'sarif':
+      console.log(formatValidationReportSARIF(report));
+      break;
+    case 'console':
+    default:
+      console.log(formatValidationReport(report));
+      break;
+  }
+
+  // Exit with error code if in strict mode and there are issues
+  if (strict && (report.incomplete.length > 0 || report.missing.length > 0)) {
+    // Count errors from incomplete contracts
+    const incompleteErrors = report.incomplete.filter((gap: ContractGap) => gap.severity === 'error').length;
+    // In strict mode, missing contracts are also errors
+    const totalErrors = incompleteErrors + report.missing.length;
+    
+    if (totalErrors > 0) {
+      console.error(`\n❌ Validation failed: ${totalErrors} error(s) found`);
+      process.exit(1);
+    }
+  }
+
+  // Exit with success (only show messages in console mode)
+  if (outputFormat === 'console') {
+    if (report.incomplete.length === 0 && report.missing.length === 0) {
+      console.log('\n✅ All contracts validated successfully!');
+    } else {
+      const warningCount = report.incomplete.filter((gap: ContractGap) => gap.severity === 'warning').length;
+      if (warningCount > 0) {
+        console.log(`\n⚠️  ${warningCount} warning(s) found`);
+      }
+    }
+  }
+}
+
+/**
+ * Load the registry from the project.
+ *
+ * In a real implementation, this would:
+ * 1. Load the project's Praxis configuration
+ * 2. Import and instantiate the registry
+ * 3. Load all registered rules and constraints
+ *
+ * For now, it returns an empty registry for demonstration.
+ *
+ * @param registryPath Optional path to registry module
+ * @returns The loaded registry
+ */
+async function loadRegistry(registryPath?: string): Promise<PraxisRegistry> {
+  const registry = new PraxisRegistry();
+
+  // If a registry path is provided, try to load it
+  if (registryPath) {
+    try {
+      // Dynamic import would happen here
+      // const module = await import(registryPath);
+      // return module.registry || module.default;
+      const module = await import(resolveRegistryPath(registryPath));
+      const candidate = module.registry ?? module.default ?? module.createRegistry?.();
+      if (candidate && candidate instanceof PraxisRegistry) {
+        return candidate;
+      }
+      throw new Error('Registry module did not export a PraxisRegistry instance');
+    } catch (error) {
+      console.warn(`Warning: Could not load registry from ${registryPath}:`, error);
+    }
+  }
+
+  // Return empty registry for now
+  // In practice, this would scan the project for rules/constraints
+  return registry;
+}
+
+function resolveRegistryPath(registryPath: string): string {
+  if (registryPath.startsWith('.') || registryPath.startsWith('/')) {
+    return new URL(registryPath, `file://${process.cwd()}/`).href;
+  }
+
+  return registryPath;
+}
+
+async function buildArtifactIndex(
+  registry: PraxisRegistry,
+  options: { includeTests: boolean; includeSpec: boolean }
+): Promise<ArtifactIndex> {
+  const index: ArtifactIndex = {};
+  const ruleIds = new Set(registry.getRuleIds().concat(registry.getConstraintIds()));
+
+  if (options.includeTests) {
+    index.tests = new Set();
+    for (const id of ruleIds) {
+      if (await hasArtifactFile('tests', id)) {
+        index.tests.add(id);
+      }
+    }
+  }
+
+  if (options.includeSpec) {
+    index.spec = new Set();
+    for (const id of ruleIds) {
+      if (await hasArtifactFile('spec', id)) {
+        index.spec.add(id);
+      }
+    }
+  }
+
+  return index;
+}
+
+async function writeLedgerSnapshots(
+  registry: PraxisRegistry,
+  options: { rootDir: string; author: string; artifactIndex?: ArtifactIndex }
+): Promise<void> {
+  const { rootDir, author, artifactIndex } = options;
+  
+  // Process rules and constraints separately to avoid type issues
+  const processDescriptor = async (descriptor: { contract?: Contract; meta?: Record<string, unknown> } & { id: string }) => {
+    if (!descriptor.contract && !descriptor.meta?.contract) {
+      return;
+    }
+    const contract = descriptor.contract ?? (descriptor.meta?.contract as any);
+    await writeLogicLedgerEntry(contract, {
+      rootDir,
+      author,
+      testsPresent: artifactIndex?.tests?.has(contract.ruleId) ?? false,
+      specPresent: artifactIndex?.spec?.has(contract.ruleId) ?? false,
+    });
+  };
+
+  // Process all rules
+  for (const descriptor of registry.getAllRules()) {
+    await processDescriptor(descriptor);
+  }
+  
+  // Process all constraints
+  for (const descriptor of registry.getAllConstraints()) {
+    await processDescriptor(descriptor);
+  }
+}
+
+async function hasArtifactFile(type: 'tests' | 'spec', ruleId: string): Promise<boolean> {
+  const fs = await import('node:fs/promises');
+  const path = await import('node:path');
+  const candidateDirs = type === 'tests' ? ['src/__tests__', 'tests', 'test'] : ['spec', 'specs'];
+  const sanitized = ruleId.replace(/[^a-zA-Z0-9_-]/g, '_');
+
+  for (const dir of candidateDirs) {
+    const fullDir = path.resolve(process.cwd(), dir);
+    try {
+      const entries = await fs.readdir(fullDir);
+      if (entries.some((file) => file.includes(sanitized))) {
+        return true;
+      }
+    } catch {
+      // ignore missing directories
+    }
+  }
+
+  return false;
+}
+
+function gapsToFacts(gaps: ContractGap[]): PraxisFact[] {
+  return gaps.map((gap) =>
+    ContractMissing.create({
+      ruleId: gap.ruleId,
+      missing: gap.missing,
+      severity: gap.severity,
+      message: gap.message,
+    })
+  );
+}
+
+function gapsToEvents(_gaps: ContractGap[]): PraxisEvent[] {
+  return [];
+}
+
+async function emitGapArtifacts(payload: {
+  facts: PraxisFact[];
+  events: PraxisEvent[];
+  gapOutput?: string;
+}): Promise<void> {
+  if (payload.gapOutput) {
+    const fs = await import('node:fs/promises');
+    await fs.writeFile(payload.gapOutput, JSON.stringify(payload, null, 2));
+  } else {
+    console.log(JSON.stringify(payload, null, 2));
+  }
+}

package/src/cli/index.ts

@@ -254,4 +254,51 @@ program
     }
   });
 
+// Validate command (Decision Ledger)
+program
+  .command('validate')
+  .description('Validate contract coverage for rules and constraints')
+  .option('--output <format>', 'Output format (console, json, sarif)', 'console')
+  .option('--strict', 'Exit with error if contracts are missing', false)
+  .option('--registry <path>', 'Path to registry module')
+  .option('--tests', 'Check for tests for each rule/constraint', true)
+  .option('--spec', 'Check for specs for each rule/constraint', true)
+  .option('--emit-facts', 'Emit ContractMissing facts JSON payload', false)
+  .option('--gap-output <file>', 'Write contract-gap payload to file')
+  .option('--ledger <dir>', 'Write logic ledger snapshots to directory')
+  .option('--author <name>', 'Author name for ledger entries', 'system')
+  .action(async (options) => {
+    try {
+      const { validateCommand } = await import('./commands/validate.js');
+      await validateCommand(options);
+    } catch (error) {
+      console.error('Error validating contracts:', error);
+      process.exit(1);
+    }
+  });
+
+// Reverse command (Decision Ledger - Reverse Engineering)
+program
+  .command('reverse')
+  .description('Reverse engineer contracts from existing codebase')
+  .option('-d, --dir <path>', 'Root directory to scan', process.cwd())
+  .option('--ai <provider>', 'AI provider (none, github-copilot, openai, auto)', 'none')
+  .option('-o, --output <dir>', 'Output directory for contracts', './contracts')
+  .option('--ledger', 'Write to logic ledger', false)
+  .option('--dry-run', 'Dry run mode (no files written)', false)
+  .option('-i, --interactive', 'Interactive mode (prompt for each)', false)
+  .option('--confidence <threshold>', 'Confidence threshold (0.0-1.0)', '0.7')
+  .option('--limit <n>', 'Max number of rules to process')
+  .option('--author <name>', 'Author name for ledger entries', 'reverse-engineer')
+  .option('--format <format>', 'Output format (json, yaml)', 'json')
+  .action(async (options) => {
+    try {
+      const { reverseCommand } = await import('./commands/reverse.js');
+      await reverseCommand(options);
+    } catch (error) {
+      console.error('Error reverse engineering contracts:', error);
+      process.exit(1);
+    }
+  });
+
 program.parse();

package/src/core/pluresdb/adapter.ts

@@ -5,6 +5,8 @@
  * This module defines the core interface and an in-memory implementation.
  */
 
+import type { LocalFirstOptions, PluresDBLocalFirst } from '@plures/pluresdb/local-first';
+
 /**
  * Function to unsubscribe from a watch
  */
@@ -121,7 +123,10 @@ export function createInMemoryDB(): InMemoryPraxisDB {
  */
 export type PluresDBInstance = {
   get(key: string): Promise<any>;
-  put(key: string, value: any): Promise<void>;
+  put(key: string, value: any): Promise<any>;
+  delete?(key: string): Promise<void>;
+  list?(): Promise<any[]>;
+  close?(): Promise<void>;
 };
 
 /**
@@ -258,7 +263,7 @@ export class PluresDBPraxisAdapter implements PraxisDB {
  *
  * @example
  * ```typescript
- * import { PluresNode } from 'pluresdb';
+ * import { PluresNode } from '@plures/pluresdb';
  * import { createPluresDB } from '@plures/praxis';
  *
  * const pluresdb = new PluresNode({ autoStart: true });
@@ -280,3 +285,41 @@ export class PluresDBPraxisAdapter implements PraxisDB {
 export function createPluresDB(config: PluresDBAdapterConfig | PluresDBInstance): PluresDBPraxisAdapter {
   return new PluresDBPraxisAdapter(config);
 }
+
+/**
+ * Options for creating a local-first PluresDB adapter using the unified API
+ */
+export interface PraxisLocalFirstOptions extends LocalFirstOptions {
+  /** Optional polling interval override for watch semantics (ms). Defaults to 1000ms. */
+  pollInterval?: number;
+}
+
+/**
+ * Create a PraxisDB adapter backed by PluresDB's unified local-first API.
+ *
+ * This will auto-detect the best backend (WASM/Tauri/IPC/network) unless a mode is provided.
+ * Uses dynamic import to avoid bundling the local-first module in environments that don't need it.
+ *
+ * @example
+ * ```typescript
+ * const db = await createPraxisLocalFirst({ mode: 'auto' });
+ * await db.set('/_praxis/facts/user/1', { id: '1', name: 'Alice' });
+ * ```
+ */
+export async function createPraxisLocalFirst(
+  options: PraxisLocalFirstOptions = {}
+): Promise<PluresDBPraxisAdapter> {
+  const { pollInterval, ...localOptions } = options;
+
+  const mod = await import('@plures/pluresdb/local-first');
+  const LocalFirstCtor =
+    (mod as { PluresDBLocalFirst?: new (opts?: LocalFirstOptions) => PluresDBLocalFirst }).PluresDBLocalFirst ??
+    (mod as { default?: new (opts?: LocalFirstOptions) => PluresDBLocalFirst }).default;
+
+  if (!LocalFirstCtor) {
+    throw new Error('Failed to load PluresDBLocalFirst from @plures/pluresdb/local-first');
+  }
+
+  const db = new LocalFirstCtor(localOptions as LocalFirstOptions);
+  return new PluresDBPraxisAdapter({ db, pollInterval });
+}

package/src/core/rules.ts

@@ -7,6 +7,15 @@
  */
 
 import type { PraxisEvent, PraxisFact, PraxisState } from './protocol.js';
+import type { Contract, ContractGap, MissingArtifact, Severity } from '../decision-ledger/types.js';
+
+declare const process:
+  | {
+      env?: {
+        NODE_ENV?: string;
+      };
+    }
+  | undefined;
 
 /**
  * Unique identifier for a rule
@@ -52,6 +61,8 @@ export interface RuleDescriptor<TContext = unknown> {
   description: string;
   /** Implementation function */
   impl: RuleFn<TContext>;
+  /** Optional contract for rule behavior */
+  contract?: Contract;
   /** Optional metadata */
   meta?: Record<string, unknown>;
 }
@@ -66,6 +77,8 @@ export interface ConstraintDescriptor<TContext = unknown> {
   description: string;
   /** Implementation function */
   impl: ConstraintFn<TContext>;
+  /** Optional contract for constraint behavior */
+  contract?: Contract;
   /** Optional metadata */
   meta?: Record<string, unknown>;
 }
@@ -83,6 +96,27 @@ export interface PraxisModule<TContext = unknown> {
   meta?: Record<string, unknown>;
 }
 
+/**
+ * Compliance validation options for rule/constraint registration.
+ */
+export interface RegistryComplianceOptions {
+  /** Enable contract checks during registration (default: true in dev) */
+  enabled?: boolean;
+  /** Required contract fields to be present */
+  requiredFields?: Array<'behavior' | 'examples' | 'invariants'>;
+  /** Severity to use for missing contracts */
+  missingSeverity?: Severity;
+  /** Callback for contract gaps (e.g., to emit facts) */
+  onGap?: (gap: ContractGap) => void;
+}
+
+/**
+ * PraxisRegistry configuration options.
+ */
+export interface PraxisRegistryOptions {
+  compliance?: RegistryComplianceOptions;
+}
+
 /**
  * Registry for rules and constraints.
  * Maps IDs to their descriptors.
@@ -90,6 +124,18 @@ export interface PraxisModule<TContext = unknown> {
 export class PraxisRegistry<TContext = unknown> {
   private rules = new Map<RuleId, RuleDescriptor<TContext>>();
   private constraints = new Map<ConstraintId, ConstraintDescriptor<TContext>>();
+  private readonly compliance: RegistryComplianceOptions;
+  private contractGaps: ContractGap[] = [];
+
+  constructor(options: PraxisRegistryOptions = {}) {
+    const defaultEnabled = typeof process !== 'undefined' ? process.env?.NODE_ENV !== 'production' : false;
+    this.compliance = {
+      enabled: defaultEnabled,
+      requiredFields: ['behavior', 'examples', 'invariants'],
+      missingSeverity: 'warning',
+      ...options.compliance,
+    };
+  }
 
   /**
    * Register a rule
@@ -99,6 +145,7 @@ export class PraxisRegistry<TContext = unknown> {
       throw new Error(`Rule with id "${descriptor.id}" already registered`);
     }
     this.rules.set(descriptor.id, descriptor);
+    this.trackContractCompliance(descriptor.id, descriptor);
   }
 
   /**
@@ -109,6 +156,7 @@ export class PraxisRegistry<TContext = unknown> {
       throw new Error(`Constraint with id "${descriptor.id}" already registered`);
     }
     this.constraints.set(descriptor.id, descriptor);
+    this.trackContractCompliance(descriptor.id, descriptor);
   }
 
   /**
@@ -164,4 +212,89 @@ export class PraxisRegistry<TContext = unknown> {
   getAllConstraints(): ConstraintDescriptor<TContext>[] {
     return Array.from(this.constraints.values());
   }
+
+  /**
+  * Get collected contract gaps from registration-time validation.
+  */
+  getContractGaps(): ContractGap[] {
+    return [...this.contractGaps];
+  }
+
+  /**
+  * Clear collected contract gaps.
+  */
+  clearContractGaps(): void {
+    this.contractGaps = [];
+  }
+
+  private trackContractCompliance(
+    id: string,
+    descriptor: RuleDescriptor<TContext> | ConstraintDescriptor<TContext>
+  ): void {
+    if (!this.compliance.enabled) {
+      return;
+    }
+
+    const gaps = this.validateDescriptorContract(id, descriptor);
+    for (const gap of gaps) {
+      this.contractGaps.push(gap);
+      if (this.compliance.onGap) {
+        this.compliance.onGap(gap);
+      } else {
+        const label = gap.severity === 'error' ? 'ERROR' : gap.severity === 'warning' ? 'WARN' : 'INFO';
+        console.warn(`[Praxis][${label}] Contract gap for "${gap.ruleId}": missing ${gap.missing.join(', ')}`);
+      }
+    }
+  }
+
+  private validateDescriptorContract(
+    id: string,
+    descriptor: RuleDescriptor<TContext> | ConstraintDescriptor<TContext>
+  ): ContractGap[] {
+    const requiredFields = this.compliance.requiredFields ?? ['behavior', 'examples', 'invariants'];
+    const missingSeverity = this.compliance.missingSeverity ?? 'warning';
+    const contract =
+      descriptor.contract ??
+      (descriptor.meta?.contract && typeof descriptor.meta.contract === 'object'
+        ? (descriptor.meta.contract as Contract)
+        : undefined);
+
+    if (!contract) {
+      return [
+        {
+          ruleId: id,
+          missing: ['contract'],
+          severity: missingSeverity,
+          message: `Contract missing for "${id}"`,
+        },
+      ];
+    }
+
+    const missing: MissingArtifact[] = [];
+
+    if (requiredFields.includes('behavior') && (!contract.behavior || contract.behavior.trim() === '')) {
+      missing.push('behavior');
+    }
+
+    if (requiredFields.includes('examples') && (!contract.examples || contract.examples.length === 0)) {
+      missing.push('examples');
+    }
+
+    if (requiredFields.includes('invariants') && (!contract.invariants || contract.invariants.length === 0)) {
+      missing.push('invariants');
+    }
+
+    if (missing.length === 0) {
+      return [];
+    }
+
+    return [
+      {
+        ruleId: id,
+        missing,
+        severity: 'warning',
+        message: `Contract for "${id}" is incomplete: missing ${missing.join(', ')}`,
+      },
+    ];
+  }
 }