plumb-fhir 0.6.0

package/CHANGELOG.md

@@ -0,0 +1,130 @@
+# Changelog
+
+## 0.6.0 (2026-10-05)
+
+The first published release; it includes everything in 0.1.0 to 0.5.0, which were not published.
+
+Project config as code: `push` converges what a project admin can write.
+
+- **`project`** in the config declares settings, secrets, AccessPolicies,
+  default access policies and clients, typed with `@medplum/fhirtypes`. An
+  environment's `settings` merge over `project.settings`. An unknown policy
+  key, duplicate names, a setting that is not a string, boolean or number,
+  and a super-admin field (`strictMode`, `features`, `link`,
+  `systemSetting`) are config errors.
+- **`push` runs a `project` step** once the profile gate has passed. It plans
+  each AccessPolicy and client by a `meta.tag` with its config key, updates
+  it in place, and writes the Project's settings, secrets, `defaultProfile`
+  and `defaultAccessPolicies` in one update. A second push with no config
+  change writes nothing.
+- **`--adopt`** tags and converges an untagged policy or client with a key's
+  name; without it, one stops the plan. **`--prune`** deletes a tagged one
+  whose key left the config.
+- **Secrets** come from environment variables (`{ env }`) or must already
+  exist (`true`); no plan, `--json` output or error holds a value. A created
+  client's id is printed, never its secret.
+- **`push --check`** plans without installing or writing anything, and exits
+  1 when `push` would change something, naming what drifted.
+- **Lockdown warnings:** a writable `*` entry, an admin client with no
+  policy, and a policy other than push's own that writes
+  StructureDefinition.
+- `strictMode` and `features` are reported, never written. A linked
+  project's resources are never planned.
+- **Breaking:** the checker bot's identifier system is now
+  `https://www.npmjs.com/package/plumb-fhir`, as is Plumb's tag system, so a
+  checker installed by 0.5 is installed again.
+
+## 0.5.0 (not published)
+
+SUSHI in `generate`: one command builds FSH and types it.
+
+- **`fsh`** in the config names the folder holding `sushi-config.yaml`, in
+  place of `local`. Setting both is a config error, as is a folder with no
+  `sushi-config.yaml`.
+- **`generate` runs the project's own SUSHI** (`fsh-sushi` 3 or later) with
+  `--snapshot`, as a first `sushi` step. Its errors stop `generate`, with
+  their FSH file and line; its warnings are listed under the step. SUSHI
+  missing or too old exits 2, naming the install command.
+- **`generate --check`** rebuilds the FSH into a temporary folder and fails
+  when the committed `fsh-generated/resources` differs from it, file by file,
+  as well as when the types do. The project is not touched.
+- **Version warnings:** the `sushi` step warns when `sushi-config.yaml`
+  depends on a package at a version `igs` does not select, and `load` warns
+  (`base-version-mismatch`) when a local profile's pinned parent version
+  differs from the one the config provides.
+
+## 0.4.0 (not published)
+
+Typed reads: reads that return the profile type once its content is checked.
+
+- **`_reads.ts`**, generated into `out`, lists the paths each selected
+  profile's type requires beyond `@medplum/fhirtypes`, for the presence check
+  typed reads run.
+- **`isProfiled`, `asProfiled` and `pickProfiled`**, generated into `out`,
+  check a resource's stamp and what its type requires, offline, and narrow it
+  to the profile type; a failure throws a **`ProfileReadError`** naming the
+  records and paths, with the records that passed in a non-enumerable
+  `passed`.
+- **`readProfiled` and `searchProfiled`** read from Medplum and return the
+  profile type once checked. The search filters on `_profile` (the profile and
+  any selected child), refuses `_elements`, `_fields`, `_summary`, `_include`
+  and `_revinclude` before any request, and fails as a whole when one result
+  does, with the rest in `passed`.
+- A choice narrowed to `Reference` keeps the base element's targets instead of
+  widening them to any resource.
+
+## 0.3.0 (not published)
+
+Routing: each write held to the profile its content selects.
+
+- **`route(resource)`**, generated into `out`, returns the selected profile a
+  resource's content selects, preferring a child over its parent, and throws
+  a `RoutingError` naming what would select each candidate rather than
+  guess.
+- **`createProfiled` and `updateProfiled`** route, stamp the type's
+  `defaultProfile` plus the routed profile, and write; `{ profile }` chooses
+  one, typed, and `{ profile: false }` writes no stamp.
+- **`routes`** in the config adds rows for profiles keyed on a value set, or
+  `false` to take one out; **`defaultProfile`** names the defaults stamped
+  with each write. `generate` warns for profiles one resource could match.
+
+## 0.2.0 (not published)
+
+The conformance check: what stored data would fail a profile, before it loads.
+
+- **`environments`** in `plumb.config.ts` name a Medplum project and the
+  environment variables holding its client credentials.
+- **`plumb validate --env <env>`** counts, per profile, the stored resources
+  that would fail and why, with Plumb's checker bot inside the project, so
+  patient data never leaves Medplum. It reports unstamped resources, silent
+  stamps, shadowed profiles, and readable against stored counts; failing ids
+  go only to a gitignored file. `--resume` continues an interrupted run.
+- **`plumb push --env <env>`** installs the checker, then loads the selected
+  profiles and their dependencies, refusing while any stored resource would
+  fail them, and re-checks once they are loaded. `--dry-run` stops after the
+  gate. Strict mode is reported, never set.
+
+## 0.1.0 (not published)
+
+The first release: profile-aware types for Medplum.
+
+- **`plumb generate`** fetches the IG packages `plumb.config.ts` names from
+  the FHIR package registry into `~/.fhir/packages`, locks each one's version
+  and hash in `plumb.lock`, and generates a TypeScript file per profile that
+  narrows `@medplum/fhirtypes`: required fields at every depth, prohibited
+  fields, choice types, fixed and pattern values, reference targets, slices
+  with typed builders and readers, extension types shared across profiles,
+  and literal unions for required bindings whose value sets can be listed
+  offline.
+- **`plumb generate --check`** compares with the committed output byte for
+  byte, writes nothing to the project, and names the cause of each
+  difference; for CI.
+- **`validateProfiled`** runs Medplum's validator against a selected profile,
+  offline, for tests.
+- Profiles by canonical URL, or `name/*` for every resource profile in an IG;
+  local StructureDefinition JSON, such as SUSHI's output; `bindings.maxCodes`.
+- Supports `@medplum/*` 5.1.0 and later, TypeScript 5.0 and later, and Node
+  `^22.18.0 || >=24.2.0`.
+
+See the README's known limits for what the types leave to `validateProfiled`
+and the server.

