@plures/praxis 1.2.13 → 1.2.41

package/src/cli/commands/conversations.ts

@@ -0,0 +1,252 @@
+/**
+ * Praxis CLI - Conversations Commands
+ * 
+ * Commands for the praxis-conversations subsystem
+ */
+
+import { promises as fs } from 'node:fs';
+import {
+  loadConversation,
+  captureConversation,
+  redactConversation,
+  normalizeConversation,
+  classifyConversation,
+  generateCandidate,
+  applyGates,
+  candidatePassed,
+  emitToFS,
+  emitToGitHub,
+  type Conversation,
+  type Candidate,
+} from '../../conversations/index.js';
+
+interface CaptureOptions {
+  input?: string;
+  output?: string;
+}
+
+interface PushOptions {
+  input: string;
+  output?: string;
+  skipRedaction?: boolean;
+  skipNormalization?: boolean;
+}
+
+interface ClassifyOptions {
+  input: string;
+  output?: string;
+}
+
+interface EmitOptions {
+  input: string;
+  emitter: 'fs' | 'github';
+  outputDir?: string;
+  owner?: string;
+  repo?: string;
+  token?: string;
+  dryRun?: boolean;
+  commitIntent?: boolean;
+}
+
+/**
+ * Capture command: Capture a conversation from input
+ */
+export async function captureCommand(options: CaptureOptions): Promise<void> {
+  console.log('📝 Capturing conversation...');
+  
+  let conversation: Conversation;
+  
+  if (options.input) {
+    // Load from file
+    const content = await fs.readFile(options.input, 'utf-8');
+    conversation = loadConversation(content);
+    console.log(`✓ Loaded conversation from ${options.input}`);
+  } else {
+    // Create a sample conversation for demo
+    conversation = captureConversation({
+      turns: [
+        { role: 'user', content: 'Hello, I have a question about the feature' },
+        { role: 'assistant', content: 'Sure, I\'d be happy to help!' },
+      ],
+      metadata: {
+        source: 'cli',
+      },
+    });
+    console.log('✓ Created sample conversation');
+  }
+  
+  if (options.output) {
+    await fs.writeFile(
+      options.output,
+      JSON.stringify(conversation, null, 2),
+      'utf-8'
+    );
+    console.log(`✓ Saved to ${options.output}`);
+  } else {
+    console.log(JSON.stringify(conversation, null, 2));
+  }
+}
+
+/**
+ * Push command: Process conversation through pipeline (capture -> redact -> normalize)
+ */
+export async function pushCommand(options: PushOptions): Promise<void> {
+  console.log('🔄 Processing conversation through pipeline...');
+  
+  // Load conversation
+  const content = await fs.readFile(options.input, 'utf-8');
+  let conversation = loadConversation(content);
+  console.log(`✓ Loaded conversation ${conversation.id}`);
+  
+  // Redact
+  if (!options.skipRedaction) {
+    conversation = redactConversation(conversation);
+    console.log('✓ Redacted PII');
+  }
+  
+  // Normalize
+  if (!options.skipNormalization) {
+    conversation = normalizeConversation(conversation);
+    console.log('✓ Normalized content');
+  }
+  
+  // Save result
+  if (options.output) {
+    await fs.writeFile(
+      options.output,
+      JSON.stringify(conversation, null, 2),
+      'utf-8'
+    );
+    console.log(`✓ Saved to ${options.output}`);
+  } else {
+    console.log(JSON.stringify(conversation, null, 2));
+  }
+}
+
+/**
+ * Classify command: Classify a conversation and generate candidate
+ */
+export async function classifyCommand(options: ClassifyOptions): Promise<void> {
+  console.log('🏷️  Classifying conversation...');
+  
+  // Load conversation
+  const content = await fs.readFile(options.input, 'utf-8');
+  let conversation = loadConversation(content);
+  console.log(`✓ Loaded conversation ${conversation.id}`);
+  
+  // Ensure conversation is processed
+  if (!conversation.redacted) {
+    conversation = redactConversation(conversation);
+    console.log('✓ Applied redaction');
+  }
+  
+  if (!conversation.normalized) {
+    conversation = normalizeConversation(conversation);
+    console.log('✓ Applied normalization');
+  }
+  
+  // Classify
+  conversation = classifyConversation(conversation);
+  console.log(`✓ Classified as: ${conversation.classification?.category} (confidence: ${conversation.classification?.confidence?.toFixed(2)})`);
+  
+  // Generate candidate
+  const candidate = generateCandidate(conversation);
+  if (!candidate) {
+    console.error('✗ Failed to generate candidate');
+    process.exit(1);
+  }
+  
+  console.log(`✓ Generated candidate: ${candidate.title}`);
+  
+  // Apply gates
+  const gatedCandidate = applyGates(candidate);
+  console.log(`\n📋 Gate Results:`);
+  for (const gate of gatedCandidate.gateStatus?.gates || []) {
+    const icon = gate.passed ? '✓' : '✗';
+    console.log(`  ${icon} ${gate.name}: ${gate.message}`);
+  }
+  
+  const passed = candidatePassed(gatedCandidate);
+  console.log(`\n${passed ? '✓ All gates passed' : '✗ Some gates failed'}`);
+  
+  // Save result
+  if (options.output) {
+    await fs.writeFile(
+      options.output,
+      JSON.stringify(gatedCandidate, null, 2),
+      'utf-8'
+    );
+    console.log(`✓ Saved candidate to ${options.output}`);
+  } else {
+    console.log('\n' + JSON.stringify(gatedCandidate, null, 2));
+  }
+}
+
+/**
+ * Emit command: Emit a candidate to a destination
+ */
+export async function emitCommand(options: EmitOptions): Promise<void> {
+  console.log('📤 Emitting candidate...');
+  
+  // Load candidate
+  const content = await fs.readFile(options.input, 'utf-8');
+  const candidate = JSON.parse(content) as Candidate;
+  console.log(`✓ Loaded candidate ${candidate.id}`);
+  
+  // Check gates
+  if (!candidatePassed(candidate)) {
+    console.error('✗ Candidate did not pass gates, refusing to emit');
+    console.error(`  Reason: ${candidate.gateStatus?.reason}`);
+    process.exit(1);
+  }
+  
+  let result: Candidate;
+  
+  if (options.emitter === 'fs') {
+    const outputDir = options.outputDir || './output/candidates';
+    result = await emitToFS(candidate, {
+      outputDir,
+      dryRun: options.dryRun,
+    });
+    
+    if (result.emissionResult?.success) {
+      console.log(`✓ Emitted to filesystem: ${result.emissionResult.externalId}`);
+    } else {
+      console.error(`✗ Emission failed: ${result.emissionResult?.error}`);
+      process.exit(1);
+    }
+  } else if (options.emitter === 'github') {
+    if (!options.owner || !options.repo) {
+      console.error('✗ GitHub emitter requires --owner and --repo');
+      process.exit(1);
+    }
+    
+    // CRITICAL: Display commit_intent gate status
+    if (!options.commitIntent) {
+      console.error('');
+      console.error('⛔ GATE BLOCKED: commit_intent=false');
+      console.error('');
+      console.error('The GitHub emitter is HARD GATED by the --commit-intent flag.');
+      console.error('This prevents accidental issue creation.');
+      console.error('');
+      console.error('To emit to GitHub, add: --commit-intent');
+      console.error('');
+      process.exit(1);
+    }
+    
+    result = await emitToGitHub(candidate, {
+      owner: options.owner,
+      repo: options.repo,
+      token: options.token,
+      dryRun: options.dryRun,
+      commitIntent: options.commitIntent,
+    });
+    
+    if (result.emissionResult?.success) {
+      console.log(`✓ Emitted to GitHub: ${result.emissionResult.externalId}`);
+    } else {
+      console.error(`✗ Emission failed: ${result.emissionResult?.error}`);
+      process.exit(1);
+    }
+  }
+}

