@konfig.ts/core 0.0.2 → 0.0.4

package/README.md

@@ -1,181 +1,82 @@
 # @konfig.ts/core
 
-The Kubernetes-agnostic primitives that the rest of konfig.ts builds on:
-the `Manifest<A>` carrier, the `Dep.*` kinds that drive compile-time
-dependency tracking, a stable YAML serializer, structural diff, an Effect
-`Schema` boundary helper, and the `Helm.release` integration.
+The Kubernetes-agnostic primitives every other konfig.ts package builds on: the
+`Manifest<A>` carrier, the `Dep.*` kinds that drive compile-time dependency
+tracking, the `Module` factories, stable YAML, structural diff, a Helm
+integration with digest verification, and the `render` entrypoint.
 
-Higher-level surfaces — workloads, services, env contracts, ArgoCD
-Application aggregation — live in `@konfig.ts/k8s`, `@konfig.ts/env`,
-and `@konfig.ts/argocd`.
+Most projects reach for the higher-level packages ([k8s](../k8s), [env](../env),
+[argocd](../argocd)) and touch core directly only for `Helm.release`, `Dep.*`,
+and `Module`.
 
-## `Manifest<A>` — the carrier
+## Install
 
-A `Manifest<A>` is a thunk from a `RenderContext` to an Effect that
-produces an `A`:
-
-```ts
-interface Manifest<A> {
-  readonly render: (
-    ctx: RenderContext
-  ) => Effect.Effect<A, AnyRenderError, RenderServices>
-}
+```bash
+bun add @konfig.ts/core
 ```
 
-`RenderServices` is `FileSystem | Path | ChildProcessSpawner | Scope`.
-Errors are a tagged union: `RenderError`, `EmbedYamlReadError`,
-`BoundaryDecodeError`, `HelmVersionTooLow`, `HelmRenderError`,
-`HelmDigestMismatch`, `CrdExtractError`.
-
-Constructors:
-
-| Op                                   | Behaviour                                      |
-| ------------------------------------ | ---------------------------------------------- |
-| `Manifest.make(run)`                 | Lift a `ctx → A \| Effect<A>` into a Manifest. |
-| `Manifest.combine({ a, b })`         | Render `a` and `b` concurrently into a tuple.  |
-| `Manifest.concat(...ms)`             | Flatten an array of Manifests into one.        |
-| `Manifest.whenever({ cond, thunk })` | Optional inclusion.                            |
-| `Manifest.embedYaml(source)`         | Pass through verbatim YAML (file or literal).  |
-
-The `Manifest<A>` itself is not where dependency-tracking happens — it
-just carries data and effect failures. The compile-time graph lives
-one level up; see below.
-
-## Where the type-safety lives
-
-konfig's dep-graph claim has two boundaries:
+## Usage
 
-1. **`AppOfApps.entrypoint(program)`** in `@konfig.ts/argocd`. Every
-   `Application.define({...})` produces an Effect `Layer.Layer<Out, _, In>`
-   that propagates the `Dep.Provide<K, N>` it produces in `Out` and the
-   `Dep.Need<K, N>` it consumes in `In`. Compose with `Layer.provideMerge`,
-   pass to `entrypoint`, and TypeScript checks `In === never`. A missing
-   provider is a compile error — see
-   [`examples/full-stack/infra/envs/broken.ts`](../../examples/full-stack/infra/envs/broken.ts).
-
-2. **`Environment.bind({ env, secrets })`** in `@konfig.ts/env`. The
-   bundle's secret atoms describe `{ envName, secret, key }` triples; the
-   `bind` checks at the type level that every secret has a backend, the
-   backend's `keys` set matches the bundle's keys, and a `requiresSource`
-   backend has a `source` of the right key shape.
-
-Inside a single `Application.define({ build })` Effect, dep tracking is
-declarative: when you `yield* Dep.Secret("ghcr-pull")` to obtain a
-`SecretRef<"ghcr-pull">`, you add the `Need` to the requirements. Forget
-to yield, and nothing complains — the system catches misses at
-composition, not inside an Application's body.
-
-## `Dep.*` — tracked kinds
+Pull a digest-verified Helm chart inside a reusable module:
 
 ```ts
