@intentic/need-resolver 1.310.0 → 1.311.0

package/README.md

@@ -1,25 +1,27 @@
-# @intentic/need-resolver
+# need-resolver
 
-The **need resolver**: turns an authored `IntentSet` into the abstract capabilities it requires. It owns the authored intent shapes and the intent → needs derivation, the first stage of the pipeline. Depends only on [`@intentic/graph`](../graph); consumed by [`@intentic/state-resolver`](../state-resolver) and [`@intentic/sdk`](../sdk).
+Defines the intent data the SDK records and derives from it the abstract capabilities the deployment needs, before any concrete tool is chosen.
 
-## Responsibilities
+```mermaid
+flowchart LR
+    sdk["sdk<br/>i.have · i.want"] -- "IntentSet" --> need(["need-resolver<br/>resolveNeeds"])
+    need -- "Need[]<br/>capability · scope · plane" --> state["state-resolver<br/>catalog picks an option"]
+```
 
-- Define the authored intent shapes (`IntentSet`, `HostIntent`, `CloudflareIntent`, `AppIntent`, …) and their input types.
-- Derive the abstract `Need`s an intent implies (`source-control`, `docker-registry`, `infra-control`, `deployment-target`, `domain`) each a `Capability` on a `Plane` (control vs application).
-- It stops at *abstract capabilities*: it does **not** choose concrete options (Forgejo/Komodo/etc.) or emit graph nodes, that is `state-resolver`'s job.
+- A `Need` is one capability at one scope: `source-control`, `docker-registry` and `infra-control` on the control-plane host, `deployment-target` on every host that runs something, and `domain` on the Cloudflare account.
+- Many apps collapse into one set of needs. The control-plane host is the first declared host with apps (`controlPlaneHostId`).
+- It validates the intent as a whole: apps without Cloudflare, targets on undeclared hosts and workspace tools naming undeclared services all throw here.
+- The intent stays plain data. Handles become resource-id strings, so an `IntentSet` serializes and carries no SDK types.
 
 ## Key files
 
-- [src/intent.ts](src/intent.ts): the authored intent types (`IntentSet` and friends).
-- [src/inputs.ts](src/inputs.ts): input shapes (`HostInput`, `CloudflareInput`, `EnvironmentInput`, `NotifyInput`, …).
-- [src/needs.ts](src/needs.ts): `resolveNeeds`, `Capability`/`Need`/`Plane`, `needKey`.
-- [src/index.ts](src/index.ts): public surface.
+- [src/intent.ts](src/intent.ts) — `IntentSet` and one intent type per declaration kind.
+- [src/inputs.ts](src/inputs.ts) — the author-supplied input shapes (`HostInput`, `EnvironmentInput`, `UpdatePolicy`).
+- [src/needs.ts](src/needs.ts) — `resolveNeeds`, `Capability`, `Plane` and the control-plane host rule.
+- [src/needs.test.ts](src/needs.test.ts) — which intents produce which needs, by example.
 
-## How it fits
+## Commands
 
-Stage 1 of intent → needs → desired-state. The `sdk` builds an `IntentSet` from a `deploy.config.ts`; `resolveNeeds` turns it into `Need`s; `state-resolver` assigns each need a catalog option and emits nodes.
-
-## Conventions & gotchas
-
-- Needs are intentionally provider-agnostic: keep concrete tech names out of this layer.
-- Each need carries its `Plane`; downstream resolution and ordering rely on it. Co-located tests in [src/needs.test.ts](src/needs.test.ts). See [ARCHITECTURE.md](../../ARCHITECTURE.md).
+```sh
+pnpm --filter @intentic/need-resolver test
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentic/need-resolver",
-  "version": "1.310.0",
+  "version": "1.311.0",
   "description": "",
   "license": "MIT",
   "type": "module",
@@ -30,7 +30,7 @@
     }
   },
   "dependencies": {
-    "@intentic/graph": "1.310.0",
+    "@intentic/graph": "1.311.0",
     "tslib": "2.8.1"
   },
   "devDependencies": {