@plures/praxis 1.1.3 → 1.2.10

package/dist/node/reverse-W7THPV45.js

@@ -0,0 +1,193 @@
+import {
+  generateContractFromRule,
+  scanRepository,
+  writeLogicLedgerEntry
+} from "./chunk-WZ6B3LZ6.js";
+import {
+  PraxisRegistry
+} from "./chunk-R2PSBPKQ.js";
+import "./chunk-QGM4M3NI.js";
+
+// src/cli/commands/reverse.ts
+async function reverseCommand(options) {
+  const rootDir = options.dir || process.cwd();
+  const aiProvider = options.ai || "none";
+  const outputDir = options.output || "./contracts";
+  const dryRun = options.dryRun || false;
+  const interactive = options.interactive || false;
+  const confidenceThreshold = parseFloat(options.confidence || "0.7");
+  const limit = options.limit ? parseInt(options.limit, 10) : void 0;
+  const author = options.author || "reverse-engineer";
+  const format = options.format || "json";
+  console.log("\u{1F50D} Scanning repository for rules and constraints...");
+  console.log(`   Directory: ${rootDir}`);
+  console.log(`   AI Provider: ${aiProvider}`);
+  console.log("");
+  const registry = new PraxisRegistry();
+  const scanResult = await scanRepository({
+    rootDir,
+    scanTests: true,
+    scanSpecs: true,
+    maxDepth: 10
+  });
+  console.log(`\u2705 Scan complete in ${scanResult.duration}ms`);
+  console.log(`   Files scanned: ${scanResult.filesScanned}`);
+  console.log(`   Rules found: ${scanResult.rules.length}`);
+  console.log(`   Constraints found: ${scanResult.constraints.length}`);
+  console.log(`   Test files: ${scanResult.testFiles.size} mapped`);
+  console.log(`   Spec files: ${scanResult.specFiles.size} mapped`);
+  if (scanResult.warnings.length > 0) {
+    console.log(`   \u26A0\uFE0F  Warnings: ${scanResult.warnings.length}`);
+    scanResult.warnings.slice(0, 5).forEach((w) => console.log(`      - ${w}`));
+    if (scanResult.warnings.length > 5) {
+      console.log(`      ... and ${scanResult.warnings.length - 5} more`);
+    }
+  }
+  console.log("");
+  for (const rule of scanResult.rules) {
+    registry.registerRule(rule);
+  }
+  for (const constraint of scanResult.constraints) {
+    registry.registerConstraint(constraint);
+  }
+  const allDescriptors = [
+    ...scanResult.rules.map((r) => ({ ...r, type: "rule" })),
+    ...scanResult.constraints.map((c) => ({ ...c, type: "constraint" }))
+  ];
+  const toProcess = limit ? allDescriptors.slice(0, limit) : allDescriptors;
+  console.log(`\u{1F916} Generating contracts for ${toProcess.length} items...`);
+  console.log("");
+  const results = [];
+  let generated = 0;
+  let skipped = 0;
+  for (const descriptor of toProcess) {
+    console.log(`\u{1F4DD} Processing ${descriptor.type}: ${descriptor.id}`);
+    const testFiles = scanResult.testFiles.get(descriptor.id) || [];
+    const specFiles = scanResult.specFiles.get(descriptor.id) || [];
+    const sourceFile = descriptor.meta?.sourceFile;
+    if (interactive) {
+      const readline = await import("readline");
+      const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout
+      });
+      try {
+        const answer = await new Promise((resolve) => {
+          rl.question(`   Generate contract for ${descriptor.id}? (y/n) `, resolve);
+        });
+        if (answer.toLowerCase() !== "y") {
+          console.log("   \u23ED\uFE0F  Skipped");
+          console.log("");
+          skipped++;
+          continue;
+        }
+      } finally {
+        rl.close();
+      }
+    }
+    try {
+      const result = await generateContractFromRule(descriptor, {
+        aiProvider,
+        confidenceThreshold,
+        includeAssumptions: true,
+        generateExamples: true,
+        sourceFile,
+        testFiles,
+        specFiles
+      });
+      console.log(`   \u2705 Generated (${result.method}, confidence: ${result.confidence.toFixed(2)})`);
+      if (result.warnings.length > 0) {
+        console.log(`   \u26A0\uFE0F  Warnings:`);
+        result.warnings.forEach((warning) => console.log(`      - ${warning}`));
+      }
+      console.log(`   \u{1F4CB} Contract summary:`);
+      console.log(`      Behavior: ${result.contract.behavior}`);
+      console.log(`      Examples: ${result.contract.examples.length}`);
+      console.log(`      Invariants: ${result.contract.invariants.length}`);
+      if (result.contract.assumptions) {
+        console.log(`      Assumptions: ${result.contract.assumptions.length}`);
+      }
+      console.log("");
+      results.push({
+        id: descriptor.id,
+        type: descriptor.type,
+        success: true,
+        confidence: result.confidence,
+        method: result.method,
+        warnings: result.warnings
+      });
+      if (!dryRun) {
+        await writeContractToFile(result.contract, outputDir, format);
+        if (options.ledger) {
+          await writeLogicLedgerEntry(result.contract, {
+            rootDir,
+            author,
+            testsPresent: testFiles.length > 0,
+            specPresent: specFiles.length > 0
+          });
+        }
+      }
+      generated++;
+    } catch (error) {
+      console.log(`   \u274C Failed: ${error instanceof Error ? error.message : String(error)}`);
+      console.log("");
+      results.push({
+        id: descriptor.id,
+        type: descriptor.type,
+        success: false,
+        confidence: 0,
+        method: "none",
+        warnings: [error instanceof Error ? error.message : String(error)]
+      });
+    }
+  }
+  console.log("");
+  console.log("\u{1F4CA} Summary");
+  console.log("=".repeat(50));
+  console.log(`Total processed: ${toProcess.length}`);
+  console.log(`Generated: ${generated}`);
+  console.log(`Skipped: ${skipped}`);
+  console.log(`Failed: ${results.filter((r) => !r.success).length}`);
+  console.log("");
+  const successfulResults = results.filter((r) => r.success);
+  const avgConfidence = successfulResults.length > 0 ? successfulResults.reduce((sum, r) => sum + r.confidence, 0) / successfulResults.length : 0;
+  console.log(`Average confidence: ${avgConfidence > 0 ? avgConfidence.toFixed(2) : "N/A"}`);
+  const methodCounts = results.reduce((acc, r) => {
+    acc[r.method] = (acc[r.method] || 0) + 1;
+    return acc;
+  }, {});
+  console.log(`Methods used:`);
+  for (const [method, count] of Object.entries(methodCounts)) {
+    console.log(`  - ${method}: ${count}`);
+  }
+  console.log("");
+  if (dryRun) {
+    console.log("\u2139\uFE0F  Dry run mode - no files were written");
+  } else {
+    console.log(`\u2705 Contracts written to: ${outputDir}`);
+    if (options.ledger) {
+      console.log(`\u2705 Logic ledger updated: ${rootDir}/logic-ledger`);
+    }
+  }
+}
+async function writeContractToFile(contract, outputDir, format) {
+  const fs = await import("fs/promises");
+  const path = await import("path");
+  const crypto = await import("crypto");
+  await fs.mkdir(outputDir, { recursive: true });
+  const hash = crypto.createHash("md5").update(contract.ruleId).digest("hex").slice(0, 6);
+  const sanitized = contract.ruleId.replace(/[^a-zA-Z0-9_-]/g, "-");
+  const fileName = `${sanitized}-${hash}.${format === "yaml" ? "yaml" : "json"}`;
+  const filePath = path.join(outputDir, fileName);
+  let content;
+  if (format === "yaml") {
+    const yaml = await import("js-yaml");
+    content = yaml.dump(contract);
+  } else {
+    content = JSON.stringify(contract, null, 2);
+  }
+  await fs.writeFile(filePath, content);
+}
+export {
+  reverseCommand
+};