package/src/cli/index.ts

@@ -301,4 +301,77 @@ program
     }
   });
 
+// Conversations commands (praxis-conversations subsystem)
+const conversationsCmd = program
+  .command('conversations')
+  .description('Conversation ingestion subsystem (capture -> redact -> normalize -> classify -> emit)');
+
+conversationsCmd
+  .command('capture')
+  .description('Capture a conversation from input')
+  .option('-i, --input <file>', 'Input conversation file')
+  .option('-o, --output <file>', 'Output file for captured conversation')
+  .action(async (options) => {
+    try {
+      const { captureCommand } = await import('./commands/conversations.js');
+      await captureCommand(options);
+    } catch (error) {
+      console.error('Error capturing conversation:', error);
+      process.exit(1);
+    }
+  });
+
+conversationsCmd
+  .command('push')
+  .description('Process conversation through pipeline (redact -> normalize)')
+  .requiredOption('-i, --input <file>', 'Input conversation file')
+  .option('-o, --output <file>', 'Output file for processed conversation')
+  .option('--skip-redaction', 'Skip PII redaction', false)
+  .option('--skip-normalization', 'Skip normalization', false)
+  .action(async (options) => {
+    try {
+      const { pushCommand } = await import('./commands/conversations.js');
+      await pushCommand(options);
+    } catch (error) {
+      console.error('Error processing conversation:', error);
+      process.exit(1);
+    }
+  });
+
+conversationsCmd
+  .command('classify')
+  .description('Classify conversation and generate candidate')
+  .requiredOption('-i, --input <file>', 'Input conversation file')
+  .option('-o, --output <file>', 'Output file for candidate')
+  .action(async (options) => {
+    try {
+      const { classifyCommand } = await import('./commands/conversations.js');
+      await classifyCommand(options);
+    } catch (error) {
+      console.error('Error classifying conversation:', error);
+      process.exit(1);
+    }
+  });
+
+conversationsCmd
+  .command('emit')
+  .description('Emit candidate to destination (fs or github)')
+  .requiredOption('-i, --input <file>', 'Input candidate file')
+  .requiredOption('-e, --emitter <type>', 'Emitter type (fs, github)')
+  .option('--output-dir <dir>', 'Output directory (for fs emitter)', './output/candidates')
+  .option('--owner <owner>', 'GitHub repository owner (for github emitter)')
+  .option('--repo <repo>', 'GitHub repository name (for github emitter)')
+  .option('--token <token>', 'GitHub token (for github emitter)')
+  .option('--dry-run', 'Dry run mode (no actual emission)', false)
+  .option('--commit-intent', 'REQUIRED: Explicit commit intent for GitHub emission', false)
+  .action(async (options) => {
+    try {
+      const { emitCommand } = await import('./commands/conversations.js');
+      await emitCommand(options);
+    } catch (error) {
+      console.error('Error emitting candidate:', error);
+      process.exit(1);
+    }
+  });
+
 program.parse();

