@the-cascade-protocol/cli 0.2.0

package/src/commands/pod/query.ts

@@ -0,0 +1,224 @@
+/**
+ * cascade pod query <pod-dir>
+ *
+ * Query data within a Cascade Pod by type (medications, conditions, etc.)
+ * or across all data types.
+ */
+
+import type { Command } from 'commander';
+import * as path from 'path';
+import { printResult, printError, printVerbose, type OutputOptions } from '../../lib/output.js';
+import {
+  DATA_TYPES,
+  resolvePodDir,
+  isDirectory,
+  fileExists,
+  discoverTtlFiles,
+  parseDataFile,
+  extractLabelFromProps,
+  selectKeyProperties,
+} from './helpers.js';
+
+export function registerQuerySubcommand(pod: Command, program: Command): void {
+  pod
+    .command('query')
+    .description('Query data within a pod')
+    .argument('<pod-dir>', 'Path to the Cascade Pod')
+    .option('--medications', 'Query medications')
+    .option('--conditions', 'Query conditions')
+    .option('--allergies', 'Query allergies')
+    .option('--lab-results', 'Query lab results')
+    .option('--immunizations', 'Query immunizations')
+    .option('--vital-signs', 'Query vital signs')
+    .option('--supplements', 'Query supplements')
+    .option('--all', 'Query all data')
+    .action(
+      async (
+        podDir: string,
+        options: {
+          medications?: boolean;
+          conditions?: boolean;
+          allergies?: boolean;
+          labResults?: boolean;
+          immunizations?: boolean;
+          vitalSigns?: boolean;
+          supplements?: boolean;
+          all?: boolean;
+        },
+      ) => {
+        const globalOpts = program.opts() as OutputOptions;
+        const absDir = resolvePodDir(podDir);
+
+        printVerbose(`Querying pod: ${absDir}`, globalOpts);
+        printVerbose(`Filters: ${JSON.stringify(options)}`, globalOpts);
+
+        // Validate pod exists
+        if (!(await isDirectory(absDir))) {
+          printError(`Pod directory not found: ${absDir}`, globalOpts);
+          process.exitCode = 1;
+          return;
+        }
+
+        try {
+          // Determine which data types to query
+          let requestedTypes: string[];
+
+          if (options.all) {
+            // Discover all TTL files in the pod
+            requestedTypes = Object.keys(DATA_TYPES);
+          } else {
+            requestedTypes = [];
+            if (options.medications) requestedTypes.push('medications');
+            if (options.conditions) requestedTypes.push('conditions');
+            if (options.allergies) requestedTypes.push('allergies');
+            if (options.labResults) requestedTypes.push('lab-results');
+            if (options.immunizations) requestedTypes.push('immunizations');
+            if (options.vitalSigns) requestedTypes.push('vital-signs');
+            if (options.supplements) requestedTypes.push('supplements');
+          }
+
+          if (requestedTypes.length === 0) {
+            printError(
+              'No query filter specified. Use --medications, --conditions, --all, etc.',
+              globalOpts,
+            );
+            process.exitCode = 1;
+            return;
+          }
+
+          // Process each requested data type
+          const queryResults: Record<
+            string,
+            {
+              count: number;
+              file: string;
+              records: Array<{
+                id: string;
+                type: string;
+                properties: Record<string, string>;
+              }>;
+              error?: string;
+            }
+          > = {};
+
+          // If --all, also discover any TTL files not in the registry
+          const extraFiles: string[] = [];
+          if (options.all) {
+            const allTtlFiles = await discoverTtlFiles(absDir);
+            const knownPaths = new Set(
+              Object.values(DATA_TYPES).map((dt) =>
+                path.join(absDir, dt.directory, dt.filename),
+              ),
+            );
+            // Also exclude index.ttl, manifest.ttl, profile/card.ttl, type indexes
+            const excludePaths = new Set([
+              path.join(absDir, 'index.ttl'),
+              path.join(absDir, 'manifest.ttl'),
+              path.join(absDir, 'profile', 'card.ttl'),
+              path.join(absDir, 'settings', 'publicTypeIndex.ttl'),
+              path.join(absDir, 'settings', 'privateTypeIndex.ttl'),
+            ]);
+            for (const f of allTtlFiles) {
+              if (!knownPaths.has(f) && !excludePaths.has(f)) {
+                extraFiles.push(f);
+              }
+            }
+          }
+
+          for (const typeName of requestedTypes) {
+            const typeInfo = DATA_TYPES[typeName];
+            if (!typeInfo) continue;
+
+            const filePath = path.join(absDir, typeInfo.directory, typeInfo.filename);
+            if (!(await fileExists(filePath))) {
+              printVerbose(`Skipping ${typeName}: file not found at ${filePath}`, globalOpts);
+              continue;
+            }
+
+            const { records, error } = await parseDataFile(filePath);
+
+            queryResults[typeName] = {
+              count: records.length,
+              file: `${typeInfo.directory}/${typeInfo.filename}`,
+              records: records.map((r) => ({
+                id: r.id,
+                type: r.type,
+                properties: r.properties,
+              })),
+              error,
+            };
+          }
+
+          // Process extra files found in --all mode
+          for (const extraFile of extraFiles) {
+            const relPath = path.relative(absDir, extraFile);
+            const baseName = path.basename(extraFile, '.ttl');
+
+            const { records, error } = await parseDataFile(extraFile);
+            if (records.length > 0) {
+              queryResults[baseName] = {
+                count: records.length,
+                file: relPath,
+                records: records.map((r) => ({
+                  id: r.id,
+                  type: r.type,
+                  properties: r.properties,
+                })),
+                error,
+              };
+            }
+          }
+
+          // Output results
+          if (globalOpts.json) {
+            printResult(
+              {
+                pod: podDir,
+                dataTypes: queryResults,
+              },
+              globalOpts,
+            );
+          } else {
+            // Human-readable output
+            const typeKeys = Object.keys(queryResults);
+            if (typeKeys.length === 0) {
+              console.log('No data found for the specified query filters.');
+              return;
+            }
+
+            for (const typeName of typeKeys) {
+              const data = queryResults[typeName];
+              const typeInfo = DATA_TYPES[typeName];
+              const displayLabel = typeInfo?.label ?? typeName;
+
+              console.log(`\n=== ${displayLabel} (${data.count} records) ===`);
+              if (data.error) {
+                console.log(`  Error: ${data.error}`);
+                continue;
+              }
+              console.log(`  File: ${data.file}\n`);
+
+              for (let i = 0; i < data.records.length; i++) {
+                const rec = data.records[i];
+                const label = extractLabelFromProps(rec.properties);
+                const idShort = rec.id.length > 40 ? rec.id.substring(0, 40) + '...' : rec.id;
+
+                console.log(`  ${i + 1}. ${label ?? rec.type} (${idShort})`);
+
+                // Show key properties
+                const keyProps = selectKeyProperties(typeName, rec.properties);
+                for (const [key, value] of Object.entries(keyProps)) {
+                  console.log(`     ${key}: ${value}`);
+                }
+                console.log('');
+              }
+            }
+          }
+        } catch (err: unknown) {
+          const message = err instanceof Error ? err.message : String(err);
+          printError(`Failed to query pod: ${message}`, globalOpts);
+          process.exitCode = 1;
+        }
+      },
+    );
+}

