@plures/praxis 1.1.3 → 1.2.10

package/docs/decision-ledger/LATEST.md

@@ -0,0 +1,166 @@
+# Decision Ledger Integration - LATEST Behavior Snapshot
+
+**Generated From**: BEHAVIOR_LEDGER.md Entry 1 (`decision-ledger-v1`)  
+**Generated At**: 2025-01-26  
+**Status**: Non-Authoritative (derived from ledger)
+
+---
+
+## Current Behavior Summary
+
+The Decision Ledger Integration extends Praxis with contract-based rule and constraint validation, enabling teams to document, test, and enforce behavioral contracts for their logic.
+
+### Core Capabilities
+
+1. **Contract Definition**
+   - Attach contracts to rules and constraints via the `meta.contract` field
+   - Define canonical behavior, examples, invariants, assumptions, and references
+   - Contracts are JSON-serializable and language-neutral
+
+2. **Build-time Validation**
+   - `praxis validate` CLI command scans registered rules and constraints
+   - Reports contract coverage and identifies gaps
+   - Outputs structured diagnostics (JSON, console, SARIF)
+
+3. **Runtime Validation**
+   - Optional strict mode for contract enforcement during rule registration
+   - Emits `ContractMissing` facts for rules without complete contracts
+   - Policy rules can enforce contract requirements
+
+4. **Contract Gap Management**
+   - Acknowledge known gaps with `ACKNOWLEDGE_CONTRACT_GAP` event
+   - Track technical debt and expiration dates
+   - Audit trail of contract coverage over time
+
+### Active Assumptions
+
+All assumptions from Entry 1 are active:
+- A1: Contracts stored in `meta` field
+- A2: All contract data is JSON-serializable
+- A3: CLI follows Commander.js pattern
+- A4: Tests use Vitest framework
+- A5: Contracts are optional by default
+
+### Quick Start Example
+
+```typescript
+import { defineRule, defineContract } from '@plures/praxis';
+
+// Define a contract
+const loginContract = defineContract({
+  ruleId: 'auth.login',
+  behavior: 'Process login events and create user session facts',
+  examples: [
+    {
+      given: 'User provides valid credentials',
+      when: 'LOGIN event is received',
+      then: 'UserSessionCreated fact is emitted'
+    }
+  ],
+  invariants: ['Session must have unique ID']
+});
+
+// Attach contract to rule
+const loginRule = defineRule({
+  id: 'auth.login',
+  description: 'Process login events',
+  impl: (state, events) => { /* ... */ },
+  meta: { contract: loginContract }
+});
+
+// Validate at build time
+// $ praxis validate
+```
+
+### API Reference
+
+#### Contract Types
+
+```typescript
+interface Contract {
+  ruleId: string;
+  behavior: string;
+  examples: Array<{
+    given: string;
+    when: string;
+    then: string;
+  }>;
+  invariants: string[];
+  assumptions?: Assumption[];
+  references?: Reference[];
+}
+
+interface Assumption {
+  id: string;
+  statement: string;
+  confidence: number; // 0.0 to 1.0
+  justification: string;
+  derivedFrom?: string;
+  impacts: Array<'spec' | 'tests' | 'code'>;
+  status: 'active' | 'revised' | 'invalidated';
+}
+
+interface Reference {
+  type: string;
+  url?: string;
+  description?: string;
+}
+```
+
+#### Validation API
+
+```typescript
+// CLI
+praxis validate [options]
+  --output <format>    Output format: json, console, sarif (default: console)
+  --strict             Exit with error if contracts are missing
+  --config <file>      Path to validation config file
+
+// Programmatic
+import { validateContracts } from '@plures/praxis/decision-ledger';
+
+const report = validateContracts(registry, options);
+// report.complete: Contract[]
+// report.incomplete: ContractGap[]
+// report.missing: string[] (rule IDs)
+```
+
+#### Facts and Events
+
+```typescript
+// ContractMissing fact
+const ContractMissing = defineFact<'ContractMissing', {
+  ruleId: string;
+  missing: Array<'behavior' | 'examples' | 'invariants' | 'tests' | 'spec'>;
+  severity: 'warning' | 'error';
+}>('ContractMissing');
+
+// ACKNOWLEDGE_CONTRACT_GAP event
+const AcknowledgeContractGap = defineEvent<'ACKNOWLEDGE_CONTRACT_GAP', {
+  ruleId: string;
+  missing: string[];
+  justification: string;
+  expiresAt?: string;
+}>('ACKNOWLEDGE_CONTRACT_GAP');
+```
+
+### Configuration
+
+```typescript
+// praxis.config.ts
+export default {
+  decisionLedger: {
+    strict: false,               // Require contracts for all rules
+    validateOnRegister: true,    // Validate at runtime
+    outputFormat: 'console',     // 'json' | 'console' | 'sarif'
+    requiredFields: [            // Required contract fields
+      'behavior',
+      'examples'
+    ]
+  }
+};
+```
+
+---
+
+**Note**: This is a non-authoritative snapshot derived from the behavior ledger. The source of truth is BEHAVIOR_LEDGER.md.

