@owlmeans/server-config 0.1.18-rc.8 → 0.1.18

package/README.md

@@ -11,7 +11,7 @@ Server-specific configuration utilities: `sservice()` helper and config-file rea
 ## Installation
 
 ```bash
-bun add @owlmeans/server-config
+bun add @owlmeans/server-config@^0.1.18
 ```
 
 ## Usage
@@ -65,7 +65,7 @@ This package ships embedded agent skills under `agent-meta/`. After installing y
 your project's skill store (`.agents/skills/`):
 
 ```sh
-npx @owlmeans/agent-skills
+npx @owlmeans/agent-skills@^0.1.18
 ```
 
 The embedded files are version-matched to this package release. Do not edit them

package/agent-meta/manifest.json

@@ -1,8 +1,8 @@
 {
-  "schemaVersion": 2,
+  "schemaVersion": 3,
   "package": "@owlmeans/server-config",
-  "version": "0.1.18-rc.7",
-  "generatedAt": "2026-08-24T21:14:00.132Z",
+  "version": "0.1.18",
+  "generatedAt": "2026-10-28T00:31:34.745Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {

package/agent-meta/skills/server-config/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: server-config
-description: How to use @owlmeans/server-config — server-side config helpers and validation building on @owlmeans/config. Auto-invoked when importing server config helpers.
+description: How to use @owlmeans/server-config — sservice() to declare a backend service route in the config, readConfigValue() to read a value out of a mounted file, and the BasicServerConfig shape that adds secrets. Auto-invoked when building a server config, declaring a backend service, or feeding a mounted secret into config.
 user-invocable: false
 ---
 <!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
@@ -8,25 +8,85 @@ user-invocable: false
 # @owlmeans/server-config
 
 **Layer:** Server
-**Install:** `"@owlmeans/server-config": "^0.1.18-rc.7"` in `dependencies`
+**Install:** `"@owlmeans/server-config": "^0.1.18"` in `dependencies`
+
+The server-side half of `@owlmeans/config`. Small on purpose: it declares backend services and it
+reads file-backed values. Everything else about config lives in `@owlmeans/config`, and the context
+that applies these is `@owlmeans/server-context`.
 
 ## Key Exports
 
 | Export | Description |
 |--------|-------------|
-| `Config` (server) types | Server-side Config interface (extends core Config) |
-| `serverConfig(...)` helpers | Build a typed server config |
-| Helpers | Resolve trusted entities, secret paths |
+| `sservice(service, cfg?)` | Declare a backend service route into `cfg.services` and return the config |
+| `readConfigValue(value, def?)` | A value starting with `/` or `file://` becomes the trimmed contents of that path; `undefined` falls back to `def`, and any other string is returned as is |
+| `BasicServerConfig` | `CommonConfig` plus `secrets: Record<string, string>` |
+
+## Declaring services
+
+`sservice` takes a `ServiceRoute` without `type` — `service` (the alias other routes name), `host`
+/ `port` for how the world reaches it, `internalHost` / `internalPort` for how the cluster does,
+`base`, and `opened` (bind on all interfaces rather than loopback). It writes the entry under
+`service.service` and defaults `type` to `AppType.Backend` — a default only, because the entry
+already stored under that alias is spread over it: an alias first declared by `service()` from
+`@owlmeans/config` as `AppType.Frontend` keeps that type through a later `sservice` call. Declare a
+frontend service with `service()`.
+
+```typescript
+import { sservice } from '@owlmeans/server-config'
+
+let cfg = sservice({ service: MY_SERVICE, internalHost: 'my-api', internalPort: 8080, opened: true })
+cfg = sservice({ service: AGENT, internalHost: 'agent', internalPort: 8081 }, cfg)
+```
+
+**One call per service, and it carries the whole address.** The write merges over whatever the key
+already held, but `host` and `port` are then set last and unconditionally from the incoming argument
+alone — `host: service.host ?? service.internalHost`, `port: service.port ?? service.internalPort`.
+So a second `sservice` for the same alias that names no address at all overwrites the stored `host`
+and `port` with `undefined`, and the service becomes unaddressable. Amend an existing entry by
+assigning the field instead:
+
+```typescript
+cfg.services[MY_SERVICE].opened = true
+```
+
+That last-write rule is also the mirroring rule: whenever `host` / `port` are unset, the internal
+ones become them. An entry declared with `internalHost` / `internalPort` only therefore carries the
+cluster address in `host` / `port` as well — which is what a client sees wherever the config is
+advertised (`@owlmeans/api-config-server`), so an internal address is not a private one.
+
+The service the process **is** — `cfg.services[cfg.service]` — is the one the API server binds:
+`internalPort ?? port` is the port, and `opened` decides between `0.0.0.0` and `127.0.0.1`. A peer
+service is declared the same way and is never bound, only addressed.
+
+`@owlmeans/server-app` re-exports `sservice`, so an app on it needs no direct dependency here.
 
-## Usage
+## File-backed values
+
+`readConfigValue` is how a mounted secret becomes a config value: a string starting with `/` or
+`file://` is handed to `readFileSync` and its contents trimmed, `undefined` falls back to `def`, and
+every other string is returned unchanged. That makes a config literal and a mounted path
+interchangeable at the same key, which is what lets a deployment inject a credential without a code
+path of its own.
+
+**Mount the secret at an absolute path.** A `file://` prefix passes the same test but is handed to
+`readFileSync` as a literal string, and that does not resolve a URL: the read fails with `ENOENT`
+on the URL text itself rather than returning the file. `/` is the form that works, and the only one
+anything in the framework produces.
 
 ```typescript
-import { serverConfig } from '@owlmeans/server-config'
-import { AppType } from '@owlmeans/config'
+import { readConfigValue } from '@owlmeans/server-config'
 
-const cfg = serverConfig({ service: 'my-api', type: AppType.Backend, port: 8080 })
+const secret = readConfigValue(process.env.MY_SECRET, 'dev-secret')
 ```
 
+Reading is synchronous and unguarded — a missing file throws where it is called. A whole config tree
+is converted at once by the `fileConfigReader` middleware from `@owlmeans/server-context`, so an app
+rarely calls this itself; reach for it when a value is produced outside the config tree.
+
+`secrets` on `BasicServerConfig` is the conventional home for those values — a flat map, so every
+entry can be either a literal or a path and the reader treats them alike.
+
 ## Depends On
 
-- `@owlmeans/config`, `@owlmeans/auth`, `@owlmeans/server-context`
+- `@owlmeans/config`, `@owlmeans/server-route`

package/build/config.d.ts

@@ -1,4 +1,4 @@
 import type { BasicServerConfig } from './types.js';
 import type { ServiceRoute } from '@owlmeans/server-route';
-export declare const sservice: <C extends BasicServerConfig>(service: Omit<ServiceRoute, "resolved" | "type">, cfg?: Partial<C>) => C;
+export declare const sservice: <C extends BasicServerConfig>(service: Omit<ServiceRoute, "type">, cfg?: Partial<C>) => C;
 //# sourceMappingURL=config.d.ts.map

package/build/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAC,MAAO,YAAY,CAAA;AACnD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAA;AAE1D,eAAO,MAAM,QAAQ,GAAI,CAAC,SAAS,iBAAiB,WAAW,IAAI,CAAC,YAAY,EAAE,UAAU,GAAG,MAAM,CAAC,QAAQ,OAAO,CAAC,CAAC,CAAC,KAAG,CAe1H,CAAA"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAC,MAAO,YAAY,CAAA;AACnD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAA;AAE1D,eAAO,MAAM,QAAQ,GAAI,CAAC,SAAS,iBAAiB,WAAW,IAAI,CAAC,YAAY,EAAE,MAAM,CAAC,QAAQ,OAAO,CAAC,CAAC,CAAC,KAAG,CAc7G,CAAA"}

