@burojs/config 0.2.0 → 0.5.0

package/README.md

@@ -3,10 +3,13 @@
 Inert JSON and YAML declaration sources for [buro](https://github.com/buro/buro).
 
 Parses a raw JSON or YAML string against a host-owned `SourcePolicy` and
-produces a portable declaration layer — or a list of diagnostics if the
-source is malformed, oversized, or requests something its policy doesn't
-allow. The output can only ever be data: no functions, components, schemas,
-credentials, or provider/action/mapper bindings survive the parse.
+produces a portable declaration layer that carries the policy's grants — or a
+list of diagnostics if the source is malformed, oversized, or requests
+something its policy doesn't allow. *Source* here is a configuration source — a
+JSON or YAML document a host loads into a layer runtime — not a screen's `with`
+source. The output can only ever be data: no
+functions, components, schemas, credentials, or provider/action/mapper bindings
+survive the parse.
 
 ## Install
 
@@ -20,12 +23,24 @@ pnpm add @burojs/config
 import { parseJsonLayer, type SourcePolicy } from '@burojs/config';
 
 const policy: SourcePolicy = {
-  allowedKinds: ['resource'],
-  allowedNamespaces: ['crm'],
-  allowedTransformOps: [],
-  maxTransformScope: 'layer',
+  grants: {
+    allowedKinds: ['resource'],
+    allowedNamespaces: ['crm'],
+    allowedTransformOps: [],
+    maxTransformScope: 'layer',
+    writePaths: {},
+    allowedResources: [],
+    allowedQueries: [],
+    allowedFlows: [],
+    allowedBackends: ['company'],
+    allowedBlocks: [],
+    allowedFrames: [],
+    allowedInlineFlows: [],
+    allowedFieldImplementations: [],
+    priority: { min: 0, max: 0 },
+  },
   allowedCapabilities: {},
-  limits: { maxBytes: 16_000, maxDeclarations: 12, maxDepth: 16, maxStringLength: 1_000, maxDiagnostics: 8 },
+  limits: { maxBytes: 16_000, maxDeclarations: 12, maxDepth: 16, maxNodes: 1_000, maxStringLength: 1_000, maxDiagnostics: 8 },
 };
 
 const source = JSON.stringify({
@@ -34,25 +49,45 @@ const source = JSON.stringify({
   defaultNamespace: 'crm',
   revision: 'r1',
   declarations: [
-    { kind: 'resource', ref: 'company', schemaVersion: 1, value: { name: 'company' } },
+    { kind: 'resource', ref: 'company', schemaVersion: 2, value: { name: 'company' } },
   ],
 });
 
 const result = parseJsonLayer(source, policy);
 if (!result.ok) throw new Error(result.diagnostics.map((d) => d.code).join(', '));
-// result.value is a LayerInput, ready for runtime.publishLayer(...)
+// result.value is a ParsedLayer carrying the grants of `policy`:
+await runtime.publishLayer(result.value);
 ```
 
-To load a source lazily instead of publishing it up front, wrap the parser in
-`createConfigRuntimeSource` and hand the result to a core `LayerRuntime` via
-`registerSource`/`loadSource`.
+To load a source lazily instead of publishing it up front, give
+`createConfigRuntimeSource` the policy and a `load` that returns the document's
+text; it parses each load under the policy, and returns the runtime source with
+the trust to register it under:
+
+```ts
+const configured = createConfigRuntimeSource('catalog', {
+  policy,
+  load: async () => ({ format: 'json', text: await fetch('/config/catalog.json').then((r) => r.text()) }),
+});
+runtime.registerSource(configured.source, configured.trust);
+```
+
+The parser checks keys (it refuses `action`, `component`, `validator` and the
+other code-bearing keys), the trusted-attachment capabilities in
+`allowedCapabilities`, and the `limits`; those checks are parser-only. The
+compiler enforces the `grants` — the kinds, namespaces and transform operations
+a layer uses, the paths a transform may write (`writePaths`, no default), its
+targets, its references (`allowedResources`, `allowedQueries`,
+`allowedFlows`), its backend bindings (`allowedBackends`) and its priority
+band. Use a band strictly away from your code's priorities to fix whether a
+parsed layer applies before or after your code. See the "Grants and trust"
+section of the guide linked below.
 
 ## Main exports
 
 - **`parseJsonLayer` / `parseYamlLayer`** — parse a source string against a `SourcePolicy`, returning a `ParseResult`.
-- **`createConfigRuntimeSource`** — builds a core `RuntimeSource` that fetches, parses, and adapts a source on demand.
-- **`adaptRawConfig` / `parseResultAdapter`** — the pure adapter boundary between a raw source shape and the layer the runtime commits.
-- **`SourcePolicy` / `SourceLimits`** — the allow-list and resource limits a host defines for one untrusted source.
+- **`createConfigRuntimeSource(id, { policy, load })`** — returns `{ source, trust }`: a core `RuntimeSource` that loads and parses a document on demand, and the policy's grants to register it with.
+- **`SourcePolicy` / `SourceLimits`** — `{ grants, allowedCapabilities, limits }`, what a host allows one untrusted source: `grants` (the core `LayerGrants`) is what its parsed layers carry; `SCREEN_SOURCE_LIMITS` is a preset for sources that carry whole screen trees.
 
 See [`docs/raw-config-manifests.md`](../../docs/raw-config-manifests.md) for the full source-policy boundary and how it composes with a `LayerRuntime`.