@plures/praxis 1.2.12 → 1.2.41

package/docs/examples/DOGFOODING_WORKFLOW_EXAMPLE.md

@@ -0,0 +1,295 @@
+# Example: Dogfooding Workflow in Action
+
+This example demonstrates a complete dogfooding workflow when adding a new feature to Praxis.
+
+## Scenario: Adding a New Rule with Full Dogfooding
+
+Let's walk through adding a new rule that validates user permissions, while actively dogfooding all relevant Plures tools.
+
+### Step 1: Start with Decision Ledger (Contract-First)
+
+Before writing code, define the contract:
+
+```typescript
+// src/rules/permissions.ts
+import { defineContract, defineRule, PraxisRegistry } from '@plures/praxis';
+
+// Define the contract first (Dogfooding: Decision Ledger)
+const permissionCheckContract = defineContract({
+  behavior: "Validates user permissions against required roles before granting access",
+  
+  examples: [
+    {
+      given: "User has role 'admin'",
+      when: "User requests admin action",
+      then: "Access granted fact is emitted",
+    },
+    {
+      given: "User has role 'viewer'",
+      when: "User requests admin action",
+      then: "Access denied fact is emitted with reason",
+    },
+    {
+      given: "User has no roles",
+      when: "User requests any protected action",
+      then: "Access denied fact is emitted",
+    },
+  ],
+  
+  invariants: [
+    "Access decisions are deterministic based on roles",
+    "Denied access always includes a reason",
+    "Role checks are case-insensitive",
+  ],
+  
+  assumptions: [
+    {
+      statement: "User roles are validated before reaching this rule",
+      confidence: "high",
+    },
+    {
+      statement: "Role names follow kebab-case convention",
+      confidence: "medium",
+    },
+  ],
+  
+  references: [
+    "docs/security/RBAC.md",
+    "Issue #123: Permission system design",
+  ],
+});
+
+// Implement the rule with contract attached
+const permissionCheckRule = defineRule({
+  id: 'auth.permission-check',
+  description: 'Check user permissions against required roles',
+  meta: {
+    contract: permissionCheckContract,
+  },
+  impl: (state, events) => {
+    // Implementation here...
+  },
+});
+```
+
+**Friction Found?** If the contract API is confusing or lacks examples, file a dogfooding issue immediately.
+
+### Step 2: Visualize with CodeCanvas
+
+Before implementing, visualize the schema:
+
+```typescript
+// scripts/visualize-auth-schema.ts
+import { schemaToCanvas } from '@plures/praxis';
+import { writeFileSync } from 'fs';
+
+const authSchema = {
+  entities: {
+    User: {
+      fields: {
+        id: { type: 'string' },
+        roles: { type: 'array', items: { type: 'string' } },
+      },
+    },
+    Permission: {
+      fields: {
+        action: { type: 'string' },
+        requiredRoles: { type: 'array', items: { type: 'string' } },
+      },
+    },
+  },
+};
+
+// Dogfooding: CodeCanvas
+const canvas = schemaToCanvas(authSchema);
+writeFileSync('./docs/auth-schema.json', JSON.stringify(canvas, null, 2));
+
+console.log('✅ Canvas exported to docs/auth-schema.json');
+// TODO: Convert to visual diagram format
+```
+
+Run it:
+```bash
+npx tsx scripts/visualize-auth-schema.ts
+```
+
+**Friction Found?** If `schemaToCanvas` doesn't handle your schema correctly, file a dogfooding issue with the schema structure.
+
+### Step 3: Generate Tests from Contract
+
+Write tests that mirror the contract examples:
+
+```typescript
+// test/rules/permissions.test.ts
+import { describe, it, expect } from 'vitest';
+import { permissionCheckRule } from '../../src/rules/permissions';
+import { createPraxisEngine, PraxisRegistry } from '@plures/praxis';
+
+describe('auth.permission-check', () => {
+  // Test Example 1 from contract
+  it('should grant access when user has required role', () => {
+    const registry = new PraxisRegistry();
+    registry.registerRule(permissionCheckRule);
+    
+    const engine = createPraxisEngine({
+      initialContext: { user: { roles: ['admin'] } },
+      registry,
+    });
+    
+    const events = [
+      { type: 'REQUEST_ADMIN_ACTION', payload: { action: 'delete-user' } },
+    ];
+    
+    const result = engine.step(events);
+    expect(result.facts.some(f => f.type === 'ACCESS_GRANTED')).toBe(true);
+  });
+  
+  // Test Example 2 from contract
+  it('should deny access when user lacks required role', () => {
+    const registry = new PraxisRegistry();
+    registry.registerRule(permissionCheckRule);
+    
+    const engine = createPraxisEngine({
+      initialContext: { user: { roles: ['viewer'] } },
+      registry,
+    });
+    
+    const events = [
+      { type: 'REQUEST_ADMIN_ACTION', payload: { action: 'delete-user' } },
+    ];
+    
+    const result = engine.step(events);
+    const deniedFact = result.facts.find(f => f.type === 'ACCESS_DENIED');
+    expect(deniedFact).toBeDefined();
+    expect(deniedFact?.payload.reason).toBeDefined();
+  });
+  
+  // Test Invariant: Denied access always includes reason
+  it('invariant: denied access always includes reason', () => {
+    // Test implementation...
+  });
+});
+```
+
+**Friction Found?** If testing the contract examples is cumbersome, file a dogfooding issue suggesting auto-generation.
+
+### Step 4: Generate Documentation with State-Docs
+
+Generate documentation from your module:
+
+```typescript
+// scripts/generate-auth-docs.ts
+import { createStateDocsGenerator } from '@plures/praxis';
+import { permissionCheckRule } from '../src/rules/permissions';
+import { PraxisRegistry } from '@plures/praxis';
+
+const registry = new PraxisRegistry();
+registry.registerRule(permissionCheckRule);
+
+// Dogfooding: State-Docs
+const docsGenerator = createStateDocsGenerator({
+  projectTitle: 'Praxis Auth Module',
+  target: './docs/generated/auth',
+});
+
+const docs = docsGenerator.generateFromModule({
+  name: 'auth',
+  rules: [permissionCheckRule],
+});
+
+console.log('✅ Documentation generated at docs/generated/auth');
+```
+
+Run it:
+```bash
+npx tsx scripts/generate-auth-docs.ts
+```
+
+**Friction Found?** If State-Docs doesn't extract contract information properly, file a dogfooding issue.
+
+### Step 5: Run Validation (Before Commit)
+
+```bash
+# Dogfooding: Praxis CLI
+npm run scan:rules
+npm run validate:contracts
+npm test
+npm run typecheck
+```
+
+**Friction Found?** If validation output is unclear or doesn't show file paths, file a dogfooding issue.
+
+### Step 6: Use PluresDB for Test Fixtures
+
+Instead of manual test data, use PluresDB:
+
+```typescript
+// test/fixtures/auth-fixtures.ts
+import { createInMemoryDB, createPluresDBAdapter } from '@plures/praxis';
+
+// Dogfooding: PluresDB
+export async function createAuthTestFixtures() {
+  const db = createInMemoryDB();
+  const adapter = createPluresDBAdapter({ db });
+  
+  // Pre-populate test data
+  await db.insert('users', {
+    id: 'user-1',
+    roles: ['admin', 'moderator'],
+  });
+  
+  await db.insert('users', {
+    id: 'user-2',
+    roles: ['viewer'],
+  });
+  
+  return { db, adapter };
+}
+```
+
+**Friction Found?** If PluresDB setup is tedious for tests, file a dogfooding issue.
+
+### Step 7: File Friction Reports
+
+Throughout this process, you might have encountered friction. File issues:
+
+1. **Issue #1**: "State-Docs doesn't extract contract examples automatically"
+   - Tool: State-Docs
+   - Type: Missing feature
+   - Impact: Medium
+   
+2. **Issue #2**: "CodeCanvas export format isn't compatible with Mermaid"
+   - Tool: CodeCanvas
+   - Type: Missing feature
+   - Impact: Low
+   
+3. **Issue #3**: "Praxis CLI validate doesn't show file paths for contract gaps"
+   - Tool: Praxis CLI
+   - Type: Confusing error message
+   - Impact: High
+
+## Summary: Tools Used
+
+In this workflow, we dogfooded:
+
+- ✅ **Decision Ledger**: Contract-first development
+- ✅ **CodeCanvas**: Schema visualization
+- ✅ **State-Docs**: Documentation generation
+- ✅ **Praxis CLI**: Validation and scaffolding
+- ✅ **PluresDB**: Test fixture management
+
+**Friction reports filed**: 3  
+**Developer experience improved**: 🚀
+
+## Next Steps
+
+After completing the feature:
+
+1. Review the friction reports filed
+2. Prioritize high-impact issues
+3. Update the [Plures Tools Inventory](../PLURES_TOOLS_INVENTORY.md) with learnings
+4. Share insights in the weekly dogfooding review
+
+---
+
+This example demonstrates the complete dogfooding loop: **Use → Observe → Report → Improve**.