package/src/conversations/README.md

@@ -0,0 +1,230 @@
+# Praxis Conversations Subsystem
+
+The praxis-conversations subsystem provides a deterministic-first conversation ingestion pipeline for capturing, processing, and emitting conversation data.
+
+## Pipeline
+
+The subsystem follows a deterministic pipeline:
+
+```
+capture → redact → normalize → classify → candidates → gate → emit
+```
+
+### Pipeline Stages
+
+1. **Capture**: Capture conversations from various sources (CLI, API, files)
+2. **Redact**: Remove PII (email, phone, IP addresses) using deterministic patterns
+3. **Normalize**: Normalize whitespace, code blocks, and formatting
+4. **Classify**: Classify conversations using keyword-based rules (no LLM)
+5. **Candidates**: Generate emission candidates (GitHub issues, docs, etc.)
+6. **Gate**: Apply quality gates before emission
+7. **Emit**: Emit to destinations (filesystem, GitHub)
+
+## Schemas
+
+### Conversation Schema
+
+See `conversation.schema.json` for the full schema.
+
+```json
+{
+  "id": "uuid",
+  "timestamp": "ISO 8601",
+  "turns": [
+    {
+      "role": "user|assistant|system",
+      "content": "text",
+      "timestamp": "ISO 8601"
+    }
+  ],
+  "metadata": {
+    "source": "github-copilot|cli|web",
+    "userId": "string",
+    "sessionId": "string",
+    "tags": ["tag1", "tag2"]
+  },
+  "redacted": false,
+  "normalized": false,
+  "classified": false,
+  "classification": {
+    "category": "bug-report|feature-request|question|...",
+    "confidence": 0.85,
+    "tags": ["tag1", "tag2"]
+  }
+}
+```
+
+### Candidate Schema
+
+See `candidate.schema.json` for the full schema.
+
+```json
+{
+  "id": "uuid",
+  "conversationId": "uuid",
+  "type": "github-issue|github-pr|documentation|...",
+  "title": "Short title",
+  "body": "Full body content",
+  "metadata": {
+    "priority": "low|medium|high|critical",
+    "labels": ["bug", "priority:high"],
+    "assignees": ["username"]
+  },
+  "gateStatus": {
+    "passed": true,
+    "gates": [...]
+  },
+  "emitted": false
+}
+```
+
+## CLI Usage
+
+### Capture a Conversation
+
+```bash
+# Capture from file
+praxis conversations capture -i conversation.json -o captured.json
+
+# Create sample conversation
+praxis conversations capture -o sample.json
+```
+
+### Process Through Pipeline
+
+```bash
+# Redact and normalize
+praxis conversations push -i conversation.json -o processed.json
+
+# Skip redaction
+praxis conversations push -i conversation.json --skip-redaction
+```
+
+### Classify and Generate Candidate
+
+```bash
+# Classify conversation and generate candidate
+praxis conversations classify -i conversation.json -o candidate.json
+```
+
+### Emit to Destination
+
+```bash
+# Emit to filesystem
+praxis conversations emit -i candidate.json -e fs --output-dir ./output
+
+# Emit to GitHub (dry run)
+praxis conversations emit -i candidate.json -e github \
+  --owner myorg --repo myrepo --dry-run
+
+# Emit to GitHub (REQUIRES --commit-intent)
+praxis conversations emit -i candidate.json -e github \
+  --owner myorg --repo myrepo --token $GITHUB_TOKEN --commit-intent
+```
+
+## GitHub Emitter Gate
+
+**CRITICAL**: The GitHub emitter is **HARD GATED** by the `--commit-intent` flag.
+
+This prevents accidental issue creation. You **MUST** explicitly pass `--commit-intent` to emit to GitHub:
+
+```bash
+praxis conversations emit -i candidate.json -e github \
+  --owner myorg --repo myrepo --commit-intent
+```
+
+Without `--commit-intent`, the command will fail with:
+
+```
+⛔ GATE BLOCKED: commit_intent=false
+
+The GitHub emitter is HARD GATED by the --commit-intent flag.
+This prevents accidental issue creation.
+
+To emit to GitHub, add: --commit-intent
+```
+
+## Programmatic Usage
+
+```typescript
+import {
+  captureConversation,
+  redactConversation,
+  normalizeConversation,
+  classifyConversation,
+  generateCandidate,
+  applyGates,
+  candidatePassed,
+  emitToFS,
+  emitToGitHub,
+} from '@plures/praxis/conversations';
+
+// Capture
+const conversation = captureConversation({
+  turns: [
+    { role: 'user', content: 'I found a bug...' },
+    { role: 'assistant', content: 'Thanks for reporting!' },
+  ],
+  metadata: { source: 'cli' },
+});
+
+// Process
+let processed = redactConversation(conversation);
+processed = normalizeConversation(processed);
+processed = classifyConversation(processed);
+
+// Generate candidate
+const candidate = generateCandidate(processed);
+
+// Gate
+const gated = applyGates(candidate);
+if (candidatePassed(gated)) {
+  // Emit
+  const result = await emitToFS(gated, {
+    outputDir: './output/candidates',
+  });
+  
+  console.log('Emitted:', result.emissionResult?.externalId);
+}
+```
+
+## Classification Categories
+
+The classifier uses deterministic keyword matching to identify:
+
+- `bug-report`: bugs, errors, crashes
+- `feature-request`: features, enhancements
+- `question`: questions, help requests
+- `documentation`: docs, guides, examples
+- `performance`: performance, optimization
+
+## Quality Gates
+
+Before emission, candidates pass through these gates:
+
+1. **minimum-length**: Content must be >= 50 characters
+2. **valid-title**: Title must be 10-200 characters
+3. **not-duplicate**: Not a duplicate (stub, would check existing issues)
+4. **has-metadata**: Must have labels and priority
+
+## Testing
+
+Run tests:
+
+```bash
+npm test src/__tests__/conversations.test.ts
+```
+
+Test fixtures are in `test/fixtures/conversations/`.
+
+## Examples
+
+See `test/fixtures/conversations/` for example conversations:
+
+- `bug-report.json`: Bug report conversation
+- `feature-request.json`: Feature request conversation
+- `question.json`: Question conversation
+
+## License
+
+MIT