package/dist/node/{terminal-adapter-CWka-yL8.d.ts → terminal-adapter-B-UK_Vdz.d.ts}

@@ -1,4 +1,5 @@
 import { TerminalNodeProps } from './schema.js';
+import { LocalFirstOptions } from '@plures/pluresdb/local-first';
 
 /**
  * PraxisDB Adapter
@@ -6,6 +7,7 @@ import { TerminalNodeProps } from './schema.js';
  * Provides a minimal adapter layer for PluresDB integration.
  * This module defines the core interface and an in-memory implementation.
  */
+
 /**
  * Function to unsubscribe from a watch
  */
@@ -76,7 +78,10 @@ declare function createInMemoryDB(): InMemoryPraxisDB;
  */
 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>;
 };
 /**
  * Configuration options for PluresDBPraxisAdapter
@@ -118,7 +123,7 @@ declare 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 });
@@ -138,6 +143,26 @@ declare class PluresDBPraxisAdapter implements PraxisDB {
  * ```
  */
 declare function createPluresDB(config: PluresDBAdapterConfig | PluresDBInstance): PluresDBPraxisAdapter;
+/**
+ * Options for creating a local-first PluresDB adapter using the unified API
+ */
+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' });
+ * ```
+ */
+declare function createPraxisLocalFirst(options?: PraxisLocalFirstOptions): Promise<PluresDBPraxisAdapter>;
 
 /**
  * Terminal Node Runtime Adapter
@@ -295,4 +320,4 @@ declare function createMockExecutor(responses: Record<string, {
     error?: string;
 }>): CommandExecutor;
 
-export { type CommandExecutor as C, InMemoryPraxisDB as I, type PraxisDB as P, TerminalAdapter as T, type UnsubscribeFn as U, type TerminalExecutionResult as a, type TerminalNodeState as b, createTerminalAdapter as c, type TerminalAdapterOptions as d, createMockExecutor as e, type PluresDBInstance as f, type PluresDBAdapterConfig as g, createInMemoryDB as h, PluresDBPraxisAdapter as i, createPluresDB as j, runTerminalCommand as r };
+export { type CommandExecutor as C, InMemoryPraxisDB as I, type PraxisDB as P, TerminalAdapter as T, type UnsubscribeFn as U, type TerminalExecutionResult as a, type TerminalNodeState as b, createTerminalAdapter as c, type TerminalAdapterOptions as d, createMockExecutor as e, type PluresDBInstance as f, type PluresDBAdapterConfig as g, type PraxisLocalFirstOptions as h, createInMemoryDB as i, PluresDBPraxisAdapter as j, createPluresDB as k, createPraxisLocalFirst as l, runTerminalCommand as r };

package/dist/node/{terminal-adapter-CDzxoLKR.d.cts → terminal-adapter-BQSIF5bf.d.cts}

@@ -1,4 +1,5 @@
 import { TerminalNodeProps } from './schema.cjs';
+import { LocalFirstOptions } from '@plures/pluresdb/local-first';
 
 /**
  * PraxisDB Adapter
@@ -6,6 +7,7 @@ import { TerminalNodeProps } from './schema.cjs';
  * Provides a minimal adapter layer for PluresDB integration.
  * This module defines the core interface and an in-memory implementation.
  */
+
 /**
  * Function to unsubscribe from a watch
  */
@@ -76,7 +78,10 @@ declare function createInMemoryDB(): InMemoryPraxisDB;
  */
 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>;
 };
 /**
  * Configuration options for PluresDBPraxisAdapter
@@ -118,7 +123,7 @@ declare 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 });
@@ -138,6 +143,26 @@ declare class PluresDBPraxisAdapter implements PraxisDB {
  * ```
  */
 declare function createPluresDB(config: PluresDBAdapterConfig | PluresDBInstance): PluresDBPraxisAdapter;
