babelfhir-ts 1.4.1 → 1.4.3

package/README.md

@@ -234,6 +234,7 @@ Options:
   --schema <format>        Generate schema files alongside outputs (supported: zod)
   --dicomweb               Generate DICOMweb helpers typed to ImagingStudy profiles in the IG
   --recursive              (update only) Recursively search subdirectories for lib/ folders
+  --force                  (update only) Force regeneration even if version and flags haven't changed
   --outDir <dir>           Output directory (alias for second positional argument)
   --fhir-version <ver>     FHIR version to target: r4, r4b, or r5 (auto-detected from package if omitted)
   --package <pkg[@version]>  Download FHIR package from registry and process it (latest if no version)

package/out/src/cli/installCommand.js

@@ -105,9 +105,10 @@ function npmInstall(packagePath) {
         }
         const { args } = result;
         console.log(`Installing package with ${pmName}...`);
+        // shell required on Windows for .cmd wrappers; disabled on Unix to prevent injection
         const child = spawn(pm.cmd, args, {
             stdio: 'inherit',
-            shell: true
+            shell: process.platform === 'win32'
         });
         child.on('exit', (code) => {
             if (code === 0) {

package/out/src/cli/updateCommand.js

@@ -13,14 +13,14 @@ import fs from 'fs';
 import os from 'os';
 import path from 'path';
 import crypto from 'crypto';
-import { generateIntoPackageDirect, resetFetchFailureTracking } from '../generator/index.js';
+import { generateIntoPackageDirect, resetFetchFailureTracking, GENERATOR_VERSION } from '../generator/index.js';
 import { getFhirPackagesCacheDir } from '../generator/core/cacheConfig.js';
 import { resetDiagnostics, buildQualityReport, formatReportSummary } from '../generator/core/sdDiagnostics.js';
 import { detectPackageManager } from './installCommand.js';
 import { spawn } from 'child_process';
 // ── Public entry point ──────────────────────────────────────────────────────
 export async function handleUpdateCommand(opts) {
-    const { packageFilter, recursive, generationFlags, registry, downloadPackage, confirm } = opts;
+    const { packageFilter, recursive, force, generationFlags, registry, downloadPackage, confirm } = opts;
     const startDir = process.cwd();
     // 1. Discover tgz files
     const libDirs = discoverLibDirs(startDir, recursive ?? false);
@@ -55,11 +55,17 @@ export async function handleUpdateCommand(opts) {
     for (const t of targets)
         console.log(`  ${t.igName}@${t.igVersion}  →  ${path.relative(startDir, t.tgzPath)}`);
     console.log('');
-    // 4. Regenerate each package
+    // 4. Regenerate each package (skip if already up to date)
     let updated = 0;
+    let skipped = 0;
     let failed = 0;
     const updatedPackages = [];
     for (const target of targets) {
+        if (!force && isUpToDate(target, generationFlags)) {
+            skipped++;
+            console.log(`✓ ${target.igName}@${target.igVersion} — already up to date (babelfhir-ts ${target.generatorVersion})`);
+            continue;
+        }
         try {
             await regeneratePackage(target, generationFlags, registry, downloadPackage);
             updatedPackages.push({ generatedName: target.generatedName, tgzPath: target.tgzPath });
@@ -70,25 +76,34 @@ export async function handleUpdateCommand(opts) {
             console.error(`✗ Failed to update ${target.igName}@${target.igVersion}: ${err.message}`);
         }
     }
-    // 5. Patch bun.lock integrity hashes for regenerated packages (avoids full lockfile delete)
+    // 5. Remove stale node_modules/<pkg> so bun re-extracts from the updated tgz
     if (updatedPackages.length > 0) {
-        patchBunLockIntegrity(updatedPackages);
+        removeStaleNodeModules(updatedPackages.map((p) => p.generatedName));
     }
-    // 5b. Remove stale node_modules/<pkg> so bun re-extracts from the updated tgz
+    // 6. Patch bun.lock integrity hashes BEFORE install so bun sees matching hashes
     if (updatedPackages.length > 0) {
-        removeStaleNodeModules(updatedPackages.map((p) => p.generatedName));
+        patchBunLockIntegrity(updatedPackages);
     }
-    // 6. Single npm install at the end
+    // 7. Single npm install at the end
     if (updated > 0) {
         console.log('\nReinstalling dependencies...');
         await runInstall();
     }
-    // 7. Summary
+    // 8. Re-patch bun.lock integrity after install (bun may recompute hashes)
+    if (updatedPackages.length > 0) {
+        patchBunLockIntegrity(updatedPackages);
+    }
+    // 9. Summary
     console.log('');
     if (updated > 0)
         console.log(`✓ Updated ${updated} package${updated === 1 ? '' : 's'}`);
+    if (skipped > 0)
+        console.log(`✓ ${skipped} package${skipped === 1 ? '' : 's'} already up to date`);
     if (failed > 0)
         console.error(`✗ ${failed} package${failed === 1 ? '' : 's'} failed`);
+    if (skipped > 0 && updated === 0 && failed === 0) {
+        console.log('  Use --force to regenerate anyway.');
+    }
     return {};
 }
 // ── Install redirect prompt ─────────────────────────────────────────────────
@@ -200,10 +215,15 @@ async function readTgzMetadata(tgzPath, listFn) {
             igVersion,
             ...(pkg?.fhir?.txServer && { txServer: pkg.fhir.txServer }),
             ...(pkg?.fhir?.displayLanguage && { displayLanguage: pkg.fhir.displayLanguage }),
+            ...(pkg?.fhir?.fhirVersion && { fhirVersion: pkg.fhir.fhirVersion }),
             ...(pkg?.fhir?.dicomweb && { dicomweb: true }),
             ...(pkg?.fhir?.noClient && { noClient: true }),
             ...(pkg?.fhir?.noClasses && { noClasses: true }),
             ...(pkg?.fhir?.schema && { schema: pkg.fhir.schema }),
+            // Extract generator version from devDependencies (e.g. "^1.4.2" → "1.4.2")
+            ...(pkg?.devDependencies?.['babelfhir-ts'] && {
+                generatorVersion: pkg.devDependencies['babelfhir-ts'].replace(/^[^\d]*/, ''),
+            }),
         };
     }
     catch {
@@ -222,6 +242,32 @@ function filterBySpec(all, spec) {
     // No version — match by name only
     return all.filter(t => t.igName === spec);
 }
+// ── Up-to-date check ────────────────────────────────────────────────────────
+/**
+ * Check whether a package was already generated with the current babelfhir-ts
+ * version and the same effective flags. Returns true if regeneration can be skipped.
+ */
+function isUpToDate(target, cliFlags) {
+    // No stored version → was generated before this feature existed → regenerate
+    if (!target.generatorVersion)
+        return false;
+    // Compare generator versions (strip pre-release suffixes for comparison: 1.4.2-dev.xxx → 1.4.2)
+    const storedMajorMinorPatch = target.generatorVersion.split('-')[0];
+    const currentMajorMinorPatch = GENERATOR_VERSION.split('-')[0];
+    if (storedMajorMinorPatch !== currentMajorMinorPatch)
+        return false;
+    // Compare generation flags that affect output
+    const flagKeys = ['txServer', 'displayLanguage', 'fhirVersion', 'dicomweb', 'noClient', 'noClasses', 'schema'];
+    for (const key of flagKeys) {
+        const stored = target[key];
+        const cli = cliFlags[key];
+        // CLI flag explicitly set and differs from stored → needs regeneration
+        if (cli !== undefined && cli !== null && cli !== false && cli !== '' && String(cli) !== String(stored ?? '')) {
+            return false;
+        }
+    }
+    return true;
+}
 // ── Regeneration ────────────────────────────────────────────────────────────
 async function regeneratePackage(target, generationFlags, registry, downloadPackage) {
     const spec = `${target.igName}@${target.igVersion}`;
@@ -238,6 +284,10 @@ async function regeneratePackage(target, generationFlags, registry, downloadPack
         mergedFlags.displayLanguage = target.displayLanguage;
         console.log(`  Using display-language from package metadata: ${target.displayLanguage}`);
     }
+    if (target.fhirVersion && !mergedFlags.fhirVersion) {
+        mergedFlags.fhirVersion = target.fhirVersion;
+        console.log(`  Using fhir-version from package metadata: ${target.fhirVersion}`);
+    }
     if (target.dicomweb && mergedFlags.dicomweb === undefined)
         mergedFlags.dicomweb = true;
     if (target.noClient && mergedFlags.noClient === undefined)
@@ -303,41 +353,46 @@ export function patchBunLockIntegrity(updatedPackages) {
     const pm = detectPackageManager();
     if (!pm.cmd.includes('bun'))
         return;
-    // Walk up to find bun.lock (in monorepos it's at the workspace root, not cwd)
-    let lockPath = null;
+    // Collect ALL bun.lock files walking up (monorepos may have one at the
+    // workspace root AND one in a nested app directory).
+    const lockPaths = [];
     let dir = process.cwd();
     while (true) {
         const candidate = path.join(dir, 'bun.lock');
-        if (fs.existsSync(candidate)) {
-            lockPath = candidate;
-            break;
-        }
+        if (fs.existsSync(candidate))
+            lockPaths.push(candidate);
         const parent = path.dirname(dir);
         if (parent === dir)
             break;
         dir = parent;
     }
-    if (!lockPath)
+    if (lockPaths.length === 0)
         return;
-    let lockContent = fs.readFileSync(lockPath, 'utf8');
-    let patched = 0;
-    for (const { generatedName, tgzPath } of updatedPackages) {
-        // Compute new SHA-512 integrity hash
-        const tgzBytes = fs.readFileSync(tgzPath);
-        const hash = crypto.createHash('sha512').update(tgzBytes).digest('base64');
-        const newIntegrity = `sha512-${hash}`;
-        // Match all entries for this package in bun.lock:
-        //   "hl7.fhir.uv.ips-generated": [..., "sha512-oldHash=="],
-        //   "workspace/hl7.fhir.uv.ips-generated": [..., "sha512-oldHash=="],
-        const pattern = new RegExp(`("(?:[^"]*\\/)?${escapeRegExp(generatedName)}"\\s*:\\s*\\[.*?)(sha512-[A-Za-z0-9+/]+=*)`, 'g');
-        lockContent = lockContent.replace(pattern, (_, prefix, _oldHash) => {
-            patched++;
-            return `${prefix}${newIntegrity}`;
-        });
+    let totalPatched = 0;
+    for (const lockPath of lockPaths) {
+        let lockContent = fs.readFileSync(lockPath, 'utf8');
+        let patched = 0;
+        for (const { generatedName, tgzPath } of updatedPackages) {
+            // Compute new SHA-512 integrity hash
+            const tgzBytes = fs.readFileSync(tgzPath);
+            const hash = crypto.createHash('sha512').update(tgzBytes).digest('base64');
+            const newIntegrity = `sha512-${hash}`;
+            // Match entries with existing integrity hashes and replace them:
+            //   "hl7.fhir.uv.ips-generated": [..., "sha512-oldHash=="],
+            const pattern = new RegExp(`("(?:[^"]*\\/)?${escapeRegExp(generatedName)}"\\s*:\\s*\\[.*?)(sha512-[A-Za-z0-9+/]+=*)`, 'g');
+            lockContent = lockContent.replace(pattern, (_, prefix, _oldHash) => {
+                patched++;
+                return `${prefix}${newIntegrity}`;
+            });
+        }
+        if (patched > 0) {
+            fs.writeFileSync(lockPath, lockContent, 'utf8');
+            totalPatched += patched;
+            console.log(`Patched ${patched} integrity hash${patched === 1 ? '' : 'es'} in ${path.relative(process.cwd(), lockPath) || 'bun.lock'}`);
+        }
     }
-    if (patched > 0) {
-        fs.writeFileSync(lockPath, lockContent, 'utf8');
-        console.log(`Patched ${patched} integrity hash${patched === 1 ? '' : 'es'} in bun.lock`);
+    if (totalPatched === 0) {
+        console.log('No integrity hashes found to patch in bun.lock');
     }
 }
 function escapeRegExp(s) {
@@ -437,7 +492,8 @@ function runInstall() {
         const pm = detectPackageManager();
         const pmName = path.basename(pm.cmd).replace(/\.(cmd|exe)$/, '');
         console.log(`Running ${pmName} install...`);
-        const child = spawn(pm.cmd, ['install'], { stdio: 'inherit', shell: true });
+        // shell required on Windows for .cmd wrappers; disabled on Unix to prevent injection
+        const child = spawn(pm.cmd, ['install'], { stdio: 'inherit', shell: process.platform === 'win32' });
         child.on('exit', (code) => code === 0 ? resolve() : reject(new Error(`${pmName} install failed (exit ${code})`)));
         child.on('error', (err) => reject(new Error(`Failed to run ${pmName}: ${err.message}`)));
     });

package/out/src/generator/core/fetchUtils.js

@@ -5,6 +5,37 @@
 import http from "http";
 import https from "https";
 import { USER_AGENT, FETCH_TIMEOUT_MS } from './constants.js';
+/** Maximum number of HTTP redirects to follow before aborting. */
+const MAX_REDIRECTS = 10;
+/**
+ * Validate that a URL uses an allowed scheme (http/https) and does not target
+ * private/internal network addresses (SSRF mitigation).
+ */
+export function assertSafeUrl(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw new Error(`Invalid URL: ${url}`);
+    }
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+        throw new Error(`Blocked request to non-HTTP URL: ${url}`);
+    }
+    const host = parsed.hostname.toLowerCase();
+    if (host === 'localhost' ||
+        host === '127.0.0.1' ||
+        host === '::1' ||
+        host === '0.0.0.0' ||
+        host.startsWith('169.254.') ||
+        host.startsWith('10.') ||
+        host.startsWith('192.168.') ||
+        /^172\.(1[6-9]|2\d|3[01])\./.test(host) ||
+        host.endsWith('.internal') ||
+        host.endsWith('.local')) {
+        throw new Error(`Blocked request to private/internal address: ${host}`);
+    }
+}
 /**
  * Default headers for FHIR API requests
  */
@@ -84,15 +115,20 @@ export async function fetchArrayBuffer(url, options = {}) {
  * Fetch with native https module for streaming (used by downloadFile)
  * This provides better control for large file downloads
  */
-export function fetchStream(url) {
+export function fetchStream(url, redirectCount = 0) {
+    assertSafeUrl(url);
     return new Promise((resolve, reject) => {
         const client = url.startsWith('https') ? https : http;
         client.get(url, {
             headers: FHIR_HEADERS
         }, (response) => {
-            // Handle redirects
+            // Handle redirects with depth limit
             if (response.statusCode && response.statusCode >= 300 && response.statusCode < 400 && response.headers.location) {
-                fetchStream(response.headers.location).then(resolve).catch(reject);
+                if (redirectCount >= MAX_REDIRECTS) {
+                    reject(new Error(`Too many redirects (max ${MAX_REDIRECTS})`));
+                    return;
+                }
+                fetchStream(response.headers.location, redirectCount + 1).then(resolve).catch(reject);
                 return;
             }
             if (response.statusCode !== 200) {
@@ -107,7 +143,8 @@ export function fetchStream(url) {
  * Fetch JSON using native https module with timeout support
  * Used for fallback URLs where we need more control
  */
-export function fetchJsonNative(url, options = {}) {
+export function fetchJsonNative(url, options = {}, redirectCount = 0) {
+    assertSafeUrl(url);
     return new Promise((resolve, reject) => {
         const client = url.startsWith('https') ? https : http;
         const req = client.get(url, {
@@ -117,9 +154,13 @@ export function fetchJsonNative(url, options = {}) {
             },
             timeout: options.timeout || FETCH_TIMEOUT_MS
         }, (res) => {
-            // Handle redirects
+            // Handle redirects with depth limit
             if (res.statusCode && res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
-                fetchJsonNative(res.headers.location, options).then(resolve).catch(reject);
+                if (redirectCount >= MAX_REDIRECTS) {
+                    reject(new Error(`Too many redirects (max ${MAX_REDIRECTS})`));
+                    return;
+                }
+                fetchJsonNative(res.headers.location, options, redirectCount + 1).then(resolve).catch(reject);
                 return;
             }
             if (res.statusCode !== 200) {

package/out/src/generator/emitters/client/clientGenerator.js

@@ -5,6 +5,7 @@ import { logger } from "../../../logger.js";
 import { generateSmartAuth, generateSmartClient } from './smartAuthGenerator.js';
 import { generateReadme, installBaseClientTypes } from './clientReadmeGenerator.js';
 import { versionSlug } from '../../fhir/versionContext.js';
+import { buildSearchParamInterfaces, getSearchParamsTypeName } from './searchParamHelpers.js';
 const log = logger.withTag('client');
 /**
  * Generate FHIR client code for all resource types
@@ -26,14 +27,14 @@ export function generateClient(options) {
         fs.mkdirSync(clientDir, { recursive: true });
     }
     // Generate each file
-    generateTypes(clientDir, resourceTypes);
-    generateResourceReader(clientDir, resourceTypes);
+    generateTypes(clientDir, resourceTypes, options.searchParams);
+    generateResourceReader(clientDir, resourceTypes, options.searchParams);
     generateResourceWriter(clientDir, resourceTypes);
     generateBundleParser(clientDir, resourceTypes);
-    generateFhirClient(clientDir, resourceTypes);
+    generateFhirClient(clientDir, resourceTypes, options.searchParams);
     generateSmartAuth(clientDir);
     generateSmartClient(clientDir, resourceTypes);
-    generateIndex(clientDir, resourceTypes);
+    generateIndex(clientDir, resourceTypes, options.searchParams);
     generateReadme(clientDir);
     // Install base client type declarations so tsc can resolve @babelfhir-ts/client-<version>
     installBaseClientTypes(options.outputDir);
@@ -42,10 +43,12 @@ export function generateClient(options) {
 /**
  * Generate types.ts
  */
-function generateTypes(clientDir, resourceTypes) {
+function generateTypes(clientDir, resourceTypes, searchParams) {
     const unionType = resourceTypes
         .map((rt, idx) => `  ${idx === 0 ? "" : "| "}GeneratedTypes.${rt.profileName}`)
         .join("\n");
+    // Generate per-base-resource-type search param interfaces
+    const searchParamInterfaces = buildSearchParamInterfaces(resourceTypes, searchParams);
     const content = `import type * as GeneratedTypes from "../index.js";
 
 /**
@@ -54,9 +57,34 @@ function generateTypes(clientDir, resourceTypes) {
 export type WithId<T> = { id: string } & T;
 
 /**
- * Search parameters for FHIR resources
+ * Search parameter value type — all values are serialized to query strings.
  */
-export type SearchParams = Record<string, boolean | number | string | string[] | undefined>;
+export type SearchParamValue = boolean | number | string | string[] | undefined;
+
+/**
+ * Search parameters for FHIR resources (generic untyped version).
+ */
+export type SearchParams = Record<string, SearchParamValue>;
+
+/**
+ * Common search parameters supported by all FHIR resources.
+ * Includes an index signature to allow search parameter modifiers (e.g. name:exact).
+ */
+export interface CommonSearchParams {
+  _id?: SearchParamValue;
+  _lastUpdated?: SearchParamValue;
+  _tag?: SearchParamValue;
+  _profile?: SearchParamValue;
+  _security?: SearchParamValue;
+  _count?: SearchParamValue;
+  _sort?: SearchParamValue;
+  _include?: SearchParamValue;
+  _revinclude?: SearchParamValue;
+  _summary?: SearchParamValue;
+  _elements?: SearchParamValue;
+  _total?: SearchParamValue;
+  [key: string]: SearchParamValue;
+}
 
 /**
  * Bundle of FHIR resources
@@ -80,24 +108,34 @@ export interface Bundle<T> {
  */
 export type FhirResource =
 ${unionType};
-`;
+
+${searchParamInterfaces}`;
     fs.writeFileSync(path.join(clientDir, "types.ts"), content);
 }
 /**
  * Generate resource-reader.ts
  */
-function generateResourceReader(clientDir, resourceTypes) {
+function generateResourceReader(clientDir, resourceTypes, searchParams) {
+    // Build reader type aliases with typed search params
     const readerTypes = resourceTypes
-        .map((rt) => `export type ${rt.profileName}Reader = FhirResourceSearcher<GeneratedTypes.${rt.profileName}>;`)
+        .map((rt) => {
+        const spType = getSearchParamsTypeName(rt.baseResourceType, searchParams);
+        return `export type ${rt.profileName}Reader = FhirResourceSearcher<GeneratedTypes.${rt.profileName}, ${spType}>;`;
+    })
         .join("\n");
+    // Collect unique SearchParams type imports from types.ts
+    const spTypeImports = new Set(['SearchParams']);
+    for (const rt of resourceTypes) {
+        spTypeImports.add(getSearchParamsTypeName(rt.baseResourceType, searchParams));
+    }
     const content = `import type * as GeneratedTypes from "../index.js";
 
-import type { Bundle, SearchParams, WithId } from "./types.js";
+import type { Bundle, ${[...spTypeImports].sort().join(', ')}, WithId } from "./types.js";
 
 /**
  * Generic FHIR resource searcher/reader
  */
-export interface FhirResourceSearcher<T> {
+export interface FhirResourceSearcher<T, S extends SearchParams = SearchParams> {
   readonly baseUrl: string;
   readonly resourceType: string;
 
@@ -109,17 +147,17 @@ export interface FhirResourceSearcher<T> {
   /**
    * Search for resources
    */
-  search(params?: SearchParams): Promise<Bundle<WithId<T>>>;
+  search(params?: S): Promise<Bundle<WithId<T>>>;
 
   /**
    * Search and return first result or undefined
    */
-  searchOne(params?: SearchParams): Promise<undefined | WithId<T>>;
+  searchOne(params?: S): Promise<undefined | WithId<T>>;
 
   /**
    * Search and return all results (handles pagination)
    */
-  searchAll(params?: SearchParams): Promise<WithId<T>[]>;
+  searchAll(params?: S): Promise<WithId<T>[]>;
 }
 
 /**
@@ -135,7 +173,7 @@ export type FetchFn = typeof globalThis.fetch;
 /**
  * Implementation of FHIR resource reader
  */
-export class FhirResourceReader<T> implements FhirResourceSearcher<T> {
+export class FhirResourceReader<T, S extends SearchParams = SearchParams> implements FhirResourceSearcher<T, S> {
   private readonly fetchFn: FetchFn;
 
   constructor(
@@ -163,7 +201,7 @@ export class FhirResourceReader<T> implements FhirResourceSearcher<T> {
     return (await response.json()) as WithId<T>;
   }
 
-  async search(params?: SearchParams): Promise<Bundle<WithId<T>>> {
+  async search(params?: S): Promise<Bundle<WithId<T>>> {
     const url = new URL(\`\${this.baseUrl}/\${this.resourceType}\`);
 
     if (params) {
@@ -195,12 +233,12 @@ export class FhirResourceReader<T> implements FhirResourceSearcher<T> {
     return (await response.json()) as Bundle<WithId<T>>;
   }
 
-  async searchOne(params?: SearchParams): Promise<undefined | WithId<T>> {
-    const bundle = await this.search({ ...params, _count: 1 });
+  async searchOne(params?: S): Promise<undefined | WithId<T>> {
+    const bundle = await this.search({ ...params, _count: 1 } as S & { _count: number });
     return bundle.entry?.[0]?.resource;
   }
 
-  async searchAll(params?: SearchParams): Promise<WithId<T>[]> {
+  async searchAll(params?: S): Promise<WithId<T>[]> {
     const results: WithId<T>[] = [];
     let bundle = await this.search(params);
 
@@ -364,6 +402,7 @@ export class FhirResourceWriterImpl<T> implements FhirResourceWriter<T> {
  * Generate bundle-parser.ts
  */
 function generateBundleParser(clientDir, resourceTypes) {
+    const clientPkg = `@babelfhir-ts/client-${versionSlug()}`;
     // Group profiles by base resource type
     const resourceTypeGroups = new Map();
     for (const rt of resourceTypes) {
@@ -382,6 +421,7 @@ function generateBundleParser(clientDir, resourceTypes) {
     })
         .join("\n");
     const content = `import type * as GeneratedTypes from "../index.js";
+import { BundleParser as BaseBundleParser } from "${clientPkg}";
 import type { Bundle, FhirResource } from "./types.js";
 
 /**
@@ -515,6 +555,15 @@ ${parseByTypeCases}
   getBundleType(): 'collection' | 'searchset' | 'transaction-response' | 'transaction' | undefined {
     return this.bundle.type;
   }
+
+  /**
+   * Resolve a FHIR reference within this Bundle.
+   * Supports "ResourceType/id" relative references and full-URL references
+   * matched against entry.fullUrl.
+   */
+  resolveReference<T extends FhirResource>(ref: { reference?: string } | undefined): T | undefined {
+    return BaseBundleParser.resolveReference(ref, this.bundle as any) as T | undefined;
+  }
 }
 
 /**
@@ -529,12 +578,20 @@ export function parseBundle(bundle: Bundle<FhirResource>): BundleParser {
 /**
  * Generate fhir-client.ts
  */
-function generateFhirClient(clientDir, resourceTypes) {
+function generateFhirClient(clientDir, resourceTypes, searchParams) {
+    // Collect search param type imports
+    const spTypeImports = new Set();
+    for (const rt of resourceTypes) {
+        const spType = getSearchParamsTypeName(rt.baseResourceType, searchParams);
+        if (spType !== 'SearchParams')
+            spTypeImports.add(spType);
+    }
     const readerMethods = resourceTypes
         .map((rt) => {
         const methodName = rt.profileName.charAt(0).toLowerCase() + rt.profileName.slice(1);
+        const spType = getSearchParamsTypeName(rt.baseResourceType, searchParams);
         return `  ${methodName}() {
-    return this.forType<GeneratedTypes.${rt.profileName}>("${rt.baseResourceType}");
+    return this.forType<GeneratedTypes.${rt.profileName}, ${spType}>("${rt.baseResourceType}");
   }`;
     })
         .join("\n\n");
@@ -548,13 +605,17 @@ function generateFhirClient(clientDir, resourceTypes) {
         .join("\n\n");
     const slug = versionSlug();
     const clientPkg = `@babelfhir-ts/client-${slug}`;
+    const spImportLine = spTypeImports.size > 0
+        ? `\nimport type { ${[...spTypeImports].sort().join(', ')} } from "./types.js";\n`
+        : '';
     const content = `import {
   FhirReadClient as BaseFhirReadClient,
   FhirWriteClient as BaseFhirWriteClient,
   type FetchFn,
+  type SearchParams,
 } from "${clientPkg}";
 import type * as GeneratedTypes from "../index.js";
-
+${spImportLine}
 /**
  * Profile-specific FHIR Read Client.
  * Extends the base ${slug.toUpperCase()} read client with typed profile accessors.
@@ -622,13 +683,25 @@ export class FhirClient {
 /**
  * Generate index.ts barrel export
  */
-function generateIndex(clientDir, resourceTypes) {
+function generateIndex(clientDir, resourceTypes, searchParams) {
     const readerTypes = resourceTypes
         .map((rt) => `  ${rt.profileName}Reader,`)
         .join("\n");
     const writerTypes = resourceTypes
         .map((rt) => `  ${rt.profileName}Writer,`)
         .join("\n");
+    // Collect per-resource SearchParams type exports
+    const spTypeExports = new Set();
+    if (searchParams && searchParams.size > 0) {
+        for (const rt of resourceTypes) {
+            const spType = getSearchParamsTypeName(rt.baseResourceType, searchParams);
+            if (spType !== 'SearchParams')
+                spTypeExports.add(spType);
+        }
+    }
+    const spExportLine = spTypeExports.size > 0
+        ? `export type { CommonSearchParams, SearchParamValue, ${[...spTypeExports].sort().join(', ')} } from "./types.js";\n`
+        : '';
     const content = `export { FhirClient, FhirReadClient, FhirWriteClient } from "./fhir-client.js";
 export { FhirResourceReader } from "./resource-reader.js";
 export type { FetchFn } from "./resource-reader.js";
@@ -644,7 +717,7 @@ ${writerTypes}
 export { BundleParser, parseBundle } from "./bundle-parser.js";
 export type { BundleEntry } from "./bundle-parser.js";
 export type { Bundle, FhirResource, SearchParams, WithId } from "./types.js";
-export { SmartAuth, discoverEndpoints } from "./smart-auth.js";
+${spExportLine}export { SmartAuth, discoverEndpoints } from "./smart-auth.js";
 export type { SmartConfig, SmartToken, SmartConfiguration, LaunchMode } from "./smart-auth.js";
 export { SmartFhirClient } from "./smart-client.js";
 `;

package/out/src/generator/emitters/client/clientReadmeGenerator.js

@@ -226,14 +226,14 @@ export interface Bundle<T = ${fhirNs}.Resource> {
   entry?: { resource?: T; fullUrl?: string; search?: { mode?: string; score?: number }; request?: { method: string; url: string }; response?: { status: string } }[];
 }
 
-export declare class FhirResourceReader<T extends ${fhirNs}.Resource> {
+export declare class FhirResourceReader<T extends ${fhirNs}.Resource, S extends SearchParams = SearchParams> {
   readonly baseUrl: string;
   readonly resourceType: string;
   constructor(baseUrl: string, resourceType: string, fetchFn?: FetchFn);
   read(id: string): Promise<WithId<T>>;
-  search(params?: SearchParams): Promise<Bundle<WithId<T>>>;
-  searchOne(params?: SearchParams): Promise<WithId<T> | undefined>;
-  searchAll(params?: SearchParams): Promise<WithId<T>[]>;
+  search(params?: S): Promise<Bundle<WithId<T>>>;
+  searchOne(params?: S): Promise<WithId<T> | undefined>;
+  searchAll(params?: S): Promise<WithId<T>[]>;
 }
 
 export declare class FhirResourceWriter<T extends ${fhirNs}.Resource> {
@@ -248,7 +248,7 @@ export declare class FhirResourceWriter<T extends ${fhirNs}.Resource> {
 
 export declare class FhirReadClient {
   constructor(baseUrl: string, fetchFn?: FetchFn);
-  protected forType<T extends ${fhirNs}.Resource>(resourceType: string): FhirResourceReader<T>;
+  protected forType<T extends ${fhirNs}.Resource, S extends SearchParams = SearchParams>(resourceType: string): FhirResourceReader<T, S>;
 }
 
 export declare class FhirWriteClient {
@@ -262,6 +262,13 @@ export declare class FhirClient {
   read(): FhirReadClient;
   write(): FhirWriteClient;
 }
+
+export declare class BundleParser {
+  static getResourcesByType<T extends ${fhirNs}.Resource>(bundle: Bundle<${fhirNs}.Resource>, resourceType: string): WithId<T>[];
+  static getFirstResourceByType<T extends ${fhirNs}.Resource>(bundle: Bundle<${fhirNs}.Resource>, resourceType: string): WithId<T> | undefined;
+  static getAllResources(bundle: Bundle<${fhirNs}.Resource>): ${fhirNs}.Resource[];
+  static resolveReference<T extends ${fhirNs}.Resource>(ref: { reference?: string } | undefined, bundle: Bundle<${fhirNs}.Resource>): T | undefined;
+}
 `;
     fs.writeFileSync(path.join(pkgDir, "index.d.ts"), dts);
 }

package/out/src/generator/emitters/client/searchParamHelpers.js

@@ -0,0 +1,37 @@
+/**
+ * Build per-base-resource-type SearchParams interface declarations for generated types.ts.
+ */
+export function buildSearchParamInterfaces(resourceTypes, searchParams) {
+    if (!searchParams || searchParams.size === 0)
+        return '';
+    const baseTypes = [...new Set(resourceTypes.map(rt => rt.baseResourceType))];
+    const blocks = [];
+    for (const baseType of baseTypes) {
+        const params = searchParams.get(baseType);
+        if (!params?.length)
+            continue;
+        // Sort params alphabetically and deduplicate
+        const sorted = [...params].sort((a, b) => a.code.localeCompare(b.code));
+        const fields = sorted
+            .map(p => `  "${p.code}"?: SearchParamValue;`)
+            .join("\n");
+        blocks.push(`/**
+ * Typed search parameters for ${baseType} resources.
+ * Generated from SearchParameter definitions in the base FHIR spec and IG.
+ */
+export interface ${baseType}SearchParams extends CommonSearchParams {
+${fields}
+}`);
+    }
+    return blocks.join("\n\n") + "\n";
+}
+/**
+ * Get the SearchParams interface name for a given base resource type,
+ * or fall back to SearchParams if none is generated.
+ */
+export function getSearchParamsTypeName(baseResourceType, searchParams) {
+    if (searchParams?.has(baseResourceType) && searchParams.get(baseResourceType).length > 0) {
+        return `${baseResourceType}SearchParams`;
+    }
+    return 'SearchParams';
+}

package/out/src/generator/emitters/interface/interfaceFieldProcessor.js

@@ -535,6 +535,10 @@ export function processFields(ctx, fields, parentInterfaceName, parentFieldType,
             const sanitizedBaseResource = baseResource ? sanitizeIdentifier(baseResource) : undefined;
             const isBaseAbstract = sanitizedBaseResource === 'Base';
             const extendsClause = (sanitizedBaseResource && !isBaseAbstract && !isPrimitiveType(sanitizedBaseResource)) ? ` extends ${sanitizedBaseResource}` : '';
+            // Add resourceType literal for discriminated union support (only for actual FHIR resources, not data types)
+            if (ctx.resourceType && rules().isCoreResource(ctx.resourceType) && !deduped.some(l => /^resourceType[?:]/.test(l))) {
+                deduped.unshift(`resourceType: '${ctx.resourceType}';`);
+            }
             debug('emit root interface', parentInterfaceName, 'extends', sanitizedBaseResource, 'fields', deduped.length);
             interfaces.push(`export interface ${parentInterfaceName}${extendsClause} {\n${deduped.map(l => `    ${l}`).join('\n')}\n}`);
         }

package/out/src/generator/emitters/validator/validatorConstraintBuilders.js

@@ -26,8 +26,16 @@ export function buildRequiredConstraints(fields, arrayFieldPaths, fieldPathMap,
         let rel = relBase;
         if (!rel)
             return;
-        // Skip slicing-declaration fields for choice[x] when slice fields exist.
-        if (relFull.includes('[x]') && !field.sliceName && !field.typeOptions && slicedChoicePaths.has(relFull)) {
+        // Skip slicing-declaration fields for choice[x] when slice fields exist
+        // AND the field is not required. When a profile slices value[x], the field list
+        // contains both a slicing-declaration field (no typeOptions, inherits base type
+        // like Quantity) and slice fields (with typeOptions). For optional fields, skip
+        // the declaration since the slice field handles the constraint. But for required
+        // fields (min >= 1), we MUST still emit the existence check — e.g.,
+        // medication[x] (min:1) needs "medication.exists()" to verify at least one
+        // concrete medication variant is present.
+        const fieldMin = typeof field.min === 'number' ? field.min : (field.isOptional ? 0 : 1);
+        if (relFull.includes('[x]') && !field.sliceName && !field.typeOptions && slicedChoicePaths.has(relFull) && fieldMin < 1) {
             return;
         }
         // For choice types (value[x]), append the concrete type name to get the correct accessor.

package/out/src/generator/index.js

@@ -1,7 +1,7 @@
 import path from 'path';
 import fs from 'fs';
 import { fileURLToPath } from 'url';
-import { extractPackage, readStructureDefinitionsFromDir, readStructureDefinitionsFromDependencies, createPackageFromDir, readValueSetCodesWithDependencies, readValueSetsFromDir, detectFhirVersion, ensureDependenciesDownloaded } from './parser/packageParser.js';
+import { extractPackage, readStructureDefinitionsFromDir, readStructureDefinitionsFromDependencies, createPackageFromDir, readValueSetCodesWithDependencies, readValueSetsFromDir, detectFhirVersion, ensureDependenciesDownloaded, readSearchParametersFromDir } from './parser/packageParser.js';
 import { fetchStructureDefinitions, fetchStructureDefinition, registerLocalStructureDefinitions, clearLocalStructureDefinitions, collectValueSetBindingUrls } from './parser/sdParser.js';
 import { ensureDirectoryExists, downloadFile } from './core/utils.js';
 import { getFhirPackagesCacheDir } from './core/cacheConfig.js';
@@ -9,6 +9,8 @@ import { processStructureDefinition, resetFetchFailureTracking, getFetchFailureC
 import { logger } from '../logger.js';
 import { initVersionContext, ctx, versionSlug } from './fhir/versionContext.js';
 import { DEFAULT_FHIR_VERSION } from './fhir/types.js';
+import { FHIR_VERSIONS } from './fhir/versionRegistry.js';
+import { ensureCorePackage } from './fhir/corePackageResolver.js';
 import { spawn } from 'child_process';
 import { buildProfileRegistries, expandValueSetsWithTx, emitValueSetFiles, cleanupStaleValueSetDir, initGenerationContext, enrichValueSetsFromCodeMap, collectReferencedDependencyProfiles, } from './generationHelpers.js';
 /** Resolve the babelfhir-ts CLI version from its own package.json (used to stamp generated packages). */
@@ -23,7 +25,7 @@ const _generatorPkgPath = [
 catch {
     return false;
 } });
-const GENERATOR_VERSION = _generatorPkgPath ? JSON.parse(fs.readFileSync(_generatorPkgPath, 'utf8')).version : 'unknown';
+export const GENERATOR_VERSION = _generatorPkgPath ? JSON.parse(fs.readFileSync(_generatorPkgPath, 'utf8')).version : 'unknown';
 import { resetTimings, startPhase, getTimingSummary, formatTimingSummary } from './timing.js';
 export { getTimingSummary, formatTimingSummary } from './timing.js';
 const log = logger.withTag('generator');
@@ -41,6 +43,44 @@ function buildFhirChildTypeMapFromJson() {
     return result;
 }
 export { resetFetchFailureTracking, getFetchFailureCount, getFetchFailureWarning };
+/**
+ * Load search parameters from the FHIR core package and the IG's extracted root.
+ * Merges both sets, with IG params taking precedence for deduplication by code.
+ */
+async function loadSearchParameters(extractedRoot) {
+    const slug = versionSlug();
+    const coreSpec = FHIR_VERSIONS[slug]?.corePackage;
+    const merged = new Map();
+    // Load base FHIR search params from the core package
+    if (coreSpec) {
+        try {
+            const coreDir = await ensureCorePackage(coreSpec);
+            const coreParams = readSearchParametersFromDir(coreDir);
+            for (const [baseType, params] of coreParams) {
+                merged.set(baseType, [...params]);
+            }
+            log.debug(`Loaded ${coreParams.size} base resource type search param groups from core package`);
+        }
+        catch (err) {
+            log.warn(`Could not load core search parameters: ${err.message}`);
+        }
+    }
+    // Load IG-specific search params (may override or extend base)
+    const igParams = readSearchParametersFromDir(extractedRoot);
+    for (const [baseType, params] of igParams) {
+        const existing = merged.get(baseType) || [];
+        for (const p of params) {
+            if (!existing.some(e => e.code === p.code)) {
+                existing.push(p);
+            }
+        }
+        merged.set(baseType, existing);
+    }
+    if (igParams.size > 0) {
+        log.debug(`Loaded ${igParams.size} IG-specific search param groups`);
+    }
+    return merged;
+}
 /**
  * Copy the fhir-<version>.d.ts ambient module declaration into the output directory.
  * This is required so generated code can import from 'fhir/r4' (or r4b) even when
@@ -89,9 +129,10 @@ async function compileTypeScriptToJS(dir) {
         };
         const tsconfigPath = path.join(dir, 'tsconfig.temp.json');
         fs.writeFileSync(tsconfigPath, JSON.stringify(tsconfig, null, 2));
+        // shell required on Windows for .cmd wrappers; disabled on Unix to prevent injection
         const child = spawn(tscCmd, ['-p', tsconfigPath], {
             stdio: 'inherit',
-            shell: true
+            shell: process.platform === 'win32'
         });
         child.on('exit', (code) => {
             // Clean up temp tsconfig
@@ -408,6 +449,7 @@ export async function generateIntoPackage(packageArchivePath, outArchivePath, fl
                 ...(originalPkg.fhirVersions && { fhirVersions: originalPkg.fhirVersions }),
                 ...(flags?.txServer && { txServer: flags.txServer }),
                 ...(flags?.displayLanguage && { displayLanguage: flags.displayLanguage }),
+                ...(flags?.fhirVersion && { fhirVersion: flags.fhirVersion }),
                 ...(flags?.dicomweb && { dicomweb: true }),
                 ...(flags?.noClient && { noClient: true }),
                 ...(flags?.noClasses && { noClasses: true }),
@@ -461,9 +503,12 @@ export async function generateIntoPackage(packageArchivePath, outArchivePath, fl
         // Generate FHIR client (unless --no-client flag)
         if (!flags?.noClient) {
             logger.log('Generating FHIR client...');
+            // Load search parameters from base FHIR spec + IG for typed search param generation
+            const searchParams = await loadSearchParameters(extractedRoot);
             const { generateClient } = await import('./emitters/client/clientGenerator.js');
             generateClient({
-                outputDir
+                outputDir,
+                searchParams,
             });
             logger.log('FHIR client generated');
         }
@@ -653,6 +698,7 @@ export async function generateIntoPackageDirect(packageArchivePath, flags) {
             ...(originalPkg.fhirVersions && { fhirVersions: originalPkg.fhirVersions }),
             ...(flags?.txServer && { txServer: flags.txServer }),
             ...(flags?.displayLanguage && { displayLanguage: flags.displayLanguage }),
+            ...(flags?.fhirVersion && { fhirVersion: flags.fhirVersion }),
             ...(flags?.dicomweb && { dicomweb: true }),
             ...(flags?.noClient && { noClient: true }),
             ...(flags?.noClasses && { noClasses: true }),
@@ -694,8 +740,9 @@ export async function generateIntoPackageDirect(packageArchivePath, flags) {
     await generateIndexFile(outputDir);
     if (!flags?.noClient) {
         logger.log('Generating FHIR client...');
+        const searchParams = await loadSearchParameters(extractedRoot);
         const { generateClient } = await import('./emitters/client/clientGenerator.js');
-        generateClient({ outputDir });
+        generateClient({ outputDir, searchParams });
         logger.log('FHIR client generated');
     }
     // Generate DICOMweb helpers (--dicomweb flag)
@@ -893,9 +940,11 @@ export async function generateForDirectory(inputDir, outputDir, flags) {
     // Generate FHIR client (unless --no-client flag)
     if (!flags?.noClient) {
         logger.log('Generating FHIR client...');
+        const searchParams = await loadSearchParameters(inputDir);
         const { generateClient } = await import('./emitters/client/clientGenerator.js');
         generateClient({
-            outputDir
+            outputDir,
+            searchParams,
         });
         logger.log('FHIR client generated');
     }

package/out/src/generator/parser/packageParser.js

@@ -314,7 +314,32 @@ export async function extractPackage(packagePath) {
         await extract({ cwd: extractDir, file: packagePath });
     }
     else if (packagePath.endsWith(".zip")) {
-        await fs.createReadStream(packagePath).pipe(unzipper.Extract({ path: extractDir })).promise();
+        // Use unzipper.Parse to validate each entry path against Zip Slip before extraction
+        const resolvedExtractDir = path.resolve(extractDir);
+        await new Promise((resolve, reject) => {
+            fs.createReadStream(packagePath)
+                .pipe(unzipper.Parse())
+                .on('entry', (entry) => {
+                const entryPath = path.join(extractDir, entry.path);
+                const resolvedEntry = path.resolve(entryPath);
+                // Zip Slip check: reject entries that escape the extraction directory
+                if (!resolvedEntry.startsWith(resolvedExtractDir + path.sep) && resolvedEntry !== resolvedExtractDir) {
+                    logger.warn(`[security] Skipping zip entry with path traversal: ${entry.path}`);
+                    entry.autodrain();
+                    return;
+                }
+                const dir = path.dirname(entryPath);
+                fs.mkdirSync(dir, { recursive: true });
+                if (entry.type === 'Directory') {
+                    entry.autodrain();
+                }
+                else {
+                    entry.pipe(fs.createWriteStream(entryPath));
+                }
+            })
+                .on('close', resolve)
+                .on('error', reject);
+        });
     }
     else {
         throw new Error("Unsupported package format. Only .tgz and .zip are supported.");
@@ -806,3 +831,39 @@ export function readValueSetsFromDir(extractedRoot) {
     }
     return map;
 }
+/**
+ * Read all SearchParameter resources from a package directory.
+ * Returns a map of base resource type → array of search parameter definitions.
+ */
+export function readSearchParametersFromDir(extractedRoot) {
+    const jsonFiles = findJsonFilesByPrefix(extractedRoot, 'SearchParameter-');
+    const map = new Map();
+    for (const file of jsonFiles) {
+        try {
+            const content = JSON.parse(fs.readFileSync(file, 'utf-8'));
+            if (content.resourceType !== 'SearchParameter')
+                continue;
+            if (!content.code || !content.type || !content.base?.length)
+                continue;
+            if (content.status === 'retired')
+                continue;
+            const param = {
+                code: content.code,
+                type: content.type,
+                base: content.base,
+            };
+            for (const baseType of param.base) {
+                const existing = map.get(baseType) || [];
+                // Avoid duplicates by code
+                if (!existing.some(p => p.code === param.code)) {
+                    existing.push(param);
+                    map.set(baseType, existing);
+                }
+            }
+        }
+        catch (err) {
+            log.debug(`Skipping invalid JSON while reading SearchParameters ${file}: ${err.message}`);
+        }
+    }
+    return map;
+}

package/out/src/main.js

@@ -58,6 +58,7 @@ function printUsage() {
     console.log("  --schema <format>        Generate schema files alongside outputs (supported: zod)");
     console.log("  --dicomweb               Generate DICOMweb helpers typed to ImagingStudy profiles in the IG");
     console.log("  --recursive              (update only) Recursively search subdirectories for lib/ folders");
+    console.log("  --force                  (update only) Force regeneration even if version and flags haven't changed");
     console.log("  --outDir <dir>           Output directory (alias for second positional argument)");
     console.log("  --fhir-version <ver>     FHIR version to target: r4, r4b, or r5 (auto-detected from package if omitted)");
     console.log("  --package <pkg[@version]>  Download FHIR package from registry and process it (latest if no version)");
@@ -234,6 +235,10 @@ export function parseCliArgs(argv) {
             out.flags.recursive = true;
             continue;
         }
+        if (arg === '--force') {
+            out.flags.force = true;
+            continue;
+        }
         if (arg === '--cache-dir') {
             const val = argv[i + 1];
             if (!val || val.startsWith('-'))
@@ -377,6 +382,7 @@ export async function run() {
         const result = await handleUpdateCommand({
             packageFilter: packageSpec || positionals[1] || undefined,
             recursive: !!generationFlags.recursive,
+            force: !!generationFlags.force,
             generationFlags,
             registry,
             downloadPackage,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "babelfhir-ts",
-  "version": "1.4.1",
+  "version": "1.4.3",
   "description": "BabelFHIR-TS: generate TypeScript interfaces, validators, and helper classes from FHIR R4/R4B/R5 StructureDefinitions (profiles) directly inside package archives.",
   "type": "module",
   "main": "out/src/main.js",