package/docs/examples/README.md

@@ -0,0 +1,41 @@
+# Dogfooding Examples
+
+This directory contains practical examples of dogfooding Plures tools in real-world development scenarios.
+
+## Available Examples
+
+### [Dogfooding Workflow Example](./DOGFOODING_WORKFLOW_EXAMPLE.md)
+
+A comprehensive walkthrough demonstrating how to dogfood all Plures tools when adding a new feature to Praxis. This example shows:
+
+- Using Decision Ledger for contract-first development
+- Visualizing schemas with CodeCanvas
+- Generating documentation with State-Docs
+- Running Praxis CLI validation
+- Using PluresDB for test fixtures
+- Filing friction reports during development
+
+**Use this when:** You want to see a complete end-to-end example of dogfooding in action.
+
+---
+
+## Contributing New Examples
+
+Have a great dogfooding workflow or pattern? Add it here!
+
+1. Create a new `.md` file in this directory
+2. Follow the structure of existing examples
+3. Include:
+   - Clear scenario description
+   - Step-by-step instructions
+   - Code examples
+   - Friction points to watch for
+   - Summary of tools used
+4. Update this README with a link and description
+
+---
+
+See also:
+- [Dogfooding Quick Start](../DOGFOODING_QUICK_START.md)
+- [Dogfooding Checklist](../DOGFOODING_CHECKLIST.md)
+- [Plures Tools Inventory](../PLURES_TOOLS_INVENTORY.md)