package/src/conversations/candidate.schema.json

@@ -0,0 +1,123 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://praxis.dev/schemas/candidate.json",
+  "title": "Candidate",
+  "description": "Schema for a conversation candidate for emission (GitHub issue, documentation, etc.)",
+  "type": "object",
+  "required": ["id", "conversationId", "type", "title", "body", "metadata"],
+  "properties": {
+    "id": {
+      "type": "string",
+      "description": "Unique identifier for the candidate"
+    },
+    "conversationId": {
+      "type": "string",
+      "description": "Reference to the source conversation ID"
+    },
+    "type": {
+      "type": "string",
+      "enum": ["github-issue", "github-pr", "documentation", "feature-request", "bug-report"],
+      "description": "Type of candidate to emit"
+    },
+    "title": {
+      "type": "string",
+      "description": "Title or subject for the candidate"
+    },
+    "body": {
+      "type": "string",
+      "description": "Main content body for the candidate"
+    },
+    "metadata": {
+      "type": "object",
+      "description": "Candidate metadata",
+      "properties": {
+        "priority": {
+          "type": "string",
+          "enum": ["low", "medium", "high", "critical"],
+          "description": "Priority level"
+        },
+        "labels": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Labels to apply (for GitHub issues/PRs)"
+        },
+        "assignees": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Assignees (for GitHub issues/PRs)"
+        },
+        "source": {
+          "type": "object",
+          "description": "Source information",
+          "properties": {
+            "conversationId": {
+              "type": "string"
+            },
+            "timestamp": {
+              "type": "string",
+              "format": "date-time"
+            }
+          }
+        }
+      }
+    },
+    "gateStatus": {
+      "type": "object",
+      "description": "Gating decision results",
+      "properties": {
+        "passed": {
+          "type": "boolean",
+          "description": "Whether the candidate passed gating"
+        },
+        "reason": {
+          "type": "string",
+          "description": "Reason for gating decision"
+        },
+        "gates": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "name": {
+                "type": "string"
+              },
+              "passed": {
+                "type": "boolean"
+              },
+              "message": {
+                "type": "string"
+              }
+            }
+          },
+          "description": "Individual gate results"
+        }
+      }
+    },
+    "emitted": {
+      "type": "boolean",
+      "description": "Whether the candidate has been emitted",
+      "default": false
+    },
+    "emissionResult": {
+      "type": "object",
+      "description": "Result of emission attempt",
+      "properties": {
+        "success": {
+          "type": "boolean"
+        },
+        "timestamp": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "externalId": {
+          "type": "string",
+          "description": "External ID (e.g., GitHub issue number)"
+        },
+        "error": {
+          "type": "string",
+          "description": "Error message if emission failed"
+        }
+      }
+    }
+  }
+}