+/**
+ * Options for creating a local-first PluresDB adapter using the unified API
+ */
+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' });
+ * ```
+ */
+declare function createPraxisLocalFirst(options?: PraxisLocalFirstOptions): Promise<PluresDBPraxisAdapter>;
 
 /**
  * Terminal Node Runtime Adapter
@@ -295,4 +320,4 @@ declare function createMockExecutor(responses: Record<string, {
     error?: string;
 }>): CommandExecutor;
 
-export { type CommandExecutor as C, InMemoryPraxisDB as I, type PraxisDB as P, TerminalAdapter as T, type UnsubscribeFn as U, type TerminalExecutionResult as a, type TerminalNodeState as b, createTerminalAdapter as c, type TerminalAdapterOptions as d, createMockExecutor as e, type PluresDBInstance as f, type PluresDBAdapterConfig as g, createInMemoryDB as h, PluresDBPraxisAdapter as i, createPluresDB as j, runTerminalCommand as r };
+export { type CommandExecutor as C, InMemoryPraxisDB as I, type PraxisDB as P, TerminalAdapter as T, type UnsubscribeFn as U, type TerminalExecutionResult as a, type TerminalNodeState as b, createTerminalAdapter as c, type TerminalAdapterOptions as d, createMockExecutor as e, type PluresDBInstance as f, type PluresDBAdapterConfig as g, type PraxisLocalFirstOptions as h, createInMemoryDB as i, PluresDBPraxisAdapter as j, createPluresDB as k, createPraxisLocalFirst as l, runTerminalCommand as r };

package/dist/node/validate-CNHUULQE.js

@@ -0,0 +1,180 @@
+import {
+  ContractMissing,
+  formatValidationReport,
+  formatValidationReportJSON,
+  formatValidationReportSARIF,
+  validateContracts
+} from "./chunk-5RH7UAQC.js";
+import {
+  writeLogicLedgerEntry
+} from "./chunk-WZ6B3LZ6.js";
+import {
+  PraxisRegistry
+} from "./chunk-R2PSBPKQ.js";
+import "./chunk-QGM4M3NI.js";
+
+// src/cli/commands/validate.ts
+async function validateCommand(options) {
+  const outputFormat = options.output || "console";
+  const strict = options.strict || false;
+  const registry = await loadRegistry(options.registry);
+  const artifactIndex = await buildArtifactIndex(registry, {
+    includeTests: options.tests ?? true,
+    includeSpec: options.spec ?? true
+  });
+  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
+    });
+  }
+  switch (outputFormat) {
+    case "json":
+      console.log(formatValidationReportJSON(report));
+      break;
+    case "sarif":
+      console.log(formatValidationReportSARIF(report));
+      break;
+    case "console":
+    default:
+      console.log(formatValidationReport(report));
+      break;
+  }
+  if (strict && (report.incomplete.length > 0 || report.missing.length > 0)) {
+    const incompleteErrors = report.incomplete.filter((gap) => gap.severity === "error").length;
+    const totalErrors = incompleteErrors + report.missing.length;
+    if (totalErrors > 0) {
+      console.error(`
+\u274C Validation failed: ${totalErrors} error(s) found`);
+      process.exit(1);
+    }
+  }
+  if (outputFormat === "console") {
+    if (report.incomplete.length === 0 && report.missing.length === 0) {
+      console.log("\n\u2705 All contracts validated successfully!");
+    } else {
+      const warningCount = report.incomplete.filter((gap) => gap.severity === "warning").length;
+      if (warningCount > 0) {
+        console.log(`
+\u26A0\uFE0F  ${warningCount} warning(s) found`);
+      }
+    }
+  }
+}
+async function loadRegistry(registryPath) {
+  const registry = new PraxisRegistry();
+  if (registryPath) {
+    try {
+      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 registry;
+}
+function resolveRegistryPath(registryPath) {
+  if (registryPath.startsWith(".") || registryPath.startsWith("/")) {
+    return new URL(registryPath, `file://${process.cwd()}/`).href;
+  }
+  return registryPath;
+}
+async function buildArtifactIndex(registry, options) {
+  const index = {};
+  const ruleIds = new Set(registry.getRuleIds().concat(registry.getConstraintIds()));
+  if (options.includeTests) {
+    index.tests = /* @__PURE__ */ new Set();
+    for (const id of ruleIds) {
+      if (await hasArtifactFile("tests", id)) {
+        index.tests.add(id);
+      }
+    }
+  }
+  if (options.includeSpec) {
+    index.spec = /* @__PURE__ */ new Set();
+    for (const id of ruleIds) {
+      if (await hasArtifactFile("spec", id)) {
+        index.spec.add(id);
+      }
+    }
+  }
+  return index;
+}
+async function writeLedgerSnapshots(registry, options) {
+  const { rootDir, author, artifactIndex } = options;
+  const processDescriptor = async (descriptor) => {
+    if (!descriptor.contract && !descriptor.meta?.contract) {
+      return;
+    }
+    const contract = descriptor.contract ?? descriptor.meta?.contract;
+    await writeLogicLedgerEntry(contract, {
+      rootDir,
+      author,
+      testsPresent: artifactIndex?.tests?.has(contract.ruleId) ?? false,
+      specPresent: artifactIndex?.spec?.has(contract.ruleId) ?? false
+    });
+  };
+  for (const descriptor of registry.getAllRules()) {
+    await processDescriptor(descriptor);
+  }
+  for (const descriptor of registry.getAllConstraints()) {
+    await processDescriptor(descriptor);
+  }
+}
+async function hasArtifactFile(type, ruleId) {
+  const fs = await import("fs/promises");
+  const path = await import("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 {
+    }
+  }
+  return false;
+}
+function gapsToFacts(gaps) {
+  return gaps.map(
+    (gap) => ContractMissing.create({
+      ruleId: gap.ruleId,
+      missing: gap.missing,
+      severity: gap.severity,
+      message: gap.message
+    })
+  );
+}
+function gapsToEvents(_gaps) {
+  return [];
+}
+async function emitGapArtifacts(payload) {
+  if (payload.gapOutput) {
+    const fs = await import("fs/promises");
+    await fs.writeFile(payload.gapOutput, JSON.stringify(payload, null, 2));
+  } else {
+    console.log(JSON.stringify(payload, null, 2));
+  }
+}
+export {
+  validateCommand
+};