package/docs/guides/cicd-pipeline.md

@@ -0,0 +1,142 @@
+# CI/CD Pipeline
+
+This document describes the automated continuous integration and deployment pipeline for the Praxis framework.
+
+## Overview
+
+The Praxis CI/CD pipeline is fully automated, ensuring that code merged into the `main` branch flows automatically through version bumping, tagging, release creation, and publishing to all package repositories in parallel.
+
+## Pipeline Flow
+
+```
+PR Merged to main
+    ↓
+Auto Version Bump (based on semver labels)
+    ↓
+Create Git Tag (v*.*.*)
+    ↓
+Run Tests & Build
+    ↓
+Create GitHub Release
+    ↓
+Publish to Repositories (Parallel)
+    ├─→ NPM
+    ├─→ JSR (JavaScript Registry)
+    └─→ NuGet
+```
+
+## Workflow Details
+
+### 1. Auto Version Bump (`auto-version-bump.yml`)
+
+**Trigger**: When a PR is merged to `main`
+
+**Process**:
+- Determines version bump level based on PR labels:
+  - `semver:major` → Major version bump (e.g., 1.0.0 → 2.0.0)
+  - `semver:minor` → Minor version bump (e.g., 1.0.0 → 1.1.0)
+  - `semver:patch` → Patch version bump (e.g., 1.0.0 → 1.0.1) - **default**
+- Updates `package.json` version
+- Creates and pushes a git tag (e.g., `v1.2.3`)
+
+**Requirements**: Add one of the semver labels to your PR to control the version bump.
+
+### 2. Release Creation (`release.yml`)
+
+**Trigger**: When a tag matching `v*.*.*` is pushed (automatically triggered by auto-version-bump)
+
+**Process**:
+- Checks out code at the tagged version
+- Runs full test suite
+- Builds the project
+- Creates a GitHub Release with changelog
+- Automatically triggers the publish workflow
+
+### 3. Publishing (`publish.yml`)
+
+**Trigger**: Called automatically by `release.yml` after release creation
+
+**Process**: Three parallel publishing jobs run simultaneously:
+
+#### NPM Publishing
+- Builds the TypeScript/Node.js package
+- Publishes to npm registry as `@plures/praxis`
+- Requires `NPM_TOKEN` secret
+
+#### JSR Publishing  
+- Publishes to JavaScript Registry (JSR) using Deno
+- Publishes as `@plures/praxis`
+- Uses OIDC authentication
+- Note: Uses `--allow-dirty` flag to allow publishing from clean checkout state
+
+#### NuGet Publishing
+- Extracts version from the most recent git tag
+- Updates version in `.csproj` file before building
+- Builds the C# package
+- Runs C# tests
+- Publishes to NuGet.org as `Praxis`
+- Requires `NUGET_API_KEY` secret
+
+**Note**: When the publish workflow is called from the release workflow, it extracts version information from the git tags instead of relying on GitHub context, ensuring consistent versioning across all published packages.
+
+## Additional Workflows
+
+### CI (`ci.yml`)
+
+**Trigger**: On push to `main` or pull request
+
+**Purpose**: Validates code quality before merging
+- Runs tests on multiple Node.js versions (18.x, 20.x)
+- Runs C# tests on .NET 8
+- Performs Deno compatibility checks
+
+### C# Build Check (`publish-nuget.yml`)
+
+**Trigger**: On push to `main` or pull request
+
+**Purpose**: Validates C# code builds and tests pass
+- Ensures C# codebase is always in a buildable state
+- Runs independently of publishing workflow
+
+## Secrets Required
+
+The following secrets must be configured in the GitHub repository:
+
+- `NPM_TOKEN`: NPM authentication token for publishing packages
+- `NUGET_API_KEY`: NuGet API key for publishing packages
+
+## Manual Triggers
+
+The main pipeline workflows support `workflow_dispatch`, allowing manual triggering when needed:
+
+- **Release Workflow**: Manually create a release and publish for the current state
+- **Publish Workflow**: Re-publish to all repositories without creating a new release
+- **C# Build Check**: Manually validate C# code builds and tests (separate from publishing)
+
+## Best Practices
+
+1. **Always label your PRs**: Use semver labels (`semver:major`, `semver:minor`, or `semver:patch`) to control version bumping
+2. **Review before merging**: Once merged to `main`, the entire pipeline runs automatically
+3. **Monitor releases**: Check the Actions tab to ensure all publishing jobs complete successfully
+4. **Breaking changes**: Use `semver:major` for breaking changes
+5. **New features**: Use `semver:minor` for new features
+6. **Bug fixes**: Use `semver:patch` for bug fixes and patches
+
+## Troubleshooting
+
+### Publishing failures
+
+If any publishing job fails:
+1. Check the Actions tab for detailed error logs
+2. Verify all required secrets are configured
+3. The workflow can be manually re-triggered using `workflow_dispatch`
+
+### Version conflicts
+
+If version bumping fails:
+1. Ensure no manual version changes conflict with automated bumping
+2. Check that the main branch is up to date
+
+### Parallel publishing
+
+All three repositories (NPM, JSR, NuGet) publish in parallel. If one fails, the others will continue. Check individual job logs for failures.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plures/praxis",
-  "version": "1.1.3",
+  "version": "1.2.10",
   "description": "The Full Plures Application Framework - declarative schemas, logic engine, component generation, and local-first data",
   "type": "module",
   "main": "./dist/node/index.js",