-import { Dep } from "@konfig.ts/core"
+import { Application } from "@konfig.ts/argocd"
+import { Dep, Helm, Module } from "@konfig.ts/core"
+import { Namespace } from "@konfig.ts/k8s"
+
+export const definePostgres = Module.fixedNs({
+  target: Application.target,
+  namespace: "data",
+  build: ({ namespace }, opts: { storageGi: number }) => [
+    Namespace.make({ name: namespace }),
+    Helm.release({
+      repo: "https://charts.bitnami.com/bitnami",
+      chart: "postgresql",
+      version: "16.0.0",
+      digest: "sha256:…", // verified after pull AND on every cache hit
+      namespace,
+      values: { primary: { persistence: { size: `${opts.storageGi}Gi` } } }
+    })
+  ]
+})
 ```
 
-| Kind                              | Service                        | Provided value                            |
-| --------------------------------- | ------------------------------ | ----------------------------------------- |
-| `Dep.App<Name>(name)`             | `Need<"App", Name>`            | `Application` record                      |
-| `Dep.Application<Name>(name)`     | `Need<"Application", Name>`    | `Name` literal                            |
-| `Dep.Namespace<Name>(name)`       | `Need<"Namespace", Name>`      | `Name` literal                            |
-| `Dep.Secret<Name>(name)`          | `Need<"Secret", Name>`         | `SecretRef<Name>` brand                   |
-| `Dep.SecretValues<Name, K>(name)` | `Need<"SecretValues", Name>`   | `{ readonly [k in K]: Redacted<string> }` |
-| `Dep.ConfigMap<Name>(name)`       | `Need<"ConfigMap", Name>`      | `ConfigMapRef<Name>` brand                |
-| `Dep.ServiceAccount<Name>(name)`  | `Need<"ServiceAccount", Name>` | `ServiceAccountRef<Name>` brand           |
-| `Dep.Pvc<Name>(name)`             | `Need<"Pvc", Name>`            | `PvcRef<Name>` brand                      |
-
-For each kind there's a matching `provideX` helper (`provideSecret`,
-`provideNamespace`, …) that emits a `Layer.Layer<Provide<K, N>>`.
-
-`brand(value)` and `unsafeCoerce(value, reason)` from `@konfig.ts/core`
-are escape hatches. `brand` is fine — it's a nominal-typing primitive
-for the `*Ref` types. `unsafeCoerce` is the unchecked cast and takes a
-mandatory reason string so every call site documents WHY the cast is
-sound; prefer the schema boundary below for values crossing a trust
-boundary. (`coerce` is deprecated and will be removed before 1.0.)
-
-## Stable YAML — `Yaml.serialize({ value })`
-
-Output rules:
-
-- Top-level keys ordered: `apiVersion`, `kind`, `metadata`, `spec`,
-  `status`, then alphabetical.
-- Inside `metadata`: `name`, `namespace`, `labels`, `annotations`, then
-  alphabetical.
-- Every other map: alphabetical.
-- Lists preserve insertion order.
-- LF endings, 2-space indent, single trailing newline.
-- YAML 1.1 explicit (kubectl/ArgoCD compatibility).
-
-`Yaml.filenameFor(resource)` returns `<Kind>-<metadata.name>.yaml` —
-deterministic per-resource filenames for ArgoCD-friendly diffs.
-
-## Structural diff — `diffFiles({ left, right })`
-
-Each file's YAML is parsed and redacted (Helm-volatile metadata stripped)
-before deep-equality. Output is `Map<filename, FileDiff>`, formatted via
-`formatDiff(result, "summary" | "detail" | "json")`. Today's diff is
-two-way only and treats each file as a single document; richer per-doc
-and anchor-aware diffing is on the roadmap.
-
-## `Helm.release({...})`
-
-Calls `helm pull` and `helm template`, lifts each emitted YAML document
-as a `RawYaml` Manifest under the parent Application. SHA-256 of the
-`.tgz` is verified against `opts.digest` after pull **and** on every
-cache hit — flipping a byte in a cached tarball fails the next render
-with `HelmDigestMismatch`.
-
-`opts.digest` must include the `sha256:` prefix; the cache file name
-includes the first 12 hex digits, but the verifier compares the full
-hash.
-
-## Boundary decode — `boundary({ schema, label })`
-
-Wraps `Schema.decodeUnknownEffect` so that any decode failure becomes
-a `BoundaryDecodeError` with `schema: label`. Use at the seams where
-untyped input enters a module:
+Inside a build, `yield* Dep.Secret("ghcr-pull")` records a typed dependency that
+another module must provide — the graph is checked when you compose everything
+at `AppOfApps.entrypoint` (see [`@konfig.ts/argocd`](../argocd)).
 
-```ts
-const decodeApiOptions = boundary({ schema: ApiOptions, label: "api" })
-const cfg = yield * decodeApiOptions(input)
-```
+## Surface
 
-Every place that previously did `coerce<T>(YAML.parse(stdout))` over
-untrusted external output is now expected to use this helper.
+| Area        | Exports                                                                                                                         |
+| ----------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| Manifest    | `Manifest` (`.make` / `.combine` / `.concat` / `.whenever` / `.embedYaml`), `render`, `renderManifest`, `RenderContext`         |
+| Deps        | `Dep.*` kinds + `Dep.provide*` helpers; branded `SecretRef` / `ConfigMapRef` / `PvcRef` / `ServiceAccountRef` / `BuiltImageRef` |
+| Modules     | `Module.fixedNs`, `Module.dynamicNs`                                                                                            |
+| Helm        | `Helm.release` — chart pull + SHA-256 digest verification                                                                       |
+| YAML & diff | `Yaml.serialize` / `Yaml.filenameFor`; `diffFiles`, `formatDiff`, `parseYaml`, `redact`                                         |
+| Config      | `KonfigConfig`, `ImagesConfig`, and their decoders                                                                              |
+| Boundaries  | `boundary` (Schema decode → `BoundaryDecodeError`); `brand` / `unsafeCoerce` escape hatches                                     |
+| Errors      | the tagged union `AnyRenderError` (`HelmDigestMismatch`, `BoundaryDecodeError`, …)                                              |
 
-## Layout
+## Internals
 
-```
-src/
-├── index.ts              barrel
-├── _cast.ts              brand + coerce (escape hatch)
-├── boundary.ts           Schema.decode wrapper → BoundaryDecodeError
-├── deps.ts               Dep.* kinds + provide* helpers
-├── diff.ts               structural diff + redaction
-├── Helm.ts               Helm.release with digest verification
-├── images.ts             ImagesConfig + decoders
-├── konfigConfig.ts       KonfigConfig schema (top-level config)
-├── Manifest.ts           Manifest interface + combinators
-├── render.ts             render entrypoint
-├── RenderContext.ts      threaded through every render
-├── RenderError.ts        tagged error union
-├── types.ts              Kind enum (legacy; superseded by Dep.*)
-└── yaml/
-    ├── index.ts
-    └── serialize.ts      stable YAML serializer + filenameFor
-```
+`Manifest<A>` is only a recipe from a `RenderContext` to an Effect that produces
+an `A` — it does not track deps in its own type. Per-kind dependency tracking
+lives one level up, in the Effect `Layer`s that `Module` and
+`Application.define` compose. See
+[`.docs/architecture.md`](../../.docs/architecture.md).
 
 ## Requirements
 
-konfig.ts builds on [Effect](https://effect.website/), which is still in
-beta. Until Effect ships a stable 4.x, you must install the exact beta
-konfig is developed against:
+konfig.ts is built on [Effect](https://effect.website/), currently in beta.
+Until Effect ships a stable 4.x, install the exact beta konfig.ts is built
+against:
 
-- **`effect@4.0.0-beta.70`** — required.
-- **`@effect/platform-node@4.0.0-beta.70`** — required only for `render()`
-  (the Node filesystem/subprocess entrypoint); manifest-only consumers can
-  omit it.
+- **`effect@4.0.0-beta.70`** — required by every package.
+- **`@effect/platform-node@4.0.0-beta.70`** — required only when you call
+  `render()` (the Node filesystem/subprocess entrypoint); manifest-only
+  consumers can omit it (it is declared as an optional peer).
 
-The peer dependency is pinned to the exact version on purpose: Effect's beta
-line makes breaking changes between builds, so a looser range would surface
-as `ERESOLVE` install conflicts rather than a working install. This pin will
-relax to a caret range once Effect reaches a stable 4.x.
+The pin is exact on purpose: Effect's beta line makes breaking changes between
+builds, so a looser range surfaces as `ERESOLVE` install conflicts. It relaxes
+to a caret range once Effect reaches a stable 4.x.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@konfig.ts/core",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "description": "Core abstractions (Manifest, RenderContext, Helm, deps) for konfig.ts — typesafe Kubernetes + ArgoCD config in TypeScript.",
   "license": "MIT",
   "author": "David Stahl-Gruber",