ripp-cli 1.0.0 → 1.2.1

package/CHANGELOG.md

@@ -0,0 +1,63 @@
+# Changelog
+
+All notable changes to the RIPP CLI will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.2.1] (2025-12-24)
+
+### Bug Fixes
+
+* **cli:** bundle schema files in npm package to fix validation when installed globally ([ed94409](https://github.com/Dylan-Natter/ripp-protocol/commit/ed94409))
+  - Schema files are now included in the npm package under `schema/` directory
+  - Updated schema loading paths to use bundled schemas instead of parent directory
+  - Fixes post-publish smoke test failures from version 1.2.0
+* **cli:** fix checklist generation and parsing bugs in `ripp confirm` command
+  - Fixed extraction of content fields (purpose, ux_flow, data_contracts, etc.) from candidates
+  - Use 'purpose' or 'full-packet' as section name instead of 'unknown'
+  - Add 'full-packet' to valid section types in checklist parser
+  - Fixes empty YAML blocks in generated checklists
+  - Fixes 'Unknown section type' error when building from checklist
+
+## [1.2.0](https://github.com/Dylan-Natter/ripp-protocol/compare/ripp-cli-v1.1.0...ripp-cli-v1.2.0) (2025-12-23)
+
+
+### Features
+
+* **cli:** enhance CLI description to include tooling capabilities ([8f97965](https://github.com/Dylan-Natter/ripp-protocol/commit/8f97965379bbb24287b8d69bb9d4e5af16bca1df))
+
+## [1.1.0](https://github.com/Dylan-Natter/ripp-protocol/compare/ripp-cli-v1.0.1...ripp-cli-v1.1.0) (2025-12-23)
+
+
+### Features
+
+* **cli:** add metrics, doctor, and enhanced workflow commands ([b5c413d](https://github.com/Dylan-Natter/ripp-protocol/commit/b5c413d335088350527e6e9aa8cd6fa1f0debf9f))
+* **vscode:** add metrics command and enhanced workflow integration ([24a3cd0](https://github.com/Dylan-Natter/ripp-protocol/commit/24a3cd02f3657958321cc8f04ca55f487853205c))
+
+
+### Documentation
+
+* upgrade reference implementation to Level 2 ([a4b18e3](https://github.com/Dylan-Natter/ripp-protocol/commit/a4b18e320d95fbb2754d4eb07dafc8da00eef673))
+
+## [1.0.1] - 2025-12-22
+
+### Changed
+
+- Version bump to enable npm publishing of updates
+
+### Fixed
+
+- Synchronized package-lock.json Node.js engine requirement (>=20.0.0) with package.json
+
+## [1.0.0] - Initial Release
+
+### Features
+
+- RIPP packet validation against JSON schema
+- Support for YAML and JSON input formats
+- Multi-file validation with glob patterns
+- Linting with severity levels (error, warning, info)
+- Strict mode for enhanced validation
+- Evidence package generation for handoffs
+- Portable binary distributions for macOS (ARM64 and x64)

package/README.md

@@ -274,6 +274,63 @@ npm link
 ripp validate ../../examples/
 ```
 
+## Publishing
+
+### Prerequisites
+
+To publish `ripp-cli` to npm, you need:
+
+1. **npm Account**: A verified npm account with appropriate permissions
+2. **NPM_TOKEN Secret**: Configured in GitHub repository secrets
+
+### Setting Up NPM_TOKEN
+
+The publishing workflow requires an npm **Granular Access Token** with specific permissions:
+
+1. Log in to [npmjs.com](https://www.npmjs.com)
+2. Go to **Access Tokens** → **Generate New Token** → **Granular Access Token**
+3. Configure the token:
+   - **Permissions**: Select "Read and write" for packages
+   - **Packages and scopes**: Select "All packages" or specific packages
+   - **Organizations**: (if applicable) Select relevant organizations
+   - **Expiration**: Set appropriate expiration date
+   - **Bypass 2FA**: ✅ **MUST be enabled** for CI/CD automation
+4. Copy the generated token
+5. Add it to GitHub repository secrets:
+   - Go to repository **Settings** → **Secrets and variables** → **Actions**
+   - Click **New repository secret**
+   - Name: `NPM_TOKEN`
+   - Value: (paste your token)
+
+**Important**: The token MUST have "Bypass 2FA requirement" enabled. Standard automation tokens may fail with E403 errors if 2FA is enabled on your npm account.
+
+### Publishing Process
+
+The package is published via the GitHub Actions workflow:
+
+1. Go to **Actions** → **Publish NPM Package**
+2. Click **Run workflow**
+3. Configure options:
+   - **dry_run**: `true` (test) or `false` (publish)
+   - **tag**: `latest`, `next`, or `beta`
+   - **package_path**: (default: `tools/ripp-cli`)
+4. Click **Run workflow**
+
+**Workflow Features**:
+
+- ✅ Validates package before publishing
+- ✅ Checks version isn't already published
+- ✅ Verifies npm authentication
+- ✅ Runs tests and linting
+- ✅ Dry-run mode for safe testing
+- ✅ Detailed job summaries
+
+**Version Management**:
+
+- Bump version in `package.json` before publishing
+- Follow [Semantic Versioning](https://semver.org/)
+- Workflow will reject if version already exists
+
 ## Dependencies
 
 - **ajv**: JSON Schema validator

package/index.js

@@ -17,6 +17,14 @@ const { discoverIntent } = require('./lib/discovery');
 const { confirmIntent } = require('./lib/confirmation');
 const { buildCanonicalArtifacts } = require('./lib/build');
 const { migrateDirectoryStructure } = require('./lib/migrate');
+const {
+  gatherMetrics,
+  formatMetricsText,
+  loadMetricsHistory,
+  saveMetricsHistory,
+  formatMetricsHistory
+} = require('./lib/metrics');
+const { runHealthChecks, formatHealthCheckText } = require('./lib/doctor');
 
 // ANSI color codes
 const colors = {
@@ -38,7 +46,7 @@ function log(color, symbol, message) {
 }
 
 function loadSchema() {
-  const schemaPath = path.join(__dirname, '../../schema/ripp-1.0.schema.json');
+  const schemaPath = path.join(__dirname, 'schema/ripp-1.0.schema.json');
   try {
     return JSON.parse(fs.readFileSync(schemaPath, 'utf8'));
   } catch (error) {
@@ -277,6 +285,8 @@ ${colors.blue}vNext - Intent Discovery Mode:${colors.reset}
   ripp discover                     Infer candidate intent (requires AI enabled)
   ripp confirm                      Confirm candidate intent (interactive)
   ripp build                        Build canonical RIPP artifacts from confirmed intent
+  ripp metrics                      Display workflow analytics and health metrics
+  ripp doctor                       Run health checks and diagnostics
 
   ripp --help                       Show this help message
   ripp --version                    Show version
@@ -300,9 +310,15 @@ ${colors.green}Confirm Options:${colors.reset}
   --user <id>                       User identifier for confirmation
 
 ${colors.green}Build Options:${colors.reset}
+  --from-checklist                  Build from intent.checklist.md (after manual review)
   --packet-id <id>                  Packet ID for generated RIPP (default: discovered-intent)
   --title <title>                   Title for generated RIPP packet
   --output-name <file>              Output file name (default: handoff.ripp.yaml)
+  --user <id>                       User identifier for confirmation tracking
+
+${colors.green}Metrics Options:${colors.reset}
+  --report                          Write metrics to .ripp/metrics.json
+  --history                         Show metrics trends from previous runs
 
 ${colors.green}Validate Options:${colors.reset}
   --min-level <1|2|3>               Enforce minimum RIPP level
@@ -317,6 +333,7 @@ ${colors.green}Package Options:${colors.reset}
   --in <file>                       Input RIPP packet file (required)
   --out <file>                      Output file path (required)
   --format <json|yaml|md>           Output format (auto-detected from extension)
+  --single                          Generate consolidated single-file markdown
   --package-version <version>       Version string for the package (e.g., 1.0.0)
   --force                           Overwrite existing output file without versioning
   --skip-validation                 Skip validation entirely
@@ -339,6 +356,7 @@ ${colors.green}Examples:${colors.reset}
   ripp lint ripp/intent/
   ripp lint ripp/intent/ --strict
   ripp package --in feature.ripp.yaml --out handoff.md
+  ripp package --in feature.ripp.yaml --out handoff.md --single
   ripp package --in feature.ripp.yaml --out handoff.md --package-version 1.0.0
   ripp package --in feature.ripp.yaml --out handoff.md --force
   ripp package --in feature.ripp.yaml --out handoff.md --warn-on-invalid
@@ -351,7 +369,10 @@ ${colors.blue}Intent Discovery Examples:${colors.reset}
   ripp evidence build
   RIPP_AI_ENABLED=true ripp discover --target-level 2
   ripp confirm --interactive
-  ripp build --packet-id my-feature --title "My Feature"
+  ripp confirm --checklist
+  ripp build
+  ripp build --from-checklist
+  ripp build --from-checklist --packet-id my-feature --title "My Feature"
 
 ${colors.gray}Note: Legacy paths (features/, handoffs/, packages/) are supported for backward compatibility.${colors.reset}
 
@@ -430,7 +451,7 @@ function getGitInfo() {
       commit,
       branch
     };
-  } catch (error) {
+  } catch {
     // Not in a git repo or git not available
     return null;
   }
@@ -565,6 +586,10 @@ async function main() {
     await handleConfirmCommand(args);
   } else if (command === 'build') {
     await handleBuildCommand(args);
+  } else if (command === 'metrics') {
+    await handleMetricsCommand(args);
+  } else if (command === 'doctor') {
+    handleDoctorCommand(args);
   } else {
     console.error(`${colors.red}Error: Unknown command '${command}'${colors.reset}`);
     console.error("Run 'ripp --help' for usage information.");
@@ -860,7 +885,8 @@ async function handlePackageCommand(args) {
     version: null,
     force: args.includes('--force'),
     skipValidation: args.includes('--skip-validation'),
-    warnOnInvalid: args.includes('--warn-on-invalid')
+    warnOnInvalid: args.includes('--warn-on-invalid'),
+    single: args.includes('--single')
   };
 
   const inIndex = args.indexOf('--in');
@@ -1011,7 +1037,7 @@ async function handlePackageCommand(args) {
     } else if (options.format === 'yaml') {
       output = formatAsYaml(packaged);
     } else if (options.format === 'md') {
-      output = formatAsMarkdown(packaged);
+      output = formatAsMarkdown(packaged, { single: options.single });
     }
 
     // Write to output file
@@ -1272,7 +1298,7 @@ async function handleConfirmCommand(args) {
       console.log('  1. Review and edit the checklist');
       console.log('  2. Mark accepted candidates with [x]');
       console.log('  3. Save the file');
-      console.log('  4. Run "ripp build" to compile confirmed intent');
+      console.log('  4. Run "ripp build --from-checklist" to compile confirmed intent');
       console.log('');
     } else {
       log(colors.green, '✓', 'Intent confirmation complete');
@@ -1302,7 +1328,8 @@ async function handleBuildCommand(args) {
   const options = {
     packetId: null,
     title: null,
-    outputName: null
+    outputName: null,
+    fromChecklist: args.includes('--from-checklist')
   };
 
   const packetIdIndex = args.indexOf('--packet-id');
@@ -1320,11 +1347,32 @@ async function handleBuildCommand(args) {
     options.outputName = args[outputNameIndex + 1];
   }
 
-  console.log(`${colors.blue}Building canonical RIPP artifacts...${colors.reset}\n`);
+  const userIndex = args.indexOf('--user');
+  if (userIndex !== -1 && args[userIndex + 1]) {
+    options.user = args[userIndex + 1];
+  }
+
+  if (options.fromChecklist) {
+    console.log(`${colors.blue}Building from checklist...${colors.reset}\n`);
+  } else {
+    console.log(`${colors.blue}Building canonical RIPP artifacts...${colors.reset}\n`);
+  }
 
   try {
     const result = buildCanonicalArtifacts(cwd, options);
 
+    // Display summary of checklist processing if applicable
+    if (options.fromChecklist && options._validationResults) {
+      const vr = options._validationResults;
+      console.log(`${colors.blue}Checklist Summary:${colors.reset}`);
+      console.log(`  ${colors.gray}Total checked: ${vr.totalChecked}${colors.reset}`);
+      console.log(`  ${colors.green}✓ Accepted: ${vr.accepted}${colors.reset}`);
+      if (vr.rejected > 0) {
+        console.log(`  ${colors.yellow}⚠ Rejected: ${vr.rejected}${colors.reset}`);
+      }
+      console.log('');
+    }
+
     log(colors.green, '✓', 'Build complete');
     console.log(`  ${colors.gray}RIPP Packet: ${result.packetPath}${colors.reset}`);
     console.log(`  ${colors.gray}Handoff MD: ${result.markdownPath}${colors.reset}`);
@@ -1340,6 +1388,88 @@ async function handleBuildCommand(args) {
     process.exit(0);
   } catch (error) {
     console.error(`${colors.red}Error: ${error.message}${colors.reset}`);
+    if (options.fromChecklist) {
+      console.log('');
+      console.log(`${colors.blue}Troubleshooting:${colors.reset}`);
+      console.log('  1. Verify checklist file exists: .ripp/intent.checklist.md');
+      console.log('  2. Ensure at least one candidate is marked with [x]');
+      console.log('  3. Check YAML blocks for syntax errors');
+      console.log('  4. Run "ripp confirm --checklist" to regenerate checklist');
+    }
+    console.log('');
+    process.exit(1);
+  }
+}
+
+async function handleMetricsCommand(args) {
+  const cwd = process.cwd();
+  const rippDir = path.join(cwd, '.ripp');
+
+  // Parse options
+  const options = {
+    report: args.includes('--report'),
+    history: args.includes('--history')
+  };
+
+  // Check if .ripp directory exists
+  if (!fs.existsSync(rippDir)) {
+    console.error(`${colors.red}Error: RIPP directory not found${colors.reset}`);
+    console.error('Run "ripp init" to initialize RIPP in this repository');
+    process.exit(1);
+  }
+
+  try {
+    if (options.history) {
+      // Show metrics history
+      const history = loadMetricsHistory(rippDir);
+      console.log(formatMetricsHistory(history));
+      process.exit(0);
+    }
+
+    // Gather current metrics
+    const metrics = gatherMetrics(rippDir);
+
+    // Display metrics
+    console.log(formatMetricsText(metrics));
+
+    // Write report if requested
+    if (options.report) {
+      const reportPath = path.join(rippDir, 'metrics.json');
+      fs.writeFileSync(reportPath, JSON.stringify(metrics, null, 2), 'utf8');
+
+      // Save to history
+      saveMetricsHistory(rippDir, metrics);
+
+      console.log('');
+      log(colors.green, '✓', `Metrics report saved to ${reportPath}`);
+      console.log('');
+    }
+
+    process.exit(0);
+  } catch (error) {
+    console.error(`${colors.red}Error: ${error.message}${colors.reset}`);
+    process.exit(1);
+  }
+}
+
+function handleDoctorCommand() {
+  const cwd = process.cwd();
+
+  console.log(`${colors.blue}Running RIPP health checks...${colors.reset}`);
+  console.log('');
+
+  try {
+    const results = runHealthChecks(cwd);
+    console.log(formatHealthCheckText(results));
+
+    // Exit with non-zero if there are critical failures
+    const hasCriticalFailures = Object.values(results.checks).some(
+      check => check.status === 'fail'
+    );
+
+    process.exit(hasCriticalFailures ? 1 : 0);
+  } catch (error) {
+    console.error(`${colors.red}Error running health checks: ${error.message}${colors.reset}`);
     process.exit(1);
   }
 }

package/lib/build.js

@@ -1,6 +1,11 @@
 const fs = require('fs');
 const path = require('path');
 const yaml = require('js-yaml');
+const {
+  parseChecklist,
+  buildConfirmedIntent,
+  validateConfirmedBlocks
+} = require('./checklist-parser');
 
 /**
  * RIPP Build - Canonical Artifact Compilation
@@ -11,17 +16,26 @@ const yaml = require('js-yaml');
  * Build canonical RIPP artifacts from confirmed intent
  */
 function buildCanonicalArtifacts(cwd, options = {}) {
-  const confirmedPath = path.join(cwd, '.ripp', 'intent.confirmed.yaml');
-
-  if (!fs.existsSync(confirmedPath)) {
-    throw new Error('No confirmed intent found. Run "ripp confirm" first.');
-  }
+  let confirmed;
+
+  // Check if building from checklist
+  if (options.fromChecklist) {
+    confirmed = buildFromChecklist(cwd, options);
+  } else {
+    const confirmedPath = path.join(cwd, '.ripp', 'intent.confirmed.yaml');
+
+    if (!fs.existsSync(confirmedPath)) {
+      throw new Error(
+        'No confirmed intent found. Run "ripp confirm" first, or use "ripp build --from-checklist" to build from the checklist.'
+      );
+    }
 
-  const confirmedContent = fs.readFileSync(confirmedPath, 'utf8');
-  const confirmed = yaml.load(confirmedContent);
+    const confirmedContent = fs.readFileSync(confirmedPath, 'utf8');
+    confirmed = yaml.load(confirmedContent);
 
-  if (!confirmed.confirmed || confirmed.confirmed.length === 0) {
-    throw new Error('No confirmed intent blocks found');
+    if (!confirmed.confirmed || confirmed.confirmed.length === 0) {
+      throw new Error('No confirmed intent blocks found');
+    }
   }
 
   // Build RIPP packet from confirmed intent
@@ -50,6 +64,97 @@ function buildCanonicalArtifacts(cwd, options = {}) {
   };
 }
 
+/**
+ * Build from checklist markdown file
+ * Parses checklist, validates checked items, and generates confirmed intent
+ */
+function buildFromChecklist(cwd, options = {}) {
+  const checklistPath = path.join(cwd, '.ripp', 'intent.checklist.md');
+
+  // Check if checklist exists
+  if (!fs.existsSync(checklistPath)) {
+    throw new Error(
+      `Checklist not found at ${checklistPath}. Run "ripp confirm --checklist" to generate it.`
+    );
+  }
+
+  // Read and parse checklist
+  const checklistContent = fs.readFileSync(checklistPath, 'utf8');
+  const parseResult = parseChecklist(checklistContent);
+
+  // Check for parsing errors
+  if (parseResult.errors.length > 0) {
+    const errorMsg = [
+      'Failed to parse checklist:',
+      ...parseResult.errors.map(e => `  - ${e}`)
+    ].join('\n');
+    throw new Error(errorMsg);
+  }
+
+  // Check if any candidates were checked
+  if (parseResult.candidates.length === 0) {
+    throw new Error(
+      'No candidates selected in checklist. Mark candidates with [x] and save the file, then run this command again.'
+    );
+  }
+
+  // Display warnings if any
+  if (parseResult.warnings.length > 0 && options.showWarnings !== false) {
+    console.warn('\n⚠️  Warnings:');
+    parseResult.warnings.forEach(w => console.warn(`  - ${w}`));
+    console.warn('');
+  }
+
+  // Build confirmed intent structure
+  const confirmed = buildConfirmedIntent(parseResult.candidates, {
+    user: options.user || 'checklist',
+    timestamp: new Date().toISOString()
+  });
+
+  // Validate confirmed blocks
+  const validation = validateConfirmedBlocks(confirmed.confirmed);
+
+  // Store validation results for reporting
+  const validationResults = {
+    totalChecked: parseResult.candidates.length,
+    accepted: validation.accepted.length,
+    rejected: validation.rejected.length,
+    reasons: validation.reasons
+  };
+
+  // If there are rejected blocks, report them
+  if (validation.rejected.length > 0) {
+    console.warn('\n⚠️  Some candidates were rejected:');
+    validation.rejected.forEach(block => {
+      const reasons = validation.reasons[block.section] || [];
+      console.warn(`  - ${block.section}: ${reasons.join(', ')}`);
+    });
+    console.warn('');
+  }
+
+  // Check if we have any accepted blocks
+  if (validation.accepted.length === 0) {
+    throw new Error(
+      'No valid candidates found. All selected candidates failed validation. Please review and fix the checklist.'
+    );
+  }
+
+  // Use only accepted blocks
+  const finalConfirmed = {
+    version: confirmed.version,
+    confirmed: validation.accepted
+  };
+
+  // Save confirmed intent for traceability
+  const confirmedPath = path.join(cwd, '.ripp', 'intent.confirmed.yaml');
+  fs.writeFileSync(confirmedPath, yaml.dump(finalConfirmed, { indent: 2 }), 'utf8');
+
+  // Store validation results on options for reporting in handleBuildCommand
+  options._validationResults = validationResults;
+
+  return finalConfirmed;
+}
+
 /**
  * Build RIPP packet from confirmed intent blocks
  */
@@ -334,5 +439,6 @@ function generateHandoffMarkdown(packet, confirmed) {
 module.exports = {
   buildCanonicalArtifacts,
   buildRippPacket,
-  generateHandoffMarkdown
+  generateHandoffMarkdown,
+  buildFromChecklist
 };