@the-cascade-protocol/cli 0.2.0

package/src/commands/pod/index.ts

@@ -0,0 +1,32 @@
+/**
+ * cascade pod <subcommand>
+ *
+ * Manage Cascade Pod structures.
+ *
+ * Subcommands:
+ *   init <directory>    Initialize a new Cascade Pod
+ *   query <pod-dir>     Query data within a pod
+ *   export <pod-dir>    Export pod data
+ *   info <pod-dir>      Show pod metadata and statistics
+ *
+ * This module delegates to focused subcommand modules:
+ *   - init.ts    Pod initialization with templates
+ *   - query.ts   Data querying by type
+ *   - export.ts  Pod export (zip/directory)
+ *   - info.ts    Pod metadata and statistics
+ */
+
+import { Command } from 'commander';
+import { registerInitSubcommand } from './init.js';
+import { registerQuerySubcommand } from './query.js';
+import { registerExportSubcommand } from './export.js';
+import { registerInfoSubcommand } from './info.js';
+
+export function registerPodCommand(program: Command): void {
+  const pod = program.command('pod').description('Manage Cascade Pod structures');
+
+  registerInitSubcommand(pod, program);
+  registerQuerySubcommand(pod, program);
+  registerExportSubcommand(pod, program);
+  registerInfoSubcommand(pod, program);
+}

package/src/commands/pod/info.ts