@@ -117,7 +117,7 @@
   "dependencies": {
     "commander": "^14.0.2",
     "js-yaml": "^4.1.1",
-    "pluresdb": "^1.0.1"
+    "@plures/pluresdb": "^1.6.10"
   },
   "peerDependencies": {
     "svelte": "^5.46.0"

package/src/__tests__/cli-validate.test.ts

@@ -0,0 +1,197 @@
+/**
+ * CLI Validate Command - Integration Tests
+ * 
+ * Tests for the praxis validate command with decision ledger features.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { promises as fs } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { exec } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const execAsync = promisify(exec);
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+// Go up from src/__tests__ to project root
+const projectRoot = path.resolve(__dirname, '..', '..');
+const cliPath = path.join(projectRoot, 'dist/node/cli/index.js');
+const sampleRegistryPath = path.join(projectRoot, 'examples/sample-registry.js');
+
+describe('CLI Validate Command', () => {
+  let tempDir: string;
+
+  beforeEach(async () => {
+    tempDir = path.join(tmpdir(), `praxis-test-${Date.now()}`);
+    await fs.mkdir(tempDir, { recursive: true });
+  });
+
+  afterEach(async () => {
+    try {
+      await fs.rm(tempDir, { recursive: true, force: true });
+    } catch (error) {
+      // Ignore cleanup errors
+    }
+  });
+
+  it('should validate registry and output to console', async () => {
+    const { stdout, stderr } = await execAsync(
+      `node ${cliPath} validate --registry ${sampleRegistryPath}`
+    );
+
+    expect(stdout).toContain('Contract Validation Report');
+    expect(stdout).toContain('Total: 5');
+    expect(stdout).toContain('auth.login');
+    expect(stderr).toContain('[Praxis][WARN]');
+  });
+
+  it('should output validation report as JSON', async () => {
+    const { stdout } = await execAsync(
+      `node ${cliPath} validate --registry ${sampleRegistryPath} --output json 2>/dev/null`
+    );
+
+    const report = JSON.parse(stdout);
+    
+    expect(report).toHaveProperty('complete');
+    expect(report).toHaveProperty('incomplete');
+    expect(report).toHaveProperty('missing');
+    expect(report).toHaveProperty('total');
+    expect(report.total).toBe(5);
+  });
+
+  it('should output validation report as SARIF', async () => {
+    const { stdout } = await execAsync(
+      `node ${cliPath} validate --registry ${sampleRegistryPath} --output sarif 2>/dev/null`
+    );
+
+    const sarif = JSON.parse(stdout);
+    
+    expect(sarif).toHaveProperty('version', '2.1.0');
+    expect(sarif).toHaveProperty('runs');
+    expect(sarif.runs).toHaveLength(1);
+    expect(sarif.runs[0].tool.driver.name).toBe('Praxis Decision Ledger');
+  });
+
+  it('should create logic ledger snapshots with --ledger option', async () => {
+    const ledgerDir = path.join(tempDir, 'ledger');
+    
+    await execAsync(
+      `node ${cliPath} validate --registry ${sampleRegistryPath} --ledger ${ledgerDir} --author "test-user" 2>&1`
+    );
+
+    // Check that ledger directory was created
+    const ledgerPath = path.join(ledgerDir, 'logic-ledger');
+    const exists = await fs.access(ledgerPath).then(() => true).catch(() => false);
+    expect(exists).toBe(true);
+
+    // Check that index.json was created
+    const indexPath = path.join(ledgerPath, 'index.json');
+    const indexContent = await fs.readFile(indexPath, 'utf-8');
+    const index = JSON.parse(indexContent);
+    expect(index).toHaveProperty('byRuleId');
+    expect(index.byRuleId).toHaveProperty('auth.login');
+
+    // Check that a versioned snapshot was created
+    // The path in byRuleId is relative to ledgerDir, not ledgerPath
+    const ruleDirRelative = index.byRuleId['auth.login'];
+    const ruleDir = path.join(ledgerDir, ruleDirRelative);
+    const latestPath = path.join(ruleDir, 'LATEST.json');
+    const latestContent = await fs.readFile(latestPath, 'utf-8');
+    const latest = JSON.parse(latestContent);
+    expect(latest).toHaveProperty('ruleId', 'auth.login');
+    expect(latest).toHaveProperty('version', 1);
+    expect(latest).toHaveProperty('canonicalBehavior');
+    expect(latest).toHaveProperty('assumptions');
+    expect(latest).toHaveProperty('artifacts');
+    expect(latest).toHaveProperty('drift');
+  });
+
+  it('should emit contract gaps as facts with --emit-facts option', async () => {
+    const gapFile = path.join(tempDir, 'gaps.json');
+    
+    await execAsync(
+      `node ${cliPath} validate --registry ${sampleRegistryPath} --emit-facts --gap-output ${gapFile}`
+    );
+
+    // Check that gap file was created
+    const gapContent = await fs.readFile(gapFile, 'utf-8');
+    const gaps = JSON.parse(gapContent);
+    
+    expect(gaps).toHaveProperty('facts');
+    expect(gaps).toHaveProperty('events');
+    expect(Array.isArray(gaps.facts)).toBe(true);
+    expect(gaps.facts.length).toBeGreaterThan(0);
+    
+    // Check that facts have correct structure
+    const firstFact = gaps.facts[0];
+    expect(firstFact).toHaveProperty('tag', 'ContractMissing');
+    expect(firstFact).toHaveProperty('payload');
+    expect(firstFact.payload).toHaveProperty('ruleId');
+    expect(firstFact.payload).toHaveProperty('missing');
+    expect(firstFact.payload).toHaveProperty('severity');
+  });
+
+  it('should exit with error code in strict mode if contracts missing', async () => {
+    try {
+      await execAsync(
+        `node ${cliPath} validate --registry ${sampleRegistryPath} --strict 2>&1`
+      );
+      // Should not reach here - strict mode should exit with error
+      throw new Error('Expected command to fail in strict mode');
+    } catch (error: any) {
+      // Expect non-zero exit code
+      expect(error.code).toBe(1);
+      // Check that stderr contains error message
+      const combinedOutput = error.stdout || error.stderr || '';
+      expect(combinedOutput).toContain('Validation failed');
+    }
+  });
+
+  it('should handle missing registry gracefully', async () => {
+    const { stdout } = await execAsync(
+      `node ${cliPath} validate --registry ./non-existent-registry.js`
+    );
+
+    expect(stdout).toContain('Contract Validation Report');
+    expect(stdout).toContain('Total: 0');
+    expect(stdout).toContain('All contracts validated successfully');
+  });
+
+  it('should track drift when updating contracts', async () => {
+    const ledgerDir = path.join(tempDir, 'ledger');
+    
+    // First validation
+    await execAsync(
+      `node ${cliPath} validate --registry ${sampleRegistryPath} --ledger ${ledgerDir} --author "test-user" 2>&1`
+    );
+
+    // Second validation (simulates contract update)
+    await execAsync(
+      `node ${cliPath} validate --registry ${sampleRegistryPath} --ledger ${ledgerDir} --author "test-user" 2>&1`
+    );
+
+    // Check that version was incremented
+    const indexPath = path.join(ledgerDir, 'logic-ledger', 'index.json');
+    const indexContent = await fs.readFile(indexPath, 'utf-8');
+    const index = JSON.parse(indexContent);
+    
+    const ruleDirRelative = index.byRuleId['auth.login'];
+    const ruleDir = path.join(ledgerDir, ruleDirRelative);
+    const latestPath = path.join(ruleDir, 'LATEST.json');
+    const latestContent = await fs.readFile(latestPath, 'utf-8');
+    const latest = JSON.parse(latestContent);
+    
+    // Second run should have version 2
+    expect(latest.version).toBe(2);
+    
+    // Check that v0001.json and v0002.json exist
+    const v1Path = path.join(ruleDir, 'v0001.json');
+    const v2Path = path.join(ruleDir, 'v0002.json');
+    const v1Exists = await fs.access(v1Path).then(() => true).catch(() => false);
+    const v2Exists = await fs.access(v2Path).then(() => true).catch(() => false);
+    expect(v1Exists).toBe(true);
+    expect(v2Exists).toBe(true);
+  });
+});