package/src/commands/serve.ts

@@ -0,0 +1,92 @@
+/**
+ * cascade serve
+ *
+ * Start a local MCP-compatible agent server that exposes Cascade Protocol
+ * tools to AI agents.
+ *
+ * Transports:
+ *   stdio  — Standard input/output (for Claude Desktop, Claude Code)
+ *   sse    — Server-Sent Events over HTTP (for web-based agents)
+ *
+ * Options:
+ *   --mcp                     Enable MCP (Model Context Protocol) mode
+ *   --transport <transport>   Transport type (stdio|sse) [default: stdio]
+ *   --port <port>             Port for SSE transport [default: 3000]
+ *   --pod <path>              Default Pod directory path
+ *
+ * Environment Variables:
+ *   CASCADE_POD_PATH          Default Pod directory (overridden by --pod)
+ *
+ * Claude Desktop configuration:
+ *   {
+ *     "mcpServers": {
+ *       "cascade": {
+ *         "command": "cascade",
+ *         "args": ["serve", "--mcp"],
+ *         "env": { "CASCADE_POD_PATH": "/path/to/pod" }
+ *       }
+ *     }
+ *   }
+ */
+
+import { Command } from 'commander';
+import { printError, printVerbose, type OutputOptions } from '../lib/output.js';
+import { startServer } from '../lib/mcp/server.js';
+
+export function registerServeCommand(program: Command): void {
+  program
+    .command('serve')
+    .description('Start local agent server')
+    .option('--mcp', 'Enable MCP (Model Context Protocol) mode')
+    .option('--transport <transport>', 'Transport type (stdio|sse)', 'stdio')
+    .option('--port <port>', 'Port for SSE transport', '3000')
+    .option('--pod <path>', 'Default Pod directory path')
+    .action(
+      async (options: {
+        mcp?: boolean;
+        transport: string;
+        port: string;
+        pod?: string;
+      }) => {
+        const globalOpts = program.opts() as OutputOptions;
+
+        if (!options.mcp) {
+          printError(
+            'The --mcp flag is required. Usage: cascade serve --mcp',
+            globalOpts,
+          );
+          console.error('');
+          console.error('Examples:');
+          console.error('  cascade serve --mcp                           # stdio transport');
+          console.error('  cascade serve --mcp --transport sse --port 3000  # SSE transport');
+          console.error('  cascade serve --mcp --pod ./my-pod            # with default Pod');
+          process.exitCode = 1;
+          return;
+        }
+
+        const transport = options.transport as 'stdio' | 'sse';
+        if (transport !== 'stdio' && transport !== 'sse') {
+          printError(
+            `Invalid transport: "${options.transport}". Must be "stdio" or "sse".`,
+            globalOpts,
+          );
+          process.exitCode = 1;
+          return;
+        }
+
+        printVerbose(`Starting MCP server with transport: ${transport}`, globalOpts);
+
+        try {
+          await startServer({
+            transport,
+            port: parseInt(options.port, 10),
+            podPath: options.pod,
+          });
+        } catch (err: unknown) {
+          const message = err instanceof Error ? err.message : String(err);
+          printError(`Failed to start server: ${message}`, globalOpts);
+          process.exitCode = 1;
+        }
+      },
+    );
+}