package/build/config.js

@@ -8,7 +8,6 @@ export const sservice = (service, cfg) => {
         type: AppType.Backend,
         ..._cfg.services[service.service],
         ...service,
-        resolved: service.host != null || service.internalHost != null,
         host: service.host ?? service.internalHost,
         port: service.port ?? service.internalPort,
     };

package/build/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAA;AAI1C,MAAM,CAAC,MAAM,QAAQ,GAAG,CAA8B,OAAgD,EAAE,GAAgB,EAAK,EAAE;IAC7H,MAAM,IAAI,GAAM,CAAC,GAAG,IAAI,EAAE,CAAM,CAAA;IAChC,IAAI,IAAI,CAAC,QAAQ,IAAI,IAAI,EAAE,CAAC;QAC1B,IAAI,CAAC,QAAQ,GAAG,EAAE,CAAA;IACpB,CAAC;IACD,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG;QAC/B,IAAI,EAAE,OAAO,CAAC,OAAO;QACrB,GAAG,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,OAAO,CAAC;QACjC,GAAG,OAAO;QACV,QAAQ,EAAE,OAAO,CAAC,IAAI,IAAI,IAAI,IAAI,OAAO,CAAC,YAAY,IAAI,IAAI;QAC9D,IAAI,EAAE,OAAO,CAAC,IAAI,IAAI,OAAO,CAAC,YAAY;QAC1C,IAAI,EAAE,OAAO,CAAC,IAAI,IAAI,OAAO,CAAC,YAAY;KAC3C,CAAA;IAED,OAAO,IAAI,CAAA;AACb,CAAC,CAAA"}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAA;AAI1C,MAAM,CAAC,MAAM,QAAQ,GAAG,CAA8B,OAAmC,EAAE,GAAgB,EAAK,EAAE;IAChH,MAAM,IAAI,GAAM,CAAC,GAAG,IAAI,EAAE,CAAM,CAAA;IAChC,IAAI,IAAI,CAAC,QAAQ,IAAI,IAAI,EAAE,CAAC;QAC1B,IAAI,CAAC,QAAQ,GAAG,EAAE,CAAA;IACpB,CAAC;IACD,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG;QAC/B,IAAI,EAAE,OAAO,CAAC,OAAO;QACrB,GAAG,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,OAAO,CAAC;QACjC,GAAG,OAAO;QACV,IAAI,EAAE,OAAO,CAAC,IAAI,IAAI,OAAO,CAAC,YAAY;QAC1C,IAAI,EAAE,OAAO,CAAC,IAAI,IAAI,OAAO,CAAC,YAAY;KAC3C,CAAA;IAED,OAAO,IAAI,CAAA;AACb,CAAC,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/server-config",
-  "version": "0.1.18-rc.8",
+  "version": "0.1.18",
   "license": "MIT",
   "type": "module",
   "scripts": {
@@ -21,12 +21,12 @@
     }
   },
   "dependencies": {
-    "@owlmeans/config": "^0.1.18-rc.8",
-    "@owlmeans/server-route": "^0.1.18-rc.6"
+    "@owlmeans/config": "^0.1.18",
+    "@owlmeans/server-route": "^0.1.18"
   },
   "devDependencies": {
-    "@owlmeans/dep-config": "workspace:*",
-    "@types/node": "^26.1.0",
+    "@owlmeans/dep-config": "^0.1.18",
+    "@types/node": "^26.6.4",
     "nodemon": "^3.1.14",
     "typescript": "^7.0.2"
   },

package/src/config.ts

@@ -3,16 +3,15 @@ import { AppType } from '@owlmeans/config'
 import type { BasicServerConfig}  from './types.js'
 import type { ServiceRoute } from '@owlmeans/server-route'
 
-export const sservice = <C extends BasicServerConfig>(service: Omit<ServiceRoute, "resolved" | "type">, cfg?: Partial<C>): C => {
+export const sservice = <C extends BasicServerConfig>(service: Omit<ServiceRoute, "type">, cfg?: Partial<C>): C => {
   const _cfg: C = (cfg ?? {}) as C
   if (_cfg.services == null) {
     _cfg.services = {}
   }
-  _cfg.services[service.service] = { 
-    type: AppType.Backend, 
-    ..._cfg.services[service.service], 
-    ...service, 
-    resolved: service.host != null || service.internalHost != null,
+  _cfg.services[service.service] = {
+    type: AppType.Backend,
+    ..._cfg.services[service.service],
+    ...service,
     host: service.host ?? service.internalHost,
     port: service.port ?? service.internalPort,
   }