package/docs/core/pluresdb-integration.md

@@ -50,28 +50,28 @@ npm install @plures/praxis
 
 ### Configuration
 
-Configure PluresDB in your application:
+You can choose network-only (previous default) or the new local-first unified API (auto-detects WASM/Tauri/IPC/network).
+
+**Network (unchanged):**
 
 ```typescript
 import { createPluresDB } from '@plures/praxis';
+import { PluresNode } from '@plures/pluresdb';
 
-const db = createPluresDB({
-  // Database name (stored in IndexedDB)
-  name: 'my-app-db',
+const db = createPluresDB(new PluresNode({ autoStart: true }));
+```
 
-  // Schema version (increment to migrate)
-  version: 1,
+**Local-first (auto-detect):**
+
+```typescript
+import { createPraxisLocalFirst } from '@plures/praxis';
 
-  // Collections to create
-  collections: ['users', 'posts', 'comments'],
+// Auto mode picks the best backend (WASM in browser, Tauri/IPC on desktop, network fallback)
+const db = await createPraxisLocalFirst({ mode: 'auto' });
 
-  // Sync configuration (optional)
-  sync: {
-    enabled: true,
-    endpoint: 'https://your-sync-server.com',
-    interval: 5000, // ms
-  },
-});
+// Optional: override
+// const db = await createPraxisLocalFirst({ mode: 'wasm', dbName: 'my-app' });
+// const db = await createPraxisLocalFirst({ mode: 'ipc', channelName: 'my-channel' });
 ```
 
 ### From Schema