package/LICENSE.txt

@@ -0,0 +1,176 @@
+                              Apache License
+                        Version 2.0, January 2004
+                     http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+   "License" shall mean the terms and conditions for use, reproduction,
+   and distribution as defined by Sections 1 through 9 of this document.
+
+   "Licensor" shall mean the copyright owner or entity authorized by
+   the copyright owner that is granting the License.
+
+   "Legal Entity" shall mean the union of the acting entity and all
+   other entities that control, are controlled by, or are under common
+   control with that entity. For the purposes of this definition,
+   "control" means (i) the power, direct or indirect, to cause the
+   direction or management of such entity, whether by contract or
+   otherwise, or (ii) ownership of fifty percent (50%) or more of the
+   outstanding shares, or (iii) beneficial ownership of such entity.
+
+   "You" (or "Your") shall mean an individual or Legal Entity
+   exercising permissions granted by this License.
+
+   "Source" form shall mean the preferred form for making modifications,
+   including but not limited to software source code, documentation
+   source, and configuration files.
+
+   "Object" form shall mean any form resulting from mechanical
+   transformation or translation of a Source form, including but
+   not limited to compiled object code, generated documentation,
+   and conversions to other media types.
+
+   "Work" shall mean the work of authorship, whether in Source or
+   Object form, made available under the License, as indicated by a
+   copyright notice that is included in or attached to the work
+   (an example is provided in the Appendix below).
+
+   "Derivative Works" shall mean any work, whether in Source or Object
+   form, that is based on (or derived from) the Work and for which the
+   editorial revisions, annotations, elaborations, or other modifications
+   represent, as a whole, an original work of authorship. For the purposes
+   of this License, Derivative Works shall not include works that remain
+   separable from, or merely link (or bind by name) to the interfaces of,
+   the Work and Derivative Works thereof.
+
+   "Contribution" shall mean any work of authorship, including
+   the original version of the Work and any modifications or additions
+   to that Work or Derivative Works thereof, that is intentionally
+   submitted to Licensor for inclusion in the Work by the copyright owner
+   or by an individual or Legal Entity authorized to submit on behalf of
+   the copyright owner. For the purposes of this definition, "submitted"
+   means any form of electronic, verbal, or written communication sent
+   to the Licensor or its representatives, including but not limited to
+   communication on electronic mailing lists, source code control systems,
+   and issue tracking systems that are managed by, or on behalf of, the
+   Licensor for the purpose of discussing and improving the Work, but
+   excluding communication that is conspicuously marked or otherwise
+   designated in writing by the copyright owner as "Not a Contribution."
+
+   "Contributor" shall mean Licensor and any individual or Legal Entity
+   on behalf of whom a Contribution has been received by Licensor and
+   subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of
+   this License, each Contributor hereby grants to You a perpetual,
+   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   copyright license to reproduce, prepare Derivative Works of,
+   publicly display, publicly perform, sublicense, and distribute the
+   Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of
+   this License, each Contributor hereby grants to You a perpetual,
+   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   (except as stated in this section) patent license to make, have made,
+   use, offer to sell, sell, import, and otherwise transfer the Work,
+   where such license applies only to those patent claims licensable
+   by such Contributor that are necessarily infringed by their
+   Contribution(s) alone or by combination of their Contribution(s)
+   with the Work to which such Contribution(s) was submitted. If You
+   institute patent litigation against any entity (including a
+   cross-claim or counterclaim in a lawsuit) alleging that the Work
+   or a Contribution incorporated within the Work constitutes direct
+   or contributory patent infringement, then any patent licenses
+   granted to You under this License for that Work shall terminate
+   as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the
+   Work or Derivative Works thereof in any medium, with or without
+   modifications, and in Source or Object form, provided that You
+   meet the following conditions:
+
+   (a) You must give any other recipients of the Work or
+         Derivative Works a copy of this License; and
+
+   (b) You must cause any modified files to carry prominent notices
+         stating that You changed the files; and
+
+   (c) You must retain, in the Source form of any Derivative Works
+         that You distribute, all copyright, patent, trademark, and
+         attribution notices from the Source form of the Work,
+         excluding those notices that do not pertain to any part of
+         the Derivative Works; and
+
+   (d) If the Work includes a "NOTICE" text file as part of its
+         distribution, then any Derivative Works that You distribute must
+         include a readable copy of the attribution notices contained
+         within such NOTICE file, excluding those notices that do not
+         pertain to any part of the Derivative Works, in at least one
+         of the following places: within a NOTICE text file distributed
+         as part of the Derivative Works; within the Source form or
+         documentation, if provided along with the Derivative Works; or,
+         within a display generated by the Derivative Works, if and
+         wherever such third-party notices normally appear. The contents
+         of the NOTICE file are for informational purposes only and
+         do not modify the License. You may add Your own attribution
+         notices within Derivative Works that You distribute, alongside
+         or as an addendum to the NOTICE text from the Work, provided
+         that such additional attribution notices cannot be construed
+         as modifying the License.
+
+   You may add Your own copyright statement to Your modifications and
+   may provide additional or different license terms and conditions
+   for use, reproduction, or distribution of Your modifications, or
+   for any such Derivative Works as a whole, provided Your use,
+   reproduction, and distribution of the Work otherwise complies with
+   the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise,
+   any Contribution intentionally submitted for inclusion in the Work
+   by You to the Licensor shall be under the terms and conditions of
+   this License, without any additional terms or conditions.
+   Notwithstanding the above, nothing herein shall supersede or modify
+   the terms of any separate license agreement you may have executed
+   with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade
+   names, trademarks, service marks, or product names of the Licensor,
+   except as required for reasonable and customary use in describing the
+   origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or
+   agreed to in writing, Licensor provides the Work (and each
+   Contributor provides its Contributions) on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+   implied, including, without limitation, any warranties or conditions
+   of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+   PARTICULAR PURPOSE. You are solely responsible for determining the
+   appropriateness of using or redistributing the Work and assume any
+   risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory,
+   whether in tort (including negligence), contract, or otherwise,
+   unless required by applicable law (such as deliberate and grossly
+   negligent acts) or agreed to in writing, shall any Contributor be
+   liable to You for damages, including any direct, indirect, special,
+   incidental, or consequential damages of any character arising as a
+   result of this License or out of the use or inability to use the
+   Work (including but not limited to damages for loss of goodwill,
+   work stoppage, computer failure or malfunction, or any and all
+   other commercial damages or losses), even if such Contributor
+   has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing
+   the Work or Derivative Works thereof, You may choose to offer,
+   and charge a fee for, acceptance of support, warranty, indemnity,
+   or other liability obligations and/or rights consistent with this
+   License. However, in accepting such obligations, You may act only
+   on Your own behalf and on Your sole responsibility, not on behalf
+   of any other Contributor, and only if You agree to indemnify,
+   defend, and hold each Contributor harmless for any liability
+   incurred by, or claims asserted against, such Contributor by reason
+   of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS

package/NOTICE

@@ -0,0 +1,20 @@
+Plumb
+Copyright 2026 Balance Hormone Center and Plumb contributors
+
+This product includes software developed by Balance Hormone Center and
+other contributors under the Apache License, Version 2.0.
+
+Plumb is built on Medplum (https://www.medplum.com). "Medplum" is a
+registered trademark of Orangebot, Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at:
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.