package/src/commands/validate.ts

@@ -0,0 +1,303 @@
+/**
+ * cascade validate <file-or-dir>
+ *
+ * Validate Cascade Protocol data against SHACL shapes.
+ *
+ * Options:
+ *   --shapes <shapes-dir>  Path to custom SHACL shapes directory
+ *   --json                 Output results as JSON
+ *   --verbose              Show detailed validation information
+ *
+ * Exit codes:
+ *   0 = all files pass validation
+ *   1 = one or more validation failures
+ *   2 = errors (file not found, malformed Turtle, etc.)
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { Command } from 'commander';
+import { printVerbose, type OutputOptions } from '../lib/output.js';
+import {
+  loadShapes,
+  validateFile,
+  findTurtleFiles,
+  type ValidationResult,
+} from '../lib/shacl-validator.js';
+
+/** ANSI color codes for terminal output */
+const colors = {
+  reset: '\x1b[0m',
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  cyan: '\x1b[36m',
+  dim: '\x1b[2m',
+  bold: '\x1b[1m',
+};
+
+/** Severity icons for human-readable output */
+const severityIcons: Record<string, string> = {
+  violation: `${colors.red}FAIL${colors.reset}`,
+  warning: `${colors.yellow}WARN${colors.reset}`,
+  info: `${colors.blue}INFO${colors.reset}`,
+};
+
+/**
+ * Format a single validation result for human-readable output.
+ */
+function formatResultHuman(result: ValidationResult, verbose: boolean): string {
+  const lines: string[] = [];
+  const relPath = result.file;
+
+  if (result.valid) {
+    lines.push(`${colors.green}PASS${colors.reset} ${relPath} (${result.quadCount} triples)`);
+    if (verbose && result.shapesUsed.length > 0) {
+      lines.push(`     Shapes: ${result.shapesUsed.join(', ')}`);
+    }
+    if (verbose && result.subjects.length > 0) {
+      const typesSummary = result.subjects
+        .flatMap((s) => s.types.map(uriToLocalName))
+        .filter((t, i, a) => a.indexOf(t) === i);
+      lines.push(`     Types: ${typesSummary.join(', ')}`);
+    }
+  } else {
+    const violations = result.results.filter((r) => r.severity === 'violation');
+    const warnings = result.results.filter((r) => r.severity === 'warning');
+    const infos = result.results.filter((r) => r.severity === 'info');
+
+    const countParts: string[] = [];
+    if (violations.length > 0) countParts.push(`${violations.length} violation${violations.length !== 1 ? 's' : ''}`);
+    if (warnings.length > 0) countParts.push(`${warnings.length} warning${warnings.length !== 1 ? 's' : ''}`);
+    if (infos.length > 0) countParts.push(`${infos.length} info`);
+
+    const statusIcon = violations.length > 0
+      ? `${colors.red}FAIL${colors.reset}`
+      : `${colors.yellow}WARN${colors.reset}`;
+
+    lines.push(`${statusIcon} ${relPath} (${result.quadCount} triples, ${countParts.join(', ')})`);
+
+    if (result.shapesUsed.length > 0) {
+      lines.push(`     Shapes: ${result.shapesUsed.join(', ')}`);
+    }
+
+    // Group issues by severity
+    for (const issue of result.results) {
+      const icon = severityIcons[issue.severity] ?? issue.severity;
+      const focusInfo = issue.focusNode ? ` [${uriToLocalName(issue.focusNode)}]` : '';
+      lines.push(`  ${icon} ${issue.message}${focusInfo}`);
+      if (issue.property) {
+        lines.push(`       Property: ${issue.property}`);
+      }
+      if (issue.shape) {
+        lines.push(`       Shape: ${issue.shape}`);
+      }
+      if (issue.value !== undefined) {
+        lines.push(`       Value: ${issue.value}`);
+      }
+      if (issue.specLink) {
+        lines.push(`       Spec: ${colors.cyan}${issue.specLink}${colors.reset}`);
+      }
+    }
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Extract local name from a URI (fragment or last path segment).
+ */
+function uriToLocalName(uri: string): string {
+  if (uri.includes('#')) {
+    return uri.split('#').pop() ?? uri;
+  }
+  return uri.split('/').pop() ?? uri;
+}
+
+/**
+ * Print a summary line for batch validation.
+ */
+function printSummary(
+  results: ValidationResult[],
+  opts: OutputOptions,
+): void {
+  if (opts.json) return; // JSON mode outputs the full array
+
+  const total = results.length;
+  const passed = results.filter((r) => r.valid).length;
+  const failed = total - passed;
+
+  const totalViolations = results.reduce(
+    (sum, r) => sum + r.results.filter((i) => i.severity === 'violation').length,
+    0,
+  );
+  const totalWarnings = results.reduce(
+    (sum, r) => sum + r.results.filter((i) => i.severity === 'warning').length,
+    0,
+  );
+  const totalInfos = results.reduce(
+    (sum, r) => sum + r.results.filter((i) => i.severity === 'info').length,
+    0,
+  );
+
+  console.log('');
+  console.log(`${colors.bold}Validation Summary${colors.reset}`);
+  console.log(`  Files: ${total} total, ${colors.green}${passed} passed${colors.reset}, ${failed > 0 ? `${colors.red}${failed} failed${colors.reset}` : '0 failed'}`);
+
+  const parts: string[] = [];
+  if (totalViolations > 0) parts.push(`${colors.red}${totalViolations} violations${colors.reset}`);
+  if (totalWarnings > 0) parts.push(`${colors.yellow}${totalWarnings} warnings${colors.reset}`);
+  if (totalInfos > 0) parts.push(`${colors.blue}${totalInfos} info${colors.reset}`);
+  if (parts.length > 0) {
+    console.log(`  Issues: ${parts.join(', ')}`);
+  }
+}
+
+export function registerValidateCommand(program: Command): void {
+  program
+    .command('validate')
+    .description('Validate Cascade data against SHACL shapes')
+    .argument('<file-or-dir>', 'Turtle file or directory to validate')
+    .option('--shapes <shapes-dir>', 'Path to custom SHACL shapes directory')
+    .action(async (fileOrDir: string, options: { shapes?: string }) => {
+      const globalOpts = program.opts() as OutputOptions;
+
+      // Resolve the path
+      const targetPath = path.resolve(fileOrDir);
+
+      // Check if path exists
+      if (!fs.existsSync(targetPath)) {
+        if (globalOpts.json) {
+          console.log(JSON.stringify({ error: `Path not found: ${targetPath}` }, null, 2));
+        } else {
+          console.error(`${colors.red}ERROR${colors.reset}: Path not found: ${targetPath}`);
+        }
+        process.exitCode = 2;
+        return;
+      }
+
+      // Load SHACL shapes
+      printVerbose('Loading SHACL shapes...', globalOpts);
+
+      let shapesStore;
+      let shapeFiles: string[];
+      try {
+        const loaded = loadShapes(options.shapes);
+        shapesStore = loaded.store;
+        shapeFiles = loaded.shapeFiles;
+        printVerbose(`Loaded ${shapeFiles.length} shape files: ${shapeFiles.join(', ')}`, globalOpts);
+      } catch (e: unknown) {
+        const msg = e instanceof Error ? e.message : String(e);
+        if (globalOpts.json) {
+          console.log(JSON.stringify({ error: msg }, null, 2));
+        } else {
+          console.error(`${colors.red}ERROR${colors.reset}: ${msg}`);
+        }
+        process.exitCode = 2;
+        return;
+      }
+
+      // Determine files to validate
+      let filesToValidate: string[];
+      const stat = fs.statSync(targetPath);
+
+      if (stat.isDirectory()) {
+        filesToValidate = findTurtleFiles(targetPath);
+        if (filesToValidate.length === 0) {
+          if (globalOpts.json) {
+            console.log(JSON.stringify({ error: `No .ttl files found in ${targetPath}` }, null, 2));
+          } else {
+            console.error(`${colors.yellow}WARNING${colors.reset}: No .ttl files found in ${targetPath}`);
+          }
+          process.exitCode = 2;
+          return;
+        }
+        printVerbose(`Found ${filesToValidate.length} Turtle files in ${targetPath}`, globalOpts);
+      } else if (stat.isFile()) {
+        if (!targetPath.endsWith('.ttl')) {
+          if (globalOpts.json) {
+            console.log(JSON.stringify({ error: `Not a Turtle file: ${targetPath}` }, null, 2));
+          } else {
+            console.error(`${colors.red}ERROR${colors.reset}: Not a Turtle file (expected .ttl): ${targetPath}`);
+          }
+          process.exitCode = 2;
+          return;
+        }
+        filesToValidate = [targetPath];
+      } else {
+        if (globalOpts.json) {
+          console.log(JSON.stringify({ error: `Not a file or directory: ${targetPath}` }, null, 2));
+        } else {
+          console.error(`${colors.red}ERROR${colors.reset}: Not a file or directory: ${targetPath}`);
+        }
+        process.exitCode = 2;
+        return;
+      }
+
+      // Validate each file
+      const results: ValidationResult[] = [];
+      let hasErrors = false;
+      let hasViolations = false;
+
+      for (const file of filesToValidate) {
+        printVerbose(`Validating: ${file}`, globalOpts);
+
+        try {
+          const result = validateFile(file, shapesStore, shapeFiles);
+          results.push(result);
+
+          if (!result.valid) {
+            const violations = result.results.filter((r) => r.severity === 'violation');
+            if (violations.length > 0) {
+              hasViolations = true;
+            }
+          }
+
+          // Print result immediately in human-readable mode
+          if (!globalOpts.json) {
+            console.log(formatResultHuman(result, globalOpts.verbose));
+          }
+        } catch (e: unknown) {
+          hasErrors = true;
+          const msg = e instanceof Error ? e.message : String(e);
+          const errorResult: ValidationResult = {
+            valid: false,
+            file,
+            results: [{
+              severity: 'violation',
+              shape: '',
+              property: '',
+              message: `Error processing file: ${msg}`,
+            }],
+            shapesUsed: [],
+            quadCount: 0,
+            subjects: [],
+          };
+          results.push(errorResult);
+          if (!globalOpts.json) {
+            console.log(formatResultHuman(errorResult, globalOpts.verbose));
+          }
+        }
+      }
+
+      // Output JSON
+      if (globalOpts.json) {
+        console.log(JSON.stringify(results, null, 2));
+      } else {
+        // Print summary for multiple files
+        if (results.length > 1) {
+          printSummary(results, globalOpts);
+        }
+      }
+
+      // Set exit code
+      if (hasErrors) {
+        process.exitCode = 2;
+      } else if (hasViolations) {
+        process.exitCode = 1;
+      } else {
+        process.exitCode = 0;
+      }
+    });
+}

package/src/index.ts

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+
+/**
+ * @the-cascade-protocol/cli
+ *
+ * Cascade Protocol CLI - Validate, convert, and manage health data.
+ *
+ * Usage:
+ *   cascade <command> [options]
+ *
+ * Commands:
+ *   validate      Validate Cascade data against SHACL shapes
+ *   convert       Convert between health data formats
+ *   pod           Manage Cascade Pod structures
+ *   conformance   Run conformance test suite
+ *   serve         Start local agent server
+ *   capabilities  Show machine-readable tool descriptions
+ */
+
+import { Command } from 'commander';
+import { registerValidateCommand } from './commands/validate.js';
+import { registerConvertCommand } from './commands/convert.js';
+import { registerPodCommand } from './commands/pod/index.js';
+import { registerConformanceCommand } from './commands/conformance.js';
+import { registerServeCommand } from './commands/serve.js';
+import { registerCapabilitiesCommand } from './commands/capabilities.js';
+
+const program = new Command();
+
+program
+  .name('cascade')
+  .description('Cascade Protocol CLI')
+  .version('0.2.0')
+  .option('--verbose', 'Verbose output', false)
+  .option('--json', 'Output results as JSON (machine-readable)', false);
+
+// Register all commands
+registerValidateCommand(program);
+registerConvertCommand(program);
+registerPodCommand(program);
+registerConformanceCommand(program);
+registerServeCommand(program);
+registerCapabilitiesCommand(program);
+
+// Custom help text with examples
+program.addHelpText(
+  'after',
+  `
+Examples:
+  cascade validate record.ttl
+  cascade convert --from fhir --to cascade patient.json
+  cascade pod init ./my-pod
+  cascade capabilities
+  cascade capabilities --json
+`,
+);
+
+program.parse();