@@ -0,0 +1,239 @@
+/**
+ * cascade pod info <pod-dir>
+ *
+ * Show pod metadata and statistics, including patient profile,
+ * data file summary, and provenance information.
+ */
+
+import type { Command } from 'commander';
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { printResult, printError, printVerbose, type OutputOptions } from '../../lib/output.js';
+import {
+  parseTurtleFile,
+  getSubjectsByType,
+  getProperties,
+  shortenIRI,
+} from '../../lib/turtle-parser.js';
+import {
+  DATA_TYPES,
+  CASCADE_NAMESPACES,
+  resolvePodDir,
+  isDirectory,
+  fileExists,
+  discoverTtlFiles,
+  readPatientProfile,
+  normalizeProvenanceLabel,
+} from './helpers.js';
+
+export function registerInfoSubcommand(pod: Command, program: Command): void {
+  pod
+    .command('info')
+    .description('Show pod metadata and statistics')
+    .argument('<pod-dir>', 'Path to the Cascade Pod')
+    .action(async (podDir: string) => {
+      const globalOpts = program.opts() as OutputOptions;
+      const absDir = resolvePodDir(podDir);
+
+      printVerbose(`Getting info for pod: ${absDir}`, globalOpts);
+
+      // Validate pod exists
+      if (!(await isDirectory(absDir))) {
+        printError(`Pod directory not found: ${absDir}`, globalOpts);
+        process.exitCode = 1;
+        return;
+      }
+
+      try {
+        // Read patient profile info
+        const profile = await readPatientProfile(absDir);
+
+        // Scan data files
+        const clinicalSummary: Array<{ file: string; records: number; provenance: string; label: string }> = [];
+        const wellnessSummary: Array<{ file: string; records: number; provenance: string; label: string }> = [];
+        const provenanceSources = new Set<string>();
+
+        // Get last modified time of the pod
+        let lastModified: Date | undefined;
+        const allTtlFiles = await discoverTtlFiles(absDir);
+
+        for (const filePath of allTtlFiles) {
+          const stat = await fs.stat(filePath);
+          if (!lastModified || stat.mtime > lastModified) {
+            lastModified = stat.mtime;
+          }
+        }
+
+        // Analyze each known data type
+        for (const [, typeInfo] of Object.entries(DATA_TYPES)) {
+          const filePath = path.join(absDir, typeInfo.directory, typeInfo.filename);
+          if (!(await fileExists(filePath))) continue;
+
+          const result = await parseTurtleFile(filePath);
+          if (!result.success) continue;
+
+          // Count records by type
+          let recordCount = 0;
+          for (const rdfType of typeInfo.rdfTypes) {
+            recordCount += getSubjectsByType(result.store, rdfType).length;
+          }
+
+          // If no records found by type, count all typed subjects
+          if (recordCount === 0 && result.subjects.length > 0) {
+            recordCount = result.subjects.length;
+          }
+
+          // Detect provenance
+          const provenanceValues = new Set<string>();
+          for (const subject of result.subjects) {
+            const props = getProperties(result.store, subject.uri);
+            const prov = props[CASCADE_NAMESPACES.cascade + 'dataProvenance'];
+            if (prov) {
+              for (const p of prov) {
+                const shortProv = normalizeProvenanceLabel(shortenIRI(p));
+                provenanceValues.add(shortProv);
+                provenanceSources.add(shortProv);
+              }
+            }
+          }
+
+          // For wellness files, also check for prov:wasGeneratedBy / cascade:sourceType
+          // which indicates DeviceGenerated provenance
+          if (provenanceValues.size === 0) {
+            const allQuads = result.quads;
+            const hasDeviceSource = allQuads.some(
+              (q) =>
+                (q.predicate.value === CASCADE_NAMESPACES.cascade + 'sourceType' &&
+                  (q.object.value === 'healthKit' || q.object.value === 'bluetoothDevice')) ||
+                // Also detect device provenance from prov:wasGeneratedBy patterns
+                (q.predicate.value === 'http://www.w3.org/ns/prov#wasGeneratedBy'),
+            );
+            // If in wellness directory and has device data patterns, infer DeviceGenerated
+            if (hasDeviceSource || typeInfo.directory === 'wellness') {
+              const hasDeviceTypes = allQuads.some(
+                (q) =>
+                  q.predicate.value === 'http://www.w3.org/1999/02/22-rdf-syntax-ns#type' &&
+                  (q.object.value.includes('HeartRateData') ||
+                    q.object.value.includes('BloodPressureData') ||
+                    q.object.value.includes('ActivityData') ||
+                    q.object.value.includes('SleepData') ||
+                    q.object.value.includes('DailyVitalReading') ||
+                    q.object.value.includes('DailyActivitySnapshot') ||
+                    q.object.value.includes('DailySleepSnapshot') ||
+                    q.object.value === 'http://hl7.org/fhir/Observation'),
+              );
+              if (hasDeviceSource || hasDeviceTypes) {
+                provenanceValues.add('cascade:DeviceGenerated');
+                provenanceSources.add('cascade:DeviceGenerated');
+              }
+            }
+          }
+
+          const provenanceStr = provenanceValues.size > 0
+            ? Array.from(provenanceValues).join(', ')
+            : 'Unknown';
+
+          // Determine record description
+          let recordDesc: string;
+          // For time-series data (vital signs, heart rate, etc.), show as "X days" if applicable
+          const isTimeSeries = ['vital-signs', 'heart-rate', 'blood-pressure', 'activity', 'sleep'].some(
+            (ts) => typeInfo.filename.includes(ts.replace('-', '-')),
+          );
+          if (isTimeSeries && recordCount >= 28) {
+            recordDesc = `${recordCount} days`;
+          } else if (recordCount === 1) {
+            recordDesc = '1 record';
+          } else {
+            recordDesc = `${recordCount} records`;
+          }
+
+          const entry = {
+            file: typeInfo.filename,
+            records: recordCount,
+            provenance: provenanceStr,
+            label: `${typeInfo.filename.padEnd(22)} ${recordDesc.padEnd(16)} (${provenanceStr})`,
+          };
+
+          if (typeInfo.directory === 'clinical') {
+            clinicalSummary.push(entry);
+          } else {
+            wellnessSummary.push(entry);
+          }
+        }
+
+        if (globalOpts.json) {
+          printResult(
+            {
+              pod: podDir,
+              patient: {
+                name: profile.name,
+                age: profile.age,
+                dateOfBirth: profile.dateOfBirth,
+              },
+              schemaVersion: profile.schemaVersion,
+              lastModified: lastModified?.toISOString(),
+              clinical: clinicalSummary.map((s) => ({
+                file: s.file,
+                records: s.records,
+                provenance: s.provenance,
+              })),
+              wellness: wellnessSummary.map((s) => ({
+                file: s.file,
+                records: s.records,
+                provenance: s.provenance,
+              })),
+              provenanceSources: Array.from(provenanceSources),
+            },
+            globalOpts,
+          );
+        } else {
+          // Human-readable output
+          console.log(`\nCascade Pod: ${podDir}\n`);
+
+          if (profile.name) {
+            const ageStr = profile.age ? ` (age ${profile.age})` : '';
+            console.log(`Patient: ${profile.name}${ageStr}`);
+          }
+          if (profile.schemaVersion) {
+            console.log(`Schema Version: ${profile.schemaVersion}`);
+          }
+          if (lastModified) {
+            console.log(`Last Modified: ${lastModified.toISOString().split('T')[0]}`);
+          }
+
+          if (clinicalSummary.length > 0) {
+            console.log('\nData Summary:');
+            console.log('  Clinical:');
+            for (const entry of clinicalSummary) {
+              console.log(`    ${entry.label}`);
+            }
+          }
+
+          if (wellnessSummary.length > 0) {
+            if (clinicalSummary.length === 0) {
+              console.log('\nData Summary:');
+            }
+            console.log('  Wellness:');
+            for (const entry of wellnessSummary) {
+              console.log(`    ${entry.label}`);
+            }
+          }
+
+          if (provenanceSources.size > 0) {
+            console.log(`\nProvenance Sources: ${Array.from(provenanceSources).join(', ')}`);
+          }
+
+          if (clinicalSummary.length === 0 && wellnessSummary.length === 0) {
+            console.log('\nThis pod has no data files yet.');
+            console.log('Add TTL files to the clinical/ or wellness/ directories to get started.');
+          }
+
+          console.log('');
+        }
+      } catch (err: unknown) {
+        const message = err instanceof Error ? err.message : String(err);
+        printError(`Failed to read pod info: ${message}`, globalOpts);
+        process.exitCode = 1;
+      }
+    });
+}