package/docs/workflows/pr-overlap-guard.md

@@ -0,0 +1,50 @@
+# PR Overlap Guard
+
+## Overview
+
+The Praxis PR Overlap Guard is an automated workflow that helps prevent duplicate work by detecting when a new pull request may overlap with existing open pull requests.
+
+## How It Works
+
+The workflow runs automatically when a PR is opened, synchronized, or reopened. It:
+
+1. **Title Similarity Check**: Uses character trigram analysis to detect similar PR titles
+   - Normalizes titles (lowercase, removes special characters)
+   - Computes Jaccard coefficient of character trigrams
+   - Flags titles with >60% similarity
+
+2. **Code Overlap Check**: Analyzes diff signatures to detect similar changes
+   - Compares changed file paths
+   - Analyzes added/removed line counts
+   - Flags code with >50% overlap
+
+3. **Automated Alerts**: Posts a comment on the PR if potential overlaps are detected
+   - Lists similar PRs with links
+   - Shows similarity percentages
+   - Allows manual verification
+
+## Thresholds
+
+- **Title Similarity**: 60% or higher triggers an alert
+- **Patch Overlap**: 50% or higher triggers an alert
+- PRs meeting either threshold will generate an alert
+
+## Response to Alerts
+
+If you receive an overlap alert:
+
+1. Review the linked PRs to understand the overlap
+2. If your PR is intentionally similar (e.g., alternative approach), add a comment explaining the difference
+3. If it's a genuine duplicate, consider coordinating with the other PR author
+4. The alert is informational - you can proceed if you believe your PR is distinct
+
+## Technical Details
+
+- **Algorithm**: Custom trigram-based string similarity + file/line change analysis
+- **Performance**: Only computes expensive patch comparisons when titles are >30% similar
+- **Dependencies**: Uses GitHub CLI (`gh`) for fetching PR data
+
+## Files
+
+- Workflow: `.github/workflows/praxis-pr-overlap-guard.yml`
+- Documentation: `docs/workflows/pr-overlap-guard.md` (this file)

package/package.json

@@ -1,8 +1,13 @@
 {
   "name": "@plures/praxis",
-  "version": "1.2.12",
+  "version": "1.2.41",
   "description": "The Full Plures Application Framework - declarative schemas, logic engine, component generation, and local-first data",
   "type": "module",
+  "packageManager": "pnpm@9.15.1",
+  "workspaces": [
+    "packages/*",
+    "apps/*"
+  ],
   "main": "./dist/node/index.js",
   "types": "./dist/node/index.d.ts",
   "bin": {
@@ -120,7 +125,7 @@
   "dependencies": {
     "commander": "^14.0.2",
     "js-yaml": "^4.1.1",
-    "@plures/pluresdb": "^1.6.10"
+    "@plures/pluresdb": "^2.9.7"
   },
   "peerDependencies": {
     "svelte": "^5.46.0"