@the-cascade-protocol/cli 0.2.0 → 0.2.1

package/src/commands/conformance.ts

@@ -1,447 +0,0 @@
-/**
- * cascade conformance run
- *
- * Run conformance test suite against a CLI command or self-test.
- *
- * Options:
- *   --suite <fixtures-dir>    Path to test fixtures directory
- *   --command "<cmd>"         External command to test
- *   --self                    Run self-conformance tests
- *   --json                    Output results as JSON
- *   --verbose                 Show detailed test output
- */
-
-import fs from 'node:fs';
-import path from 'node:path';
-import { Command } from 'commander';
-import { loadShapes, validateTurtle } from '../lib/shacl-validator.js';
-import { parseTurtle } from '../lib/turtle-parser.js';
-import { printResult, printError, printVerbose, type OutputOptions } from '../lib/output.js';
-import type { ValidationResult } from '../lib/shacl-validator.js';
-
-// ---------------------------------------------------------------------------
-// Types
-// ---------------------------------------------------------------------------
-
-/** Shape of a single conformance fixture JSON file. */
-interface ConformanceFixture {
-  id: string;
-  description: string;
-  dataType: string;
-  vocabulary: string;
-  input: Record<string, unknown>;
-  expectedOutput: {
-    turtle: string;
-    validationMode: 'shacl-valid' | 'exact-match';
-  };
-  shouldAccept: boolean;
-  tags: string[];
-  shaclConstraintViolated?: string;
-  notes?: string;
-}
-
-/** Result of running a single fixture. */
-interface FixtureResult {
-  id: string;
-  description: string;
-  dataType: string;
-  status: 'passed' | 'failed' | 'error';
-  negative: boolean;
-  details?: string;
-  validationDetails?: ValidationResult;
-}
-
-/** Aggregate report for the full suite run. */
-interface SuiteReport {
-  suite: string;
-  mode: string;
-  total: number;
-  passed: number;
-  failed: number;
-  errors: number;
-  results: FixtureResult[];
-  byDataType: Record<string, { total: number; passed: number; failed: number; errors: number }>;
-}
-
-// ---------------------------------------------------------------------------
-// Fixture loading
-// ---------------------------------------------------------------------------
-
-/**
- * Load and parse all `.json` fixture files from the given directory.
- * Files are sorted by id so output order is deterministic.
- */
-function loadFixtures(suiteDir: string): ConformanceFixture[] {
-  if (!fs.existsSync(suiteDir)) {
-    throw new Error(`Fixtures directory not found: ${suiteDir}`);
-  }
-
-  const files = fs
-    .readdirSync(suiteDir)
-    .filter((f) => f.endsWith('.json'))
-    .sort();
-
-  if (files.length === 0) {
-    throw new Error(`No .json fixture files found in ${suiteDir}`);
-  }
-
-  const fixtures: ConformanceFixture[] = [];
-
-  for (const file of files) {
-    const filePath = path.join(suiteDir, file);
-    const raw = fs.readFileSync(filePath, 'utf-8');
-    const fixture = JSON.parse(raw) as ConformanceFixture;
-    fixtures.push(fixture);
-  }
-
-  return fixtures;
-}
-
-// ---------------------------------------------------------------------------
-// Self-conformance runner
-// ---------------------------------------------------------------------------
-
-/**
- * Run a single fixture in self-conformance mode.
- *
- * Positive fixtures (shouldAccept === true):
- *   - Parse the expected turtle
- *   - Run SHACL validation
- *   - PASS if no violations; FAIL otherwise
- *
- * Negative fixtures (shouldAccept === false):
- *   - If turtle is empty: PASS (rejection before serialization)
- *   - If turtle is non-empty: SHACL validate — PASS if violations found, FAIL if clean
- */
-function runSelfFixture(
-  fixture: ConformanceFixture,
-  shapesStore: ReturnType<typeof loadShapes>['store'],
-  shapeFiles: string[],
-  opts: OutputOptions,
-): FixtureResult {
-  const base: Pick<FixtureResult, 'id' | 'description' | 'dataType' | 'negative'> = {
-    id: fixture.id,
-    description: fixture.description,
-    dataType: fixture.dataType,
-    negative: !fixture.shouldAccept,
-  };
-
-  const turtle = fixture.expectedOutput.turtle;
-  const validationMode = fixture.expectedOutput.validationMode;
-
-  try {
-    if (fixture.shouldAccept) {
-      // ---- Positive fixture ----
-
-      // Step 1: Parse the turtle
-      const parseResult = parseTurtle(turtle);
-      if (!parseResult.success) {
-        return {
-          ...base,
-          status: 'failed',
-          details: `Turtle parse error: ${parseResult.errors.join('; ')}`,
-        };
-      }
-
-      // Step 2: SHACL validation
-      const validation = validateTurtle(turtle, shapesStore, shapeFiles, fixture.id);
-
-      if (validationMode === 'shacl-valid') {
-        if (validation.valid) {
-          printVerbose(`  [${fixture.id}] SHACL valid (${validation.quadCount} quads)`, opts);
-          return { ...base, status: 'passed', validationDetails: validation };
-        } else {
-          const violations = validation.results
-            .filter((r) => r.severity === 'violation')
-            .map((r) => `${r.shape}.${r.property}: ${r.message}`)
-            .join('; ');
-          return {
-            ...base,
-            status: 'failed',
-            details: `SHACL violations: ${violations}`,
-            validationDetails: validation,
-          };
-        }
-      } else if (validationMode === 'exact-match') {
-        // Exact-match: for now, verify it parses and is SHACL-valid
-        // Full normalized triple-by-triple equivalence is deferred
-        if (validation.valid) {
-          printVerbose(
-            `  [${fixture.id}] exact-match: parsed & SHACL valid (full normalization deferred)`,
-            opts,
-          );
-          return { ...base, status: 'passed', validationDetails: validation };
-        } else {
-          const violations = validation.results
-            .filter((r) => r.severity === 'violation')
-            .map((r) => `${r.shape}.${r.property}: ${r.message}`)
-            .join('; ');
-          return {
-            ...base,
-            status: 'failed',
-            details: `SHACL violations (exact-match mode): ${violations}`,
-            validationDetails: validation,
-          };
-        }
-      } else {
-        return {
-          ...base,
-          status: 'error',
-          details: `Unknown validationMode: ${validationMode as string}`,
-        };
-      }
-    } else {
-      // ---- Negative fixture ----
-
-      if (turtle === '') {
-        // Empty turtle means the SDK should reject before serialization — PASS
-        printVerbose(`  [${fixture.id}] negative: empty turtle (pre-serialization rejection)`, opts);
-        return { ...base, status: 'passed' };
-      }
-
-      // Non-empty turtle: validate and expect violations
-      const parseResult = parseTurtle(turtle);
-      if (!parseResult.success) {
-        // Parse failure on negative fixture = PASS (malformed is invalid)
-        printVerbose(`  [${fixture.id}] negative: turtle parse error (expected)`, opts);
-        return { ...base, status: 'passed', details: 'Turtle parse error (expected for negative fixture)' };
-      }
-
-      const validation = validateTurtle(turtle, shapesStore, shapeFiles, fixture.id);
-
-      if (!validation.valid) {
-        // Violations found — PASS for negative fixture
-        const violations = validation.results
-          .filter((r) => r.severity === 'violation')
-          .map((r) => `${r.shape}.${r.property}: ${r.message}`)
-          .join('; ');
-        printVerbose(`  [${fixture.id}] negative: SHACL violations found (expected): ${violations}`, opts);
-        return { ...base, status: 'passed', validationDetails: validation };
-      } else {
-        // No violations — FAIL for negative fixture
-        return {
-          ...base,
-          status: 'failed',
-          details: `Expected SHACL violations but data validated clean. Expected: ${fixture.shaclConstraintViolated ?? 'unspecified'}`,
-          validationDetails: validation,
-        };
-      }
-    }
-  } catch (err: unknown) {
-    const message = err instanceof Error ? err.message : String(err);
-    return {
-      ...base,
-      status: 'error',
-      details: `Unexpected error: ${message}`,
-    };
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Report generation
-// ---------------------------------------------------------------------------
-
-/**
- * Build the aggregate suite report from individual fixture results.
- */
-function buildReport(
-  suitePath: string,
-  mode: string,
-  results: FixtureResult[],
-): SuiteReport {
-  const byDataType: SuiteReport['byDataType'] = {};
-
-  for (const r of results) {
-    if (!byDataType[r.dataType]) {
-      byDataType[r.dataType] = { total: 0, passed: 0, failed: 0, errors: 0 };
-    }
-    const group = byDataType[r.dataType];
-    group.total++;
-    if (r.status === 'passed') group.passed++;
-    else if (r.status === 'failed') group.failed++;
-    else group.errors++;
-  }
-
-  return {
-    suite: suitePath,
-    mode,
-    total: results.length,
-    passed: results.filter((r) => r.status === 'passed').length,
-    failed: results.filter((r) => r.status === 'failed').length,
-    errors: results.filter((r) => r.status === 'error').length,
-    results,
-    byDataType,
-  };
-}
-
-/**
- * Print a human-readable report to stdout.
- */
-function printHumanReport(report: SuiteReport, opts: OutputOptions): void {
-  console.log('');
-  console.log('Cascade Protocol Conformance Test Suite');
-  console.log('========================================');
-  console.log(`Suite: ${report.suite}`);
-  console.log(`Mode: ${report.mode === 'self' ? 'self-conformance' : report.mode}`);
-  console.log(`Fixtures: ${report.total}`);
-  console.log('');
-  console.log('Running tests...');
-  console.log('');
-
-  // Group results by dataType, preserving insertion order
-  const dataTypes: string[] = [];
-  const grouped: Record<string, FixtureResult[]> = {};
-
-  for (const r of report.results) {
-    if (!grouped[r.dataType]) {
-      grouped[r.dataType] = [];
-      dataTypes.push(r.dataType);
-    }
-    grouped[r.dataType].push(r);
-  }
-
-  for (const dt of dataTypes) {
-    const fixtures = grouped[dt];
-    console.log(`  ${dt} (${fixtures.length} fixtures)`);
-
-    for (const r of fixtures) {
-      const icon = r.status === 'passed' ? '\u2713' : r.status === 'failed' ? '\u2717' : '!';
-      const negativeTag = r.negative ? '[negative] ' : '';
-      const statusLine = `    ${icon} ${r.id}: ${negativeTag}${r.description}`;
-      console.log(statusLine);
-
-      if (r.status !== 'passed' && r.details) {
-        console.log(`      ${r.details}`);
-      }
-
-      // In verbose mode, show validation details even for passing tests
-      if (opts.verbose && r.validationDetails) {
-        const vd = r.validationDetails;
-        console.log(`      Quads: ${vd.quadCount}, Shapes: [${vd.shapesUsed.join(', ')}]`);
-        if (vd.results.length > 0) {
-          for (const issue of vd.results) {
-            console.log(`      - [${issue.severity}] ${issue.shape}.${issue.property}: ${issue.message}`);
-          }
-        }
-      }
-    }
-
-    console.log('');
-  }
-
-  // Summary line
-  const parts: string[] = [];
-  parts.push(`${report.passed} passed`);
-  if (report.failed > 0) parts.push(`${report.failed} failed`);
-  else parts.push('0 failed');
-  if (report.errors > 0) parts.push(`${report.errors} errors`);
-  else parts.push('0 errors');
-
-  console.log(`Results: ${parts.join(', ')}`);
-
-  const exitCode = report.failed > 0 || report.errors > 0 ? 1 : 0;
-  console.log(`Exit code: ${exitCode}`);
-}
-
-/**
- * Print the JSON report using the output library.
- */
-function printJsonReport(report: SuiteReport, opts: OutputOptions): void {
-  // Strip validationDetails from results for cleaner JSON output
-  const cleanResults = report.results.map((r) => {
-    const { validationDetails: _vd, ...rest } = r;
-    return rest;
-  });
-
-  printResult(
-    {
-      suite: report.suite,
-      mode: report.mode,
-      total: report.total,
-      passed: report.passed,
-      failed: report.failed,
-      errors: report.errors,
-      results: cleanResults,
-      byDataType: report.byDataType,
-    },
-    opts,
-  );
-}
-
-// ---------------------------------------------------------------------------
-// Command registration
-// ---------------------------------------------------------------------------
-
-export function registerConformanceCommand(program: Command): void {
-  const conformance = program
-    .command('conformance')
-    .description('Run conformance test suite');
-
-  conformance
-    .command('run')
-    .description('Execute conformance tests')
-    .requiredOption('--suite <fixtures-dir>', 'Path to test fixtures directory')
-    .option('--command <cmd>', 'External command to test against')
-    .option('--self', 'Run self-conformance tests')
-    .action(
-      async (options: {
-        suite: string;
-        command?: string;
-        self?: boolean;
-      }) => {
-        const globalOpts = program.opts() as OutputOptions;
-
-        if (!options.command && !options.self) {
-          printError('Either --command or --self must be specified', globalOpts);
-          process.exitCode = 1;
-          return;
-        }
-
-        // External command mode: not yet supported
-        if (options.command) {
-          printError('External command mode not yet supported', globalOpts);
-          process.exitCode = 1;
-          return;
-        }
-
-        // Resolve suite directory
-        const suitePath = path.resolve(options.suite);
-        printVerbose(`Conformance suite: ${suitePath}`, globalOpts);
-        printVerbose('Running self-conformance tests', globalOpts);
-
-        try {
-          // Load fixtures
-          const fixtures = loadFixtures(suitePath);
-          printVerbose(`Loaded ${fixtures.length} fixture(s)`, globalOpts);
-
-          // Load SHACL shapes once
-          const { store: shapesStore, shapeFiles } = loadShapes();
-          printVerbose(`Loaded shapes: ${shapeFiles.join(', ')}`, globalOpts);
-
-          // Run each fixture
-          const results: FixtureResult[] = [];
-
-          for (const fixture of fixtures) {
-            const result = runSelfFixture(fixture, shapesStore, shapeFiles, globalOpts);
-            results.push(result);
-          }
-
-          // Build and output report
-          const report = buildReport(options.suite, 'self', results);
-
-          if (globalOpts.json) {
-            printJsonReport(report, globalOpts);
-          } else {
-            printHumanReport(report, globalOpts);
-          }
-
-          // Set exit code
-          process.exitCode = report.failed > 0 || report.errors > 0 ? 1 : 0;
-        } catch (err: unknown) {
-          const message = err instanceof Error ? err.message : String(err);
-          printError(`Conformance suite failed: ${message}`, globalOpts);
-          process.exitCode = 1;
-        }
-      },
-    );
-}

package/src/commands/convert.ts

@@ -1,164 +0,0 @@
-/**
- * cascade convert --from <format> --to <format> [file]
- *
- * Convert between health data formats.
- * Supports FHIR R4, Cascade Protocol Turtle, and JSON-LD.
- *
- * Options:
- *   --from <format>     Source format (fhir|cascade|c-cda)
- *   --to <format>       Target format (turtle|jsonld|fhir|cascade)
- *   --format <output>   Output serialization format (turtle|jsonld) [default: turtle]
- *   --json              Output results as JSON envelope (machine-readable)
- *   --verbose           Show detailed conversion information
- *
- * Supports stdin piping:
- *   cat patient.json | cascade convert --from fhir --to cascade
- *
- * Zero network calls. All conversion is local.
- */
-
-import { Command } from 'commander';
-import { readFileSync } from 'node:fs';
-import { printResult, printError, printVerbose, type OutputOptions } from '../lib/output.js';
-import { convert, detectFormat, type InputFormat, type OutputFormat } from '../lib/fhir-converter/index.js';
-
-/**
- * Read input from file or stdin.
- * If file is provided, reads from disk.
- * Otherwise reads all of stdin synchronously.
- */
-function readInput(file: string | undefined): string {
-  if (file) {
-    return readFileSync(file, 'utf-8');
-  }
-  // Read from stdin
-  return readFileSync(0, 'utf-8');
-}
-
-export function registerConvertCommand(program: Command): void {
-  program
-    .command('convert')
-    .description('Convert between health data formats')
-    .argument('[file]', 'Input file (reads from stdin if omitted)')
-    .requiredOption('--from <format>', 'Source format (fhir|cascade|c-cda)')
-    .requiredOption('--to <format>', 'Target format (turtle|jsonld|fhir|cascade)')
-    .option('--format <output>', 'Output serialization format (turtle|jsonld)', 'turtle')
-    .action(
-      async (
-        file: string | undefined,
-        options: { from: string; to: string; format: string },
-      ) => {
-        const globalOpts = program.opts() as OutputOptions;
-
-        printVerbose(`Converting from ${options.from} to ${options.to}`, globalOpts);
-        if (file) {
-          printVerbose(`Input file: ${file}`, globalOpts);
-        } else {
-          printVerbose('Reading from stdin', globalOpts);
-        }
-        printVerbose(`Output format: ${options.format}`, globalOpts);
-
-        // 1. Read input
-        let input: string;
-        try {
-          input = readInput(file);
-        } catch (err: any) {
-          printError(`Failed to read input: ${err.message}`, globalOpts);
-          process.exitCode = 1;
-          return;
-        }
-
-        if (!input.trim()) {
-          printError('Empty input', globalOpts);
-          process.exitCode = 1;
-          return;
-        }
-
-        // 2. Validate source/target formats
-        const validInputFormats = ['fhir', 'cascade', 'c-cda'];
-        const validOutputFormats = ['turtle', 'jsonld', 'fhir', 'cascade'];
-
-        if (!validInputFormats.includes(options.from)) {
-          printError(`Invalid source format: ${options.from}. Valid: ${validInputFormats.join(', ')}`, globalOpts);
-          process.exitCode = 1;
-          return;
-        }
-
-        if (!validOutputFormats.includes(options.to)) {
-          printError(`Invalid target format: ${options.to}. Valid: ${validOutputFormats.join(', ')}`, globalOpts);
-          process.exitCode = 1;
-          return;
-        }
-
-        // 3. Auto-detect format if helpful (validate matches declared)
-        const detected = detectFormat(input);
-        if (detected && detected !== options.from) {
-          printVerbose(
-            `Note: Input appears to be ${detected} but --from says ${options.from}. Proceeding with declared format.`,
-            globalOpts,
-          );
-        }
-
-        // 4. Run conversion
-        const outputSerialization = (options.format === 'jsonld' ? 'jsonld' : 'turtle') as 'turtle' | 'jsonld';
-        const result = await convert(
-          input,
-          options.from as InputFormat,
-          options.to as OutputFormat,
-          outputSerialization,
-        );
-
-        // 5. Output
-        if (!result.success) {
-          for (const err of result.errors) {
-            printError(err, globalOpts);
-          }
-          for (const warn of result.warnings) {
-            printVerbose(`Warning: ${warn}`, globalOpts);
-          }
-          process.exitCode = 1;
-          return;
-        }
-
-        // Print warnings in verbose mode
-        for (const warn of result.warnings) {
-          printVerbose(`Warning: ${warn}`, globalOpts);
-        }
-
-        if (globalOpts.json) {
-          // JSON envelope for machine-readable output
-          printResult(
-            {
-              success: true,
-              from: options.from,
-              to: options.to,
-              format: result.format,
-              resourceCount: result.resourceCount,
-              warnings: result.warnings,
-              output: result.output,
-              resources: result.results.map(r => ({
-                resourceType: r.resourceType,
-                cascadeType: r.cascadeType,
-                warnings: r.warnings,
-              })),
-            },
-            globalOpts,
-          );
-        } else {
-          // Direct output (Turtle, JSON-LD, or FHIR JSON)
-          console.log(result.output);
-
-          // Print summary to stderr so it does not pollute piped output
-          if (result.resourceCount > 0) {
-            console.error(
-              `Converted ${result.resourceCount} resource${result.resourceCount > 1 ? 's' : ''} ` +
-              `(${options.from} -> ${result.format})`,
-            );
-          }
-          if (result.warnings.length > 0) {
-            console.error(`${result.warnings.length} warning${result.warnings.length > 1 ? 's' : ''}`);
-          }
-        }
-      },
-    );
-}

package/src/commands/pod/export.ts

@@ -1,85 +0,0 @@
-/**
- * cascade pod export <pod-dir>
- *
- * Export pod data as a ZIP archive or directory copy.
- */
-
-import type { Command } from 'commander';
-import * as path from 'path';
-import { printResult, printError, printVerbose, type OutputOptions } from '../../lib/output.js';
-import { resolvePodDir, isDirectory, copyDirectory, createZipArchive } from './helpers.js';
-
-export function registerExportSubcommand(pod: Command, program: Command): void {
-  pod
-    .command('export')
-    .description('Export pod data')
-    .argument('<pod-dir>', 'Path to the Cascade Pod')
-    .option('--format <fmt>', 'Export format (zip|directory)', 'zip')
-    .option('--output <path>', 'Output path for export')
-    .action(async (podDir: string, options: { format: string; output?: string }) => {
-      const globalOpts = program.opts() as OutputOptions;
-      const absDir = resolvePodDir(podDir);
-
-      printVerbose(`Exporting pod: ${absDir} as ${options.format}`, globalOpts);
-
-      // Validate pod exists
-      if (!(await isDirectory(absDir))) {
-        printError(`Pod directory not found: ${absDir}`, globalOpts);
-        process.exitCode = 1;
-        return;
-      }
-
-      try {
-        if (options.format === 'directory') {
-          // Copy to new directory
-          const outputDir = options.output ?? `${absDir}-export`;
-          await copyDirectory(absDir, outputDir);
-
-          if (globalOpts.json) {
-            printResult(
-              {
-                status: 'exported',
-                format: 'directory',
-                source: absDir,
-                output: outputDir,
-              },
-              globalOpts,
-            );
-          } else {
-            console.log(`Pod exported to directory: ${outputDir}`);
-          }
-        } else if (options.format === 'zip') {
-          // Create ZIP archive
-          const outputZip =
-            options.output ?? `${path.basename(absDir)}.zip`;
-          const absOutputZip = path.resolve(process.cwd(), outputZip);
-
-          await createZipArchive(absDir, absOutputZip);
-
-          if (globalOpts.json) {
-            printResult(
-              {
-                status: 'exported',
-                format: 'zip',
-                source: absDir,
-                output: absOutputZip,
-              },
-              globalOpts,
-            );
-          } else {
-            console.log(`Pod exported to ZIP: ${absOutputZip}`);
-          }
-        } else {
-          printError(
-            `Unknown export format: ${options.format}. Use 'zip' or 'directory'.`,
-            globalOpts,
-          );
-          process.exitCode = 1;
-        }
-      } catch (err: unknown) {
-        const message = err instanceof Error ? err.message : String(err);
-        printError(`Failed to export pod: ${message}`, globalOpts);
-        process.exitCode = 1;
-      }
-    });
-}