package/src/commands/pod/init.ts

@@ -0,0 +1,273 @@
+/**
+ * cascade pod init <directory>
+ *
+ * Initialize a new Cascade Pod with the standard directory structure,
+ * template files, and discovery documents.
+ */
+
+import type { Command } from 'commander';
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { printResult, printError, printVerbose, type OutputOptions } from '../../lib/output.js';
+import { resolvePodDir, fileExists } from './helpers.js';
+
+// ─── Pod Init Templates ──────────────────────────────────────────────────────
+
+function wellKnownSolid(absPath: string): string {
+  return JSON.stringify(
+    {
+      '@context': 'https://www.w3.org/ns/solid/terms',
+      pod_root: '/',
+      profile: '/profile/card.ttl#me',
+      storage: '/',
+      publicTypeIndex: '/settings/publicTypeIndex.ttl',
+      privateTypeIndex: '/settings/privateTypeIndex.ttl',
+      podUri: `file://${absPath}/`,
+      version: '1.0',
+    },
+    null,
+    2,
+  );
+}
+
+const PROFILE_CARD_TTL = `@prefix cascade: <https://ns.cascadeprotocol.org/core/v1#> .
+@prefix foaf: <http://xmlns.com/foaf/0.1/> .
+@prefix solid: <http://www.w3.org/ns/solid/terms#> .
+@prefix pim: <http://www.w3.org/ns/pim/space#> .
+@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
+
+# =============================================================================
+# WebID Profile Card
+# =============================================================================
+# This is a Solid-compatible WebID profile for the Pod owner.
+# Edit this file to add patient demographics and identity information.
+#
+# The <#me> fragment serves as the WebID for this Pod.
+# =============================================================================
+
+<#me> a foaf:Person ;
+    # ── Edit the fields below to personalize your Pod ──
+    # foaf:name "First Last" ;
+    # foaf:givenName "First" ;
+    # foaf:familyName "Last" ;
+    # cascade:dateOfBirth "1990-01-01"^^xsd:date ;
+
+    # ── Discovery links (do not remove) ──
+    solid:publicTypeIndex </settings/publicTypeIndex.ttl> ;
+    solid:privateTypeIndex </settings/privateTypeIndex.ttl> ;
+    pim:storage </> ;
+
+    cascade:schemaVersion "1.3" .
+`;
+
+const PUBLIC_TYPE_INDEX_TTL = `@prefix solid: <http://www.w3.org/ns/solid/terms#> .
+@prefix cascade: <https://ns.cascadeprotocol.org/core/v1#> .
+@prefix health: <https://ns.cascadeprotocol.org/health/v1#> .
+@prefix clinical: <https://ns.cascadeprotocol.org/clinical/v1#> .
+
+# =============================================================================
+# Public Type Index
+# =============================================================================
+# Maps data types to their storage locations in the Pod.
+# Public registrations are visible to authorized applications.
+#
+# As you populate your Pod with data, add type registrations here so that
+# agents and applications can discover where to find each data type.
+# =============================================================================
+
+<> a solid:TypeIndex, solid:ListedDocument .
+
+# Type registrations will be added as data is populated.
+# Example:
+# <#medications> a solid:TypeRegistration ;
+#     solid:forClass health:MedicationRecord ;
+#     solid:instance </clinical/medications.ttl> .
+#
+# <#conditions> a solid:TypeRegistration ;
+#     solid:forClass health:ConditionRecord ;
+#     solid:instance </clinical/conditions.ttl> .
+`;
+
+const PRIVATE_TYPE_INDEX_TTL = `@prefix solid: <http://www.w3.org/ns/solid/terms#> .
+@prefix health: <https://ns.cascadeprotocol.org/health/v1#> .
+@prefix clinical: <https://ns.cascadeprotocol.org/clinical/v1#> .
+
+# =============================================================================
+# Private Type Index
+# =============================================================================
+# Maps wellness and device data types to their storage locations.
+# Private registrations require explicit authorization to access.
+#
+# Wellness data (heart rate, activity, sleep, etc.) is typically registered
+# here rather than in the public type index.
+# =============================================================================
+
+<> a solid:TypeIndex, solid:UnlistedDocument .
+
+# Type registrations will be added as wellness data is populated.
+# Example:
+# <#heartRate> a solid:TypeRegistration ;
+#     solid:forClass health:HeartRateData ;
+#     solid:instance </wellness/heart-rate.ttl> .
+`;
+
+function indexTtl(dirName: string): string {
+  const now = new Date().toISOString();
+  return `@prefix ldp: <http://www.w3.org/ns/ldp#> .
+@prefix dcterms: <http://purl.org/dc/terms/> .
+@prefix cascade: <https://ns.cascadeprotocol.org/core/v1#> .
+@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
+
+# =============================================================================
+# Root LDP Container
+# =============================================================================
+# This is the root index of this Cascade Pod, structured as an LDP Basic
+# Container per Solid Protocol conventions. It enumerates every resource
+# in the Pod for discoverability by agents and applications.
+#
+# Update this file as you add or remove resources.
+# =============================================================================
+
+<> a ldp:BasicContainer ;
+    dcterms:title "${dirName} -- Cascade Pod" ;
+    dcterms:description "A Cascade Protocol Pod initialized with the cascade CLI." ;
+    dcterms:created "${now}"^^xsd:dateTime ;
+    cascade:schemaVersion "1.3" ;
+
+    # ── Profile & Settings ──
+    ldp:contains
+        <profile/card.ttl> ,
+        <settings/publicTypeIndex.ttl> ,
+        <settings/privateTypeIndex.ttl> .
+
+    # ── Add clinical and wellness resources below as they are created ──
+    # ldp:contains <clinical/medications.ttl> .
+    # ldp:contains <wellness/heart-rate.ttl> .
+`;
+}
+
+const README_MD = `# Cascade Protocol Pod
+
+This directory is a **Cascade Protocol Pod** -- a portable, self-describing collection of personal health data serialized as RDF/Turtle files.
+
+## Structure
+
+\`\`\`
+.well-known/
+  solid              # Pod discovery document (JSON)
+profile/
+  card.ttl           # WebID profile (identity + discovery links)
+settings/
+  publicTypeIndex.ttl    # Maps clinical data types to file locations
+  privateTypeIndex.ttl   # Maps wellness data types to file locations
+clinical/            # Clinical records (EHR-sourced data)
+wellness/            # Wellness records (device and self-reported data)
+index.ttl            # Root LDP container listing all resources
+\`\`\`
+
+## Getting Started
+
+1. Edit \`profile/card.ttl\` to set the Pod owner's name and demographics.
+2. Add clinical data files (e.g., \`clinical/medications.ttl\`) and register them in \`settings/publicTypeIndex.ttl\`.
+3. Add wellness data files (e.g., \`wellness/heart-rate.ttl\`) and register them in \`settings/privateTypeIndex.ttl\`.
+4. Update \`index.ttl\` to list all resources.
+
+## Useful Commands
+
+\`\`\`bash
+cascade pod info .           # Show Pod summary
+cascade pod query . --all    # Query all data in the Pod
+cascade pod export . --format zip   # Export as ZIP archive
+cascade validate .           # Validate against SHACL shapes
+\`\`\`
+
+## Learn More
+
+- Cascade Protocol: https://cascadeprotocol.org
+- Pod Structure Spec: https://cascadeprotocol.org/docs/spec/pod-structure
+- Cascade SDK: https://github.com/nickthorpe71/cascade-sdk-swift
+`;
+
+// ─── Command Registration ────────────────────────────────────────────────────
+
+export function registerInitSubcommand(pod: Command, program: Command): void {
+  pod
+    .command('init')
+    .description('Initialize a new Cascade Pod')
+    .argument('<directory>', 'Directory to initialize as a Cascade Pod')
+    .action(async (directory: string) => {
+      const globalOpts = program.opts() as OutputOptions;
+      const absDir = resolvePodDir(directory);
+      const dirName = path.basename(absDir);
+
+      printVerbose(`Initializing pod at: ${absDir}`, globalOpts);
+
+      try {
+        // Check if directory already has pod structure
+        if (await fileExists(path.join(absDir, 'index.ttl'))) {
+          printError(`Directory already contains a Cascade Pod: ${absDir}`, globalOpts);
+          process.exitCode = 1;
+          return;
+        }
+
+        // Create directory structure
+        const dirs = [
+          path.join(absDir, '.well-known'),
+          path.join(absDir, 'profile'),
+          path.join(absDir, 'settings'),
+          path.join(absDir, 'clinical'),
+          path.join(absDir, 'wellness'),
+        ];
+
+        for (const dir of dirs) {
+          await fs.mkdir(dir, { recursive: true });
+        }
+
+        // Write template files
+        await fs.writeFile(path.join(absDir, '.well-known', 'solid'), wellKnownSolid(absDir));
+        await fs.writeFile(path.join(absDir, 'profile', 'card.ttl'), PROFILE_CARD_TTL);
+        await fs.writeFile(path.join(absDir, 'settings', 'publicTypeIndex.ttl'), PUBLIC_TYPE_INDEX_TTL);
+        await fs.writeFile(path.join(absDir, 'settings', 'privateTypeIndex.ttl'), PRIVATE_TYPE_INDEX_TTL);
+        await fs.writeFile(path.join(absDir, 'index.ttl'), indexTtl(dirName));
+        await fs.writeFile(path.join(absDir, 'README.md'), README_MD);
+
+        const filesCreated = [
+          '.well-known/solid',
+          'profile/card.ttl',
+          'settings/publicTypeIndex.ttl',
+          'settings/privateTypeIndex.ttl',
+          'clinical/',
+          'wellness/',
+          'index.ttl',
+          'README.md',
+        ];
+
+        if (globalOpts.json) {
+          printResult(
+            {
+              status: 'created',
+              directory: absDir,
+              files: filesCreated,
+              message: 'Cascade Pod initialized successfully.',
+            },
+            globalOpts,
+          );
+        } else {
+          console.log(`Cascade Pod initialized at: ${absDir}\n`);
+          console.log('Created:');
+          for (const f of filesCreated) {
+            console.log(`  ${f}`);
+          }
+          console.log('\nNext steps:');
+          console.log('  1. Edit profile/card.ttl to set patient name and demographics');
+          console.log('  2. Add data files to clinical/ and wellness/ directories');
+          console.log('  3. Register data types in settings/publicTypeIndex.ttl');
+          console.log(`  4. Run: cascade pod info ${directory}`);
+        }
+      } catch (err: unknown) {
+        const message = err instanceof Error ? err.message : String(err);
+        printError(`Failed to initialize pod: ${message}`, globalOpts);
+        process.exitCode = 1;
+      }
+    });
+}