@softspark/ai-toolkit 2.7.2 → 2.8.0

package/CHANGELOG.md

@@ -7,6 +7,34 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## v2.8.0 — Security Hardening & GHAS Integration (2026-04-18)
+
+### Added
+- **`scripts/audit_skills.py --sarif`** — emits SARIF 2.1.0 JSON compatible with GitHub Advanced Security Code Scanning. Severity maps HIGH→error / WARN→warning / INFO→note. Enables the GitHub Security tab to ingest audit findings directly.
+- **`scripts/audit_skills.py --permissions`** — per-skill tool-permission report (human + `--json` forms). Aggregates skills by tool usage (e.g. "50 skills use Bash"), flags broad Bash+Write+Edit access, prints full skill/invocable/tools table. Security review can now answer "show me every skill that can Bash" in one command.
+- **Checksum pinning for URL-sourced rules and hooks** — `rule_sources.py` and `hook_sources.py` now persist `sha256` of the fetched payload in `sources.json`. Subsequent refreshes log `CHECKSUM CHANGED` when the upstream payload changes. Setting `AI_TOOLKIT_STRICT_PIN=1` turns the mismatch into a hard failure (exit 2) so CI can reject silent upstream tampering.
+- **`SECRET_PLACEHOLDER_PREFIXES`** allowlist in `audit_skills.py` — WARN-level hardcoded-secret patterns now skip values starting with `REPLACE_`, `CHANGEME_`, `CHANGE_ME`, `YOUR_`, `EXAMPLE_`, `PLACEHOLDER_`, `${`, `{{`, `$ENV_`, `$(`, `<`, `xxx`, `XXX`. Fewer false positives on docs and `.env.example` fixtures.
+
+### Changed
+- **npm publish workflow (`.github/workflows/publish.yml`)** now runs with `--provenance` and `id-token: write`. Published tarballs carry a cryptographic provenance attestation visible on npmjs.com and verifiable via `npm audit signatures`.
+- **`scripts/config_resolver.py:_extract_tarball`** passes `filter="data"` to `tarfile.extract` on Python 3.12+. Defense in depth on top of existing path-traversal, symlink, and absolute-path rejection. Future-proofs against the 3.14 default-filter change.
+- **`app/hooks/session-start.sh`** sanitises `VERSION_MSG` with `LC_ALL=C tr -d '"'"'"'\\`$'` before interpolating into `osascript` / `powershell.exe` notification commands. Closes a latent command-injection footgun.
+- **`scripts/install_steps/ai_tools.py`** and **`hooks.py`** — generator and merge-hooks `subprocess.run` calls now have `timeout=120`. A stuck generator produces a clear error instead of hanging `ai-toolkit install` indefinitely.
+- **`app/hooks/commit-quality.sh`** — extracted commit message via a small Python regex instead of fragile shell `grep -oE` chain. Handles commit messages containing mixed `"` and `'` correctly.
+- **`app/hooks/quality-check.sh`** — normalised `|| true` handling across all languages (Python ruff was previously the only one propagating exit status). All language checks are now consistently advisory on the Stop hook.
+- **`bin/ai-toolkit.js:handleAddRule`** — simplified HTTPS/HTTP detection (single `startsWith('https://')` after the `http://` reject).
+- **`package.json` description** shortened from 400+ to 241 characters — stops mid-sentence truncation in npm search. Surfaces the new SARIF + provenance differentiators.
+- **`package.json` `engines`** — removed non-standard `bats` entry (npm ignores unknown engines and warned on install). Bats requirement is documented in `CLAUDE.md` Commands section.
+
+---
+
+## v2.7.3 — Regenerate llms after Medplum Merge (2026-04-17)
+
+### Fixed
+- **`llms.txt` + `llms-full.txt` stale after PR #7 (Medplum/FHIR rules)** — contributor did not re-run `npm run generate:all` before merge, so the machine-readable catalogs did not list `kb/reference/medplum-docs-map.md`, and `kb/reference/language-rules.md` still advertised `13 languages / 68 rule files` instead of `14 languages / 73 rule files`. Validator passes regardless (it does not diff generated text), so the drift slipped past CI. Regenerated from source; added Medplum row to the languages table.
+
+---
+
 ## v2.7.2 — Doc & Model-ID Consistency (2026-04-17)
 
 ### Changed

package/README.md

@@ -10,11 +10,12 @@
 
 ---
 
-## What's New in v2.7.2
+## What's New in v2.8.0
 
-- **Centralized Claude model IDs** in `scripts/_common.py` (`DEFAULT_CLAUDE_MODELS` dict). Next Anthropic model bump touches one file instead of hunting through generators.
-- **`GEMINI.md` regenerated** to include 5 skills missed at v2.7.0 tag: `prompt-caching-patterns`, `json-mode-patterns`, `content-moderation-patterns`, `model-routing-patterns`, `/mcp-builder`.
-- **`manifest.json` skill count corrected** — `94 skills (31/31/32)` → `99 skills (32/31/36)` in both component and module descriptions.
+- **SARIF + permissions audit** — `audit_skills.py --sarif` emits SARIF 2.1.0 for GitHub Advanced Security Code Scanning; `--permissions` prints per-skill tool usage (e.g. "50 skills use Bash") and flags broad Bash+Write+Edit access.
+- **Signed npm provenance** — the publish workflow now runs with `--provenance`; published tarballs carry a cryptographic build-origin attestation verifiable via `npm audit signatures`.
+- **Checksum-pinned URL sources** — `sources.json` now persists `sha256` of every URL-sourced rule/hook and warns on upstream content change. `AI_TOOLKIT_STRICT_PIN=1` turns mismatches into a hard CI failure.
+- **Security hardening** — `tarfile.extract` uses `filter="data"` on Python 3.12+; `session-start.sh` sanitises `VERSION_MSG` before `osascript`/`powershell.exe`; install-time `subprocess.run` calls now time out at 120 s.
 
 See [CHANGELOG.md](CHANGELOG.md) for full history.
 

package/app/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "ai-toolkit",
   "description": "Professional-grade Claude Code toolkit with persona presets, skill security auditor, expanded lifecycle hooks, experimental opt-in plugin packs, benchmark harvesting, and multi-tool support.",
-  "version": "2.7.2",
+  "version": "2.8.0",
   "author": {
     "name": "SoftSpark",
     "url": "https://github.com/softspark"

package/app/hooks/commit-quality.sh

@@ -14,14 +14,17 @@ fi
 # Only check commands that contain "git commit"
 printf '%s' "$COMMAND" | grep -q 'git commit' || exit 0
 
-# Extract commit message from -m flag
-# Handles: git commit -m "msg", git commit -m 'msg', git commit -am "msg"
-MSG=$(printf '%s' "$COMMAND" | grep -oE '\-m\s+["'"'"']([^"'"'"']*)["'"'"']' | head -1 | sed "s/^-m[[:space:]]*[\"']//" | sed "s/[\"']$//")
-
-# Also handle heredoc-style: -m "$(cat <<'EOF' ... EOF )"
-if [ -z "$MSG" ]; then
-    MSG=$(printf '%s' "$COMMAND" | grep -oE '\-m\s+"[^"]*"' | head -1 | sed 's/^-m[[:space:]]*//' | tr -d '"')
-fi
+# Extract commit message from -m flag. Delegated to Python for correct
+# quote handling — the previous shell-regex approach broke on commit messages
+# containing both " and '.
+MSG=$(printf '%s' "$COMMAND" | python3 -c '
+import re, sys
+cmd = sys.stdin.read()
+# Match -m followed by a quoted string (either " or ").
+m = re.search(r"""-m\s+("((?:[^"\\]|\\.)*)"|'"'"'((?:[^'"'"'\\]|\\.)*)'"'"')""", cmd)
+if m:
+    print(m.group(2) if m.group(2) is not None else m.group(3))
+' 2>/dev/null)
 
 # No message found (might be --amend or interactive) — skip
 if [ -z "$MSG" ]; then

package/app/hooks/quality-check.sh

@@ -7,8 +7,12 @@
 # shellcheck source=_profile-check.sh
 source "$(dirname "$0")/_profile-check.sh"
 
+# All lint/typecheck invocations are advisory. They run on the Stop hook and
+# must not block Claude from returning a response, hence the trailing `|| true`.
+# The first 15 lines of output are surfaced to the user; further lines are
+# truncated to keep the context lean.
 if [ -f pyproject.toml ] || [ -f setup.py ]; then
-    ruff check . 2>&1 | head -15
+    ruff check . 2>&1 | head -15 || true
 elif [ -f package.json ] && [ -f tsconfig.json ]; then
     npx tsc --noEmit 2>&1 | head -15 || true
 elif [ -f composer.json ] && [ -f vendor/bin/phpstan ]; then

package/app/hooks/session-start.sh

@@ -14,13 +14,17 @@ TOOLKIT_DIR="$(npm root -g 2>/dev/null)/@softspark/ai-toolkit"
 VERSION_MSG=$(python3 "$TOOLKIT_DIR/scripts/version_check.py" 2>/dev/null)
 if [ -n "$VERSION_MSG" ]; then
     echo "$VERSION_MSG"
+    # Strip shell/AppleScript/PowerShell metacharacters before interpolating into
+    # notification commands. VERSION_MSG is version_check.py output which should
+    # be plain ASCII, but sanitize anyway as defense in depth.
+    VERSION_MSG_SAFE=$(printf '%s' "$VERSION_MSG" | LC_ALL=C tr -d '"'"'"'\\`$')
     # Desktop notification so user sees update before typing
     if command -v osascript >/dev/null 2>&1; then
-        osascript -e "display notification \"$VERSION_MSG\" with title \"ai-toolkit\"" 2>/dev/null &
+        osascript -e "display notification \"$VERSION_MSG_SAFE\" with title \"ai-toolkit\"" 2>/dev/null &
     elif command -v notify-send >/dev/null 2>&1; then
-        notify-send "ai-toolkit" "$VERSION_MSG" 2>/dev/null &
+        notify-send "ai-toolkit" "$VERSION_MSG_SAFE" 2>/dev/null &
     elif command -v powershell.exe >/dev/null 2>&1; then
-        powershell.exe -Command "[void](New-Object -ComObject WScript.Shell).Popup('$VERSION_MSG',5,'ai-toolkit',64)" 2>/dev/null &
+        powershell.exe -Command "[void](New-Object -ComObject WScript.Shell).Popup('$VERSION_MSG_SAFE',5,'ai-toolkit',64)" 2>/dev/null &
     fi
 fi
 

package/app/rules/medplum/coding-style.md

@@ -0,0 +1,56 @@
+---
+language: medplum
+category: coding-style
+version: "1.0.0"
+---
+
+# Medplum / FHIR Coding Style
+
+## Resource Structure
+- Every FHIR object must include `resourceType` as first field.
+- Use PascalCase for resource types (`Patient`, `ServiceRequest`), camelCase for fields (`birthDate`, `valueQuantity`).
+- Never hardcode resource IDs. Let the server assign them on create.
+- Include `meta.profile` when creating resources that must conform to a StructureDefinition.
+
+## References
+- Use `createReference(resource)` from `@medplum/core` to build Reference objects.
+- Always include `display` on references for human readability.
+- Use `getReferenceString(resource)` for comparisons and logging — returns `ResourceType/id`.
+- Use `parseReference(ref)` to extract resourceType and id from a reference string.
+- Never concatenate strings to build references manually.
+
+## CodeableConcepts & Coding
+- Always include `system`, `code`, and `display` in every Coding element.
+- Use standard terminology URIs: `http://loinc.org`, `http://snomed.info/sct`, `http://hl7.org/fhir/sid/icd-10-cm`.
+- Use `getCodeBySystem(cc, system)` to find codes; `setCodeBySystem(cc, system, code)` to set them.
+- Prefer `CodeableConcept` over plain `Coding` when the FHIR spec allows both — it supports multiple codings and free text.
+
+## Identifiers
+- Use `identifier` arrays with `system` + `value` for external IDs (MRN, NPI, SSN).
+- Use `getIdentifier(resource, system)` and `setIdentifier(resource, system, value)` helpers.
+- Identifier systems must be absolute URIs (e.g., `http://hl7.org/fhir/sid/us-npi`).
+- Use `createResourceIfNoneExist(resource, 'identifier=system|value')` for idempotent creates.
+
+## Extensions
+- Use the `extension` array with `url` and typed `value[x]` fields.
+- Prefer official HL7/US Core extensions over custom ones where they exist.
+- Use `getExtension(resource, url)` and `getExtensionValue(resource, url)` helpers.
+
+## Bundles
+- Use `urn:uuid:<uuid>` for internal references between entries in a transaction Bundle.
+- Every Bundle entry must have `request.method` (`POST`, `PUT`, `DELETE`) and `request.url`.
+- Include `fullUrl` on entries that are referenced by other entries.
+- Use conditional references (`Practitioner?identifier=npi|123`) for existing resources.
+
+## HIPAA-Aware Coding
+- Identifiers like SSN, MRN, and insurance IDs are PHI — never log raw values to console or external services.
+- Use a safe logging utility (e.g., `safeLog()`) for any output that might contain patient data. Never `console.log` raw FHIR resources.
+- Reference `display` strings may contain patient names — treat as PHI in logs and error messages.
+- Every new data access path or admin operation must include corresponding `AuditEvent` creation. No exceptions.
+- When audit logging fails (Medplum unreachable), write to a fallback store — audit events must never be silently dropped.
+- See `security.md` rules for full HIPAA, access policy, and PHI handling requirements.
+
+## Formatting
+- Use `formatHumanName()`, `formatAddress()`, `formatDate()`, `formatQuantity()` for display strings.
+- Use `getDisplayString(resource)` as a universal fallback for any resource's display name.
+- Never manually concatenate name parts — FHIR names have `given[]`, `family`, `prefix[]`, `suffix[]`.

package/app/rules/medplum/frameworks.md

@@ -0,0 +1,51 @@
+---
+language: medplum
+category: frameworks
+version: "1.0.0"
+---
+
+# Medplum Frameworks
+
+## @medplum/core — SDK Client
+- Use `MedplumClient` for all FHIR operations. Never use raw `fetch` against Medplum endpoints.
+- Use `medplum.createResource()`, `readResource()`, `updateResource()`, `deleteResource()` for CRUD.
+- Use `medplum.searchResources()` for typed arrays. Use `medplum.searchOne()` when expecting a single result.
+- Use `medplum.executeBatch()` for transaction Bundles — groups multiple operations atomically.
+- Use `medplum.upsertResource(resource, query)` for atomic create-or-update.
+- Use `medplum.createResourceIfNoneExist(resource, query)` for idempotent creation.
+- Configure `autoBatchTime` on MedplumClient to auto-batch concurrent GET requests. Use `Promise.all()` instead of sequential `await` to benefit from batching.
+
+## @medplum/fhirtypes — Type Safety
+- Import FHIR types directly: `import { Patient, Observation } from '@medplum/fhirtypes'`.
+- Use TypeScript types for all FHIR resources — never use `any` for resource data.
+- Cast `event.input` in bot handlers: `const patient = event.input as Patient`.
+- Use optional chaining for nested FHIR fields: `patient.name?.[0]?.given?.[0]`.
+
+## @medplum/react — UI Components
+- Wrap app with `<MedplumProvider client={medplum}>` at the root.
+- Use `useMedplum()` hook to access the MedplumClient instance in components.
+- Use `useMedplumContext()` for client + profile + loading state together.
+- Use `<ResourceForm>` for auto-generated CRUD forms, `<ResourceTable>` for display.
+- Use `<SearchControl>` for searchable/filterable resource lists.
+- Use `<QuestionnaireForm>` to render FHIR Questionnaires and capture responses.
+- Use `useSubscription(criteria)` for real-time WebSocket data in React components.
+- Requires Mantine 7+ and PostCSS with Mantine preset. Import `@mantine/core/styles.css`.
+
+## Bot Development
+- Export a single `handler` function: `export async function handler(medplum: MedplumClient, event: BotEvent)`.
+- Access trigger resource via `event.input`. Access secrets via `event.secrets`.
+- Use `event.contentType` to determine input format (`application/fhir+json`, `text/plain`, `x-application/hl7-v2+er7`).
+- Deploy bots via CLI for CI/CD: `medplum bot deploy <bot-name>`.
+- Apply AccessPolicies to bots — restrict to minimum required resource types.
+- Use Subscriptions with `channel.type: 'rest-hook'` and `channel.endpoint: 'Bot/<ID>'` for event-driven execution.
+
+## GraphQL
+- Append `List` to resource type for searches: `PatientList(name: "Eve")`.
+- Use snake_case for search parameters in GraphQL (not kebab-case): `address_city`, not `address-city`.
+- Use inline fragments for reference resolution: `... on Observation { valueQuantity { value } }`.
+- Use `_reference` for reverse lookups: `EncounterList(_reference: patient)`.
+
+## CLI (@medplum/cli)
+- Use `medplum login` for auth, `medplum get`/`medplum post` for FHIR operations.
+- Use `medplum bot deploy` for bot deployment in CI/CD pipelines.
+- Use `medplum bulk export` for bulk data operations.

package/app/rules/medplum/patterns.md

@@ -0,0 +1,61 @@
+---
+language: medplum
+category: patterns
+version: "1.0.0"
+---
+
+# Medplum / FHIR Patterns
+
+## Bundle Transactions
+- Use `type: 'transaction'` for atomic multi-resource operations — all-or-nothing.
+- Use `type: 'batch'` when operations are independent and partial failure is acceptable.
+- Use `urn:uuid:<uuid>` in `fullUrl` for forward references between entries.
+- Reference other entries via `{ reference: 'urn:uuid:<uuid>' }`.
+- Use `ifNoneExist` on POST entries for conditional creation (idempotent).
+- Use `ifMatch: 'W/"versionId"'` on PUT entries for optimistic concurrency.
+- Use conditional references for existing resources: `Practitioner?identifier=http://hl7.org/fhir/sid/us-npi|123`.
+- For large bundles (>50MB), use `Prefer: respond-async` header.
+
+## Search Patterns
+- Use `_include=ResourceType:searchParam` to fetch referenced resources in one call.
+- Use `_revinclude=ResourceType:searchParam` to fetch resources referencing your results.
+- Use `:iterate` modifier for multi-hop traversal: `_include:iterate=Patient:general-practitioner`.
+- Use `_count` + `_offset` for pagination; use `searchResourcePages()` for async iteration.
+- Use `:contains` modifier for substring search on string params: `name:contains=eve`.
+- Use `:not` modifier to exclude: `status:not=completed`.
+- Use comma-separated values for OR: `status=active,on-hold`.
+- Use multiple parameters for AND: `name=Simpson&birthdate=1940-03-29`.
+- Prefer `searchResources()` over `search()` — returns typed array, not raw Bundle.
+
+## Subscription & Bot Workflows
+- Create a `Subscription` resource with `criteria` (FHIR search query) and `channel.type: 'rest-hook'`.
+- Point `channel.endpoint` to `Bot/<BOT_ID>` for automated processing.
+- Use `subscribeToCriteria()` client-side for WebSocket real-time updates.
+- Never subscribe to `AuditEvent` changes — prevents notification spirals.
+- Use cron-based bots for scheduled tasks (e.g., daily reports, batch processing).
+
+## Access Policies
+- Define `AccessPolicy.resource[]` with `resourceType` and optional `criteria`, `readonly`, `hiddenFields`, `readonlyFields`.
+- Use `%profile` variable to scope data to the current user: `Observation?performer=%profile`.
+- Use `%patient` variable for patient-portal access: `Observation?subject=%patient`.
+- Use compartment-based access for patient-scoped isolation.
+- Use `writeConstraint` with FHIRPath for state machine enforcement (e.g., prevent status rollback).
+- Apply least privilege: start with no access, add specific resource types.
+
+## Conditional Operations
+- Use `createResourceIfNoneExist(resource, query)` for idempotent creates keyed on identifier.
+- Use `upsertResource(resource, query)` for atomic create-or-update in a single request.
+- Use `If-None-Exist` header on POST for server-side conditional creation.
+
+## Patient Deduplication
+- Match on `identifier` systems (MRN, SSN, insurance ID) for deterministic matching.
+- Use probabilistic matching on name + birthdate + address for fuzzy matches.
+- Use Patient `link` field with `type: 'replaced-by'` for merge workflows.
+- Prefer `createResourceIfNoneExist()` at ingestion to prevent duplicates.
+
+## Questionnaire Workflows
+- Create `Questionnaire` resources for form definitions. Use `linkId` for question identification.
+- Use `QuestionnaireResponse` for captured answers. Link to Questionnaire via `questionnaire` field.
+- Use `getQuestionnaireAnswers(response)` to extract answers as a map keyed by `linkId`.
+- Automate post-submission processing with a Bot subscribed to `QuestionnaireResponse` creation.
+- Use SDC (Structured Data Capture) extensions for advanced rendering and extraction.

package/app/rules/medplum/security.md

@@ -0,0 +1,58 @@
+---
+language: medplum
+category: security
+version: "1.0.0"
+---
+
+# Medplum / FHIR Security
+
+## Authentication
+- Use client credentials flow (`startClientLogin`) for backend services and integrations.
+- Use authorization code flow (`startLogin` + `processCode`) for user-facing web apps.
+- Never store tokens in `localStorage` in production — use secure HTTP-only cookies or server-side sessions.
+- Use `refreshIfExpired()` before critical operations. Set `gracePeriod` to refresh proactively.
+- Use `setBasicAuth(clientId, clientSecret)` only for server-side code, never in browser.
+- Rotate client secrets via `$rotate-client-secret` operation periodically.
+
+## Access Policies
+- Every non-admin user must have an AccessPolicy. Never leave users with default full access.
+- Scope to specific resource types: list only the types the user needs.
+- Use `readonly: true` or explicit `interaction` arrays to restrict write access.
+- Use `criteria` with FHIR search syntax to filter visible resources (e.g., `Patient?organization=Organization/123`).
+- Use `hiddenFields` to prevent sensitive fields from being returned (e.g., SSN).
+- Use `readonlyFields` to allow viewing but prevent modification of specific fields.
+- Use `writeConstraint` FHIRPath expressions for business rules (e.g., prevent status rollback on finalized resources).
+- Test access policies by logging in as a test user with the policy applied.
+
+## HIPAA & Audit Logging
+- Medplum automatically creates AuditEvent resources for all FHIR operations.
+- Never log PHI (patient names, identifiers, health data) to application console or external services.
+- Use structured audit references: reference the Patient and the accessing Practitioner in audit records.
+- For custom audit trails, create AuditEvent resources with `type`, `agent`, `entity`, and `outcome`.
+- Ensure audit events are never silently dropped — if Medplum is unreachable, write to a fallback store.
+
+## PHI Handling
+- Never include PHI in URLs, query parameters, or HTTP headers.
+- Use POST-based search for queries containing sensitive criteria.
+- Use `Binary` resources with `securityContext` for sensitive file attachments.
+- Encrypt data at rest and in transit (TLS 1.2+). Medplum hosted handles this automatically.
+- Apply data retention policies — use `$expunge` operation for permanent deletion when required.
+
+## SMART Scopes
+- Use `patient/*.read` style scopes for patient-facing apps.
+- Use `user/*.read` style scopes for practitioner-facing apps.
+- Validate scopes server-side on every request — do not trust client-side scope claims.
+- Use `launch/patient` context for apps launched within a patient context.
+- Define minimal scopes: request only the resource types and operations needed.
+
+## Multi-Tenant Isolation
+- Use Medplum Projects for tenant isolation — each project is a separate data silo.
+- Never share AccessPolicies across projects/tenants.
+- Validate `meta.project` on operations when building multi-tenant middleware.
+- Use separate ClientApplications per tenant for backend integrations.
+
+## Secrets Management
+- Use Bot secrets (`event.secrets`) for API keys, connection strings, and credentials.
+- Never hardcode secrets in bot source code or resource data.
+- Use Medplum project-level secrets storage — accessible only by project admins.
+- Rotate secrets on a regular schedule and after any suspected compromise.

package/app/rules/medplum/testing.md

@@ -0,0 +1,56 @@
+---
+language: medplum
+category: testing
+version: "1.0.0"
+---
+
+# Medplum / FHIR Testing
+
+## MockClient
+- Use `MockClient` from `@medplum/mock` for unit tests — it simulates the full MedplumClient API in memory.
+- Pre-populate test data with `mockClient.createResource()` before running test assertions.
+- MockClient supports `search`, `searchResources`, `searchOne`, `readResource`, `updateResource`, `deleteResource`.
+- MockClient does not require network access — tests run fast and offline.
+- Use `new MockClient()` per test to ensure isolation between test cases.
+
+## Bot Unit Testing
+- Test the handler function directly: `await handler(mockClient, mockEvent)`.
+- Create mock `BotEvent` objects with `input`, `contentType`, `secrets`, and `bot` fields.
+- Verify resource creation: call `mockClient.searchResources()` after handler execution.
+- Test error paths: pass invalid input resources and assert the handler throws or returns errors.
+- Test different content types: `application/fhir+json`, `text/plain`, `x-application/hl7-v2+er7`.
+- Mock `event.secrets` for bots that depend on external API keys.
+
+## Resource Validation
+- Use `validateResource(resource)` from `@medplum/core` to check resources against StructureDefinitions.
+- Test that required fields produce `OperationOutcome` errors when missing.
+- Test custom profiles: create a `StructureDefinition` resource, then validate resources against it.
+- Use the `$validate` operation for server-side validation in integration tests.
+- Test the Data Absent Reason extension when required fields may legitimately be empty.
+
+## Search Testing
+- Test search parameter behavior: exact match vs prefix match vs substring (`name`, `name:exact`, `name:contains`).
+- Verify `_include` returns related resources in the Bundle.
+- Test pagination with `_count` and `_offset` parameters.
+- Test token search with and without system namespace: `identifier=value` vs `identifier=system|value`.
+- Test date range searches with comparison prefixes: `ge`, `le`, `gt`, `lt`.
+
+## Integration Testing
+- Use Medplum Docker image (`medplum/medplum-server`) for local integration tests.
+- Test full workflows end-to-end: create patient → create observation → search → verify.
+- Verify Bundle transactions are atomic: intentionally fail one entry and confirm rollback.
+- Test access policies by authenticating as users with different policies.
+- Test Subscription triggers: create a Subscription, modify a matching resource, verify Bot execution.
+
+## Test Data Factories
+- Create typed factory functions: `createTestPatient(overrides?)`, `createTestObservation(overrides?)`.
+- Use realistic but synthetic data — never use real patient data in tests.
+- Include only minimal required fields by default. Let tests add specific fields via overrides.
+- Use `generateId()` from `@medplum/core` for unique test identifiers.
+- Use standard test identifier systems: `http://example.com/test-mrn` to avoid collision with real systems.
+
+## Assertions
+- Assert on `OperationOutcome` for error responses: check `issue[].severity`, `issue[].code`, `issue[].expression`.
+- Use `isOk(outcome)` and `isNotFound(outcome)` from `@medplum/core` for status checks.
+- Use `deepEquals(a, b)` for resource comparison (ignores `meta.versionId` and `meta.lastUpdated`).
+- Assert reference integrity: verify `subject.reference` matches expected `Patient/id` format.

package/bin/ai-toolkit.js

@@ -368,11 +368,11 @@ function handleAddRule(args) {
     process.exit(1);
   }
   // Pass URLs through directly (don't resolve as filesystem path)
-  const isUrl = ruleFile.startsWith('https://') || ruleFile.startsWith('http://');
   if (ruleFile.startsWith('http://')) {
     console.error('Error: only HTTPS URLs are supported. Use https:// for security.');
     process.exit(1);
   }
+  const isUrl = ruleFile.startsWith('https://');
   const absRuleFile = isUrl ? ruleFile : path.resolve(CWD, ruleFile);
   const ruleName = args[1];
   run(scriptPath('add_rule.py'), ruleName ? [absRuleFile, ruleName] : [absRuleFile]);

package/kb/reference/language-rules.md

@@ -6,14 +6,14 @@ tags: [rules, languages, coding-style, testing, patterns, security]
 version: "1.0.0"
 created: "2026-04-07"
 last_updated: "2026-04-07"
-description: "Reference for the language-specific rules system: 13 languages, 5 categories per language, auto-detection."
+description: "Reference for the language-specific rules system: 14 languages, 5 categories per language, auto-detection."
 ---
 
 # Language Rules System
 
 ## Overview
 
-ai-toolkit ships language-specific rule files covering 13 programming languages plus a common set (see README.md for current count). Rules are plain Markdown files injected into `CLAUDE.md` via `ai-toolkit install --local`. They provide coding-style, testing, patterns, frameworks, and security guidance specific to each language.
+ai-toolkit ships language-specific rule files covering 14 languages/platforms plus a common set (see README.md for current count). Rules are plain Markdown files injected into `CLAUDE.md` via `ai-toolkit install --local`. They provide coding-style, testing, patterns, frameworks, and security guidance specific to each language.
 
 Rules are distinct from skills: rules are injected as static text into `CLAUDE.md` and are always visible to Claude, whereas skills are loaded contextually by agents.
 
@@ -48,10 +48,11 @@ app/rules/
 ├── csharp/
 ├── php/
 ├── cpp/
-└── ruby/
+├── ruby/
+└── medplum/
 ```
 
-**Total: 13 directories × 5 files each + 3 standalone = 68 rule files** (see README.md for canonical count)
+**Total: 14 directories × 5 files each + 3 standalone = 73 rule files** (see README.md for canonical count)
 
 ## Supported Languages
 
@@ -70,6 +71,7 @@ app/rules/
 | PHP | `rules/php/` | `composer.json` |
 | C++ | `rules/cpp/` | `CMakeLists.txt`, `Makefile`, `*.cpp` |
 | Ruby | `rules/ruby/` | `Gemfile`, `*.gemspec` |
+| Medplum | `rules/medplum/` | `medplum.config.mts`, `medplum.config.ts` |
 
 ## Rule Categories
 
@@ -107,6 +109,7 @@ Scans for configuration files defined in each module's `auto_detect` list in `ma
 10. `Package.swift` → Swift
 11. `*.csproj` or `*.sln` → C#
 12. `CMakeLists.txt` or `Makefile` → C++
+13. `medplum.config.mts` or `medplum.config.ts` → Medplum
 
 ### Phase 2: Source file extensions (actual code presence)
 
@@ -163,6 +166,7 @@ Language rules are tracked as modules in `manifest.json`:
 | `rules-php` | PHP-specific rules |
 | `rules-cpp` | C++-specific rules |
 | `rules-ruby` | Ruby-specific rules |
+| `rules-medplum` | Medplum/FHIR healthcare platform rules |
 
 ## Rules vs Skills