@the-cascade-protocol/cli 0.2.0 → 0.2.1

package/src/commands/pod/query.ts

@@ -1,224 +0,0 @@
-/**
- * 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

@@ -1,92 +0,0 @@
-/**
- * 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

@@ -1,303 +0,0 @@
-/**
- * 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

@@ -1,58 +0,0 @@
-#!/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();