@htilabs/platform-common-models 0.8.13 → 0.8.14

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (72) hide show
  1. package/README.md +44 -0
  2. package/dist/config/index.cjs +4 -0
  3. package/dist/config/index.cjs.map +1 -1
  4. package/dist/config/index.d.cts +16 -1
  5. package/dist/config/index.d.ts +16 -1
  6. package/dist/config/index.js +2 -0
  7. package/dist/config/index.js.map +1 -1
  8. package/dist/constants/index.cjs +10 -0
  9. package/dist/constants/index.cjs.map +1 -1
  10. package/dist/constants/index.d.cts +1 -1
  11. package/dist/constants/index.d.ts +1 -1
  12. package/dist/constants/index.js +10 -0
  13. package/dist/constants/index.js.map +1 -1
  14. package/dist/cvcs/index.cjs +505 -2
  15. package/dist/cvcs/index.cjs.map +1 -1
  16. package/dist/cvcs/index.d.cts +2642 -2084
  17. package/dist/cvcs/index.d.ts +2642 -2084
  18. package/dist/cvcs/index.js +500 -2
  19. package/dist/cvcs/index.js.map +1 -1
  20. package/dist/{index-I-DiX9eQ.d.ts → index-CDoqrfc1.d.ts} +1 -1
  21. package/dist/{index-CoVr1jIV.d.cts → index-Zu_mOJRn.d.cts} +1 -1
  22. package/dist/index.cjs +582 -4
  23. package/dist/index.cjs.map +1 -1
  24. package/dist/index.d.cts +111 -7
  25. package/dist/index.d.ts +111 -7
  26. package/dist/index.js +571 -4
  27. package/dist/index.js.map +1 -1
  28. package/dist/models/index.d.cts +2 -2
  29. package/dist/models/index.d.ts +2 -2
  30. package/dist/mongo/index.cjs +383 -0
  31. package/dist/mongo/index.cjs.map +1 -0
  32. package/dist/mongo/index.d.cts +221 -0
  33. package/dist/mongo/index.d.ts +221 -0
  34. package/dist/mongo/index.js +351 -0
  35. package/dist/mongo/index.js.map +1 -0
  36. package/dist/{platform-auth-BfCMuAlC.d.cts → platform-auth-AsfnIXfK.d.cts} +2 -2
  37. package/dist/{platform-auth-BfCMuAlC.d.ts → platform-auth-AsfnIXfK.d.ts} +2 -2
  38. package/dist/schemas/index.cjs +5 -1
  39. package/dist/schemas/index.cjs.map +1 -1
  40. package/dist/schemas/index.d.cts +29 -25
  41. package/dist/schemas/index.d.ts +29 -25
  42. package/dist/schemas/index.js +5 -1
  43. package/dist/schemas/index.js.map +1 -1
  44. package/dist/types/index.d.cts +2 -2
  45. package/dist/types/index.d.ts +2 -2
  46. package/package.json +10 -1
  47. package/src/__sot__/coreIndicators.pin.json +6 -1
  48. package/src/__tests__/__snapshots__/cvc-sot.snap +18 -2
  49. package/src/__tests__/cvc-136-scoring-invariant.test.ts +6 -3
  50. package/src/__tests__/cvc-drift-gate.test.ts +14 -3
  51. package/src/__tests__/cvc-sot-snapshot.test.ts +13 -1
  52. package/src/__tests__/cvc-structural.test.ts +6 -0
  53. package/src/__tests__/mongo-verifier.test.ts +502 -0
  54. package/src/config/index.ts +8 -2
  55. package/src/constants/ic.ts +31 -2
  56. package/src/cvcs/assertionStatus.v1.0.0.json +80 -0
  57. package/src/cvcs/coreIndicators.v1.0.0.json +67 -2
  58. package/src/cvcs/createdBySystem.v1.0.0.json +89 -0
  59. package/src/cvcs/hmisSex.v1.0.0.json +89 -0
  60. package/src/cvcs/index.ts +18 -0
  61. package/src/cvcs/minorAdultStatus.v1.0.0.json +80 -0
  62. package/src/cvcs/subjectType.v1.0.0.json +80 -0
  63. package/src/generated/cvc-enums.ts +76 -2
  64. package/src/index.ts +20 -0
  65. package/src/mongo/catalog.ts +65 -0
  66. package/src/mongo/contract.ts +157 -0
  67. package/src/mongo/index.ts +343 -0
  68. package/src/mongo/similarity.ts +133 -0
  69. package/src/mongo/uri.ts +53 -0
  70. package/src/schemas/common.ts +4 -0
  71. package/dist/{cvcEntry-BCj1OWqL.d.cts → cvcEntry-0BIB9sen.d.cts} +8 -8
  72. package/dist/{cvcEntry-BCj1OWqL.d.ts → cvcEntry-0BIB9sen.d.ts} +8 -8
package/README.md CHANGED
@@ -16,6 +16,50 @@ Package exports are organized into a public root API and a small number of
16
16
  dedicated subpaths (`/validation`, `/cvcs`) — consult `package.json` for the
17
17
  authoritative `exports` map.
18
18
 
19
+ ## Seeding CVCs
20
+
21
+ The CVC Source-of-Truth catalogs under `src/cvcs/` are seeded into MongoDB with:
22
+
23
+ ```bash
24
+ # one domain
25
+ MONGO_URI="<cluster>/platform-test" pnpm seed:cvc -- --domain service_categories --version 1.0.0
26
+
27
+ # every domain + the default platform registry
28
+ MONGO_URI="<cluster>/platform-test" pnpm seed:cvc:all
29
+ ```
30
+
31
+ The connection URI comes from `MONGO_URI` (or `--mongo-uri`); the target database
32
+ is whatever the URI's path says. Pass `--dry-run` to validate and report counts
33
+ without writing anything.
34
+
35
+ ### Production-DB seed guard
36
+
37
+ Both seeders run a DB-name safety guard after the target URI is resolved and
38
+ before any write connection, so a production database cannot be seeded silently.
39
+ The target database name is parsed from the Mongo URI (`mongodb://` and
40
+ `mongodb+srv://`, the path segment after the host, before any `?`).
41
+
42
+ - **Test databases** — a database whose name ends in `-test` (e.g.
43
+ `platform-test`) seeds with **no prompt**. Agents and CI can run it freely:
44
+
45
+ ```bash
46
+ MONGO_URI="<cluster>/platform-test" pnpm seed:cvc:all
47
+ ```
48
+
49
+ - **Any other (prod-shaped) database** — e.g. `platform`, `platform-db`, or a URI
50
+ with no database name — requires an **interactive human confirmation**: you
51
+ must type the exact target database name at the terminal (read from
52
+ `/dev/tty`). There is **no** flag or environment variable to skip this — no
53
+ `--yes`, no `--force`, no `FORCE=1`.
54
+
55
+ If stdin is not a TTY (agent, CI, pipe, `nohup`, background) the seeder
56
+ **aborts** with a non-zero exit (`refusing to seed non-test DB '<name>'
57
+ without interactive confirmation`). This non-TTY abort is what makes the guard
58
+ un-bypassable by non-interactive callers.
59
+
60
+ - **`--dry-run`** never prompts or aborts for any database (it writes nothing),
61
+ but its output states whether a real run *would* proceed, prompt, or abort.
62
+
19
63
  ## Service Catalog: Deprecation Notice
20
64
 
21
65
  The hardcoded `IC_48_*` constants and helpers in
@@ -21,6 +21,8 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
21
21
  var config_exports = {};
22
22
  __export(config_exports, {
23
23
  createConfigEndpoint: () => createConfigEndpoint,
24
+ loadContract: () => loadContract,
25
+ resolveDefault: () => resolveDefault,
24
26
  validateAgainstContract: () => validateAgainstContract
25
27
  });
26
28
  module.exports = __toCommonJS(config_exports);
@@ -186,6 +188,8 @@ function createConfigEndpoint(runtimeYamlPath, opts = {}) {
186
188
  // Annotate the CommonJS export names for ESM import in node:
187
189
  0 && (module.exports = {
188
190
  createConfigEndpoint,
191
+ loadContract,
192
+ resolveDefault,
189
193
  validateAgainstContract
190
194
  });
191
195
  //# sourceMappingURL=index.cjs.map
@@ -1 +1 @@
1
- {"version":3,"sources":["../../src/config/index.ts"],"sourcesContent":["/**\n * @htilabs/platform-common-models — Runtime Config Contract Validator\n *\n * Implements contract R12.1 (platform-common home):\n * - validateAgainstContract(runtimeYamlPath, opts?) — startup validator (R3.2)\n * - createConfigEndpoint(runtimeYamlPath, opts?) — /api/config factory (R7)\n *\n * Consumers MUST call validateAgainstContract once at process startup, before\n * any other initialization that reads env vars. Build-phase variables\n * (phase: build) are NOT checked at runtime per R3.4.\n *\n * No secret VALUES are read, stored, or returned here. Secret env vars are\n * validated for presence but their values are never logged or exposed.\n *\n * Dual ESM + CJS via tsup. Plain JS consumers (pave, leads) use require():\n * const { validateAgainstContract } = require('@htilabs/platform-common-models/config');\n */\n\nimport { readFileSync } from \"node:fs\";\nimport { parse } from \"yaml\";\n\n// ─── Schema types (mirrors thread's runtime-config-lib.ts VariableSpec) ──────\n\nexport interface VariableSpec {\n type: \"string\" | \"boolean\" | \"number\" | \"enum\" | \"url\" | \"json\";\n required: boolean;\n secret: boolean;\n description: string;\n phase?: \"runtime\" | \"build\";\n values?: string[];\n default?: Record<string, unknown>;\n provider?: string;\n name?: string;\n client_visible?: boolean;\n deprecated?: { since: string; remove_after?: string; replacement?: string };\n}\n\nexport interface ServiceContract {\n service: string;\n version: number;\n environments: string[];\n // Thread extensions (tolerated, not required — R1.1 note)\n port?: number;\n build_secrets?: string[];\n variables: Record<string, VariableSpec>;\n}\n\n/** Typed config accessor returned by validateAgainstContract. */\nexport type TypedConfig = Record<string, string | boolean | number | unknown>;\n\nexport interface ValidateOptions {\n /**\n * Environment name used to select per-env defaults (e.g. \"local\", \"test\").\n * Defaults to process.env.NODE_ENV, then \"local\".\n */\n env?: string;\n /**\n * If true, do not call process.exit(1) on failure; throw instead.\n * Useful for tests. Defaults to false (production mode exits).\n */\n throwOnFailure?: boolean;\n}\n\nexport interface EndpointOptions {\n /** Cache-Control header value. Defaults to \"private, no-store\". */\n cacheControl?: string;\n}\n\n/**\n * A framework-agnostic route handler that returns a JSON response.\n * Compatible with:\n * - Next.js App Router: export const GET = createConfigEndpoint(...)\n * - Fastify: instance.get('/api/config', createConfigEndpoint(...))\n * - Express: app.get('/api/config', createConfigEndpoint(...))\n */\nexport type RouteHandler = (\n req?: unknown,\n res?: unknown,\n) => Promise<Response | void> | Response | void;\n\n// ─── YAML parser ──────────────────────────────────────────────────────────────\n\nfunction loadContract(runtimeYamlPath: string): ServiceContract {\n let raw: string;\n try {\n raw = readFileSync(runtimeYamlPath, \"utf8\");\n } catch (err) {\n const msg =\n err instanceof Error ? err.message : String(err);\n throw new Error(\n `[platform-common/config] Cannot read ${runtimeYamlPath}: ${msg}`,\n );\n }\n const parsed = parse(raw) as ServiceContract | null;\n if (!parsed || typeof parsed !== \"object\") {\n throw new Error(\n `[platform-common/config] ${runtimeYamlPath}: not a YAML mapping`,\n );\n }\n if (parsed.version !== 1) {\n throw new Error(\n `[platform-common/config] ${runtimeYamlPath}: unsupported contract version ${parsed.version} (expected 1)`,\n );\n }\n if (!parsed.variables || typeof parsed.variables !== \"object\") {\n throw new Error(\n `[platform-common/config] ${runtimeYamlPath}: missing \"variables\" map`,\n );\n }\n return parsed;\n}\n\n// ─── Coercion ────────────────────────────────────────────────────────────────\n\n/**\n * Coerce a raw environment string value to the declared type.\n * Returns [ok, coerced] or [false, errorMessage].\n */\nfunction coerce(\n key: string,\n raw: string,\n spec: VariableSpec,\n): [true, unknown] | [false, string] {\n switch (spec.type) {\n case \"boolean\": {\n if (raw === \"true\" || raw === \"1\") return [true, true];\n if (raw === \"false\" || raw === \"0\") return [true, false];\n return [false, `${key}: expected boolean (\"true\"/\"false\"/\"1\"/\"0\"), got \"${raw}\"`];\n }\n case \"number\": {\n const n = Number(raw);\n if (!Number.isFinite(n)) {\n return [false, `${key}: expected number, got \"${raw}\"`];\n }\n return [true, n];\n }\n case \"enum\": {\n const vals = spec.values ?? [];\n if (!vals.includes(raw)) {\n return [false, `${key}: expected one of [${vals.join(\", \")}], got \"${raw}\"`];\n }\n return [true, raw];\n }\n case \"url\": {\n try {\n new URL(raw);\n return [true, raw];\n } catch {\n return [false, `${key}: expected a valid URL, got \"${raw}\"`];\n }\n }\n case \"json\": {\n try {\n const parsed = JSON.parse(raw) as unknown;\n return [true, parsed];\n } catch {\n return [false, `${key}: expected valid JSON, got \"${raw}\"`];\n }\n }\n default:\n // string\n return [true, raw];\n }\n}\n\n// ─── Default application ─────────────────────────────────────────────────────\n\n/**\n * Returns the default value for a variable in the given environment,\n * or undefined if no default applies.\n *\n * Exact env match only — defaults are per-environment and MUST NOT bleed\n * across envs. (A local default stays local; it does not fall back into prod.)\n */\nfunction resolveDefault(\n spec: VariableSpec,\n env: string,\n): string | undefined {\n if (!spec.default) return undefined;\n const v = spec.default[env];\n if (v === undefined) return undefined;\n return String(v);\n}\n\n// ─── validateAgainstContract ─────────────────────────────────────────────────\n\n/**\n * Parse `runtimeYamlPath`, coerce every runtime-phase variable from\n * `process.env` (with per-env defaults applied), and fail fast on any\n * missing or invalid required variable (R3.2).\n *\n * Build-phase variables (phase: build) are skipped per R3.4.\n *\n * Returns a typed config object keyed by variable name.\n */\nexport function validateAgainstContract(\n runtimeYamlPath: string,\n opts: ValidateOptions = {},\n): TypedConfig {\n const contract = loadContract(runtimeYamlPath);\n const env =\n opts.env ??\n (process.env.NODE_ENV as string | undefined) ??\n \"local\";\n\n const errors: string[] = [];\n const result: TypedConfig = {};\n\n for (const [key, spec] of Object.entries(contract.variables)) {\n // R3.4: skip build-phase variables entirely at runtime.\n if (spec.phase === \"build\") continue;\n\n const rawFromEnv = process.env[key];\n const defaultValue = resolveDefault(spec, env);\n const effective = rawFromEnv ?? defaultValue;\n\n if (effective === undefined || effective === \"\") {\n if (spec.required) {\n errors.push(\n `${key}: required but not set (no value in process.env and no default for env \"${env}\")`,\n );\n }\n // Not required and not set — omit from result.\n continue;\n }\n\n const [ok, coerced] = coerce(key, effective, spec);\n if (!ok) {\n errors.push(coerced as string);\n continue;\n }\n result[key] = coerced;\n }\n\n if (errors.length > 0) {\n const message = [\n `[platform-common/config] validateAgainstContract failed for ${runtimeYamlPath}`,\n `${errors.length} variable(s) missing or invalid:`,\n ...errors.map((e) => ` - ${e}`),\n ].join(\"\\n\");\n\n if (opts.throwOnFailure) {\n throw new Error(message);\n }\n console.error(message);\n process.exit(1);\n }\n\n return result;\n}\n\n// ─── createConfigEndpoint ────────────────────────────────────────────────────\n\n/**\n * Build a static JSON payload containing only variables that are\n * client_visible: true AND secret: false (R7.2, R7.3). Reads process.env\n * once at factory call time.\n */\nfunction buildClientPayload(\n contract: ServiceContract,\n env: string,\n): Record<string, unknown> {\n const payload: Record<string, unknown> = {};\n\n for (const [key, spec] of Object.entries(contract.variables)) {\n // R7.3: never expose secrets.\n if (spec.secret) continue;\n // R7.2: only expose client_visible vars.\n if (!spec.client_visible) continue;\n // R3.4: build-phase vars are not available at runtime.\n if (spec.phase === \"build\") continue;\n\n const raw = process.env[key] ?? resolveDefault(spec, env);\n if (raw === undefined) continue;\n\n const [ok, coerced] = coerce(key, raw, spec);\n payload[key] = ok ? coerced : raw;\n }\n\n return payload;\n}\n\n/**\n * Route-handler factory for GET /api/config (R7.1).\n *\n * Reads the contract and process.env once at factory-call time and caches\n * the JSON payload. The returned handler is compatible with:\n *\n * Next.js App Router:\n * export const GET = createConfigEndpoint(path);\n *\n * Fastify:\n * instance.get('/api/config', createConfigEndpoint(path));\n *\n * Express:\n * app.get('/api/config', createConfigEndpoint(path));\n *\n * The handler detects the calling convention at runtime:\n * - Next.js / fetch-native: called with no arguments; returns a Response.\n * - Express: called with (req, res); calls res.json() and returns void.\n * - Fastify: called with (req, reply); calls reply.send() and returns void.\n */\nexport function createConfigEndpoint(\n runtimeYamlPath: string,\n opts: EndpointOptions = {},\n): RouteHandler {\n const contract = loadContract(runtimeYamlPath);\n const env =\n (process.env.NODE_ENV as string | undefined) ?? \"local\";\n const payload = buildClientPayload(contract, env);\n const cacheControl = opts.cacheControl ?? \"private, no-store\";\n const body = JSON.stringify(payload);\n\n return function configHandler(\n _req?: unknown,\n res?: unknown,\n ): Promise<Response | void> | Response | void {\n // Express-shaped: res has .json()\n if (res && typeof (res as Record<string, unknown>)[\"json\"] === \"function\") {\n const r = res as {\n setHeader: (k: string, v: string) => void;\n json: (data: unknown) => void;\n };\n r.setHeader(\"Cache-Control\", cacheControl);\n r.setHeader(\"Content-Type\", \"application/json\");\n r.json(payload);\n return;\n }\n\n // Fastify-shaped: res has .send()\n if (res && typeof (res as Record<string, unknown>)[\"send\"] === \"function\") {\n const r = res as {\n header: (k: string, v: string) => void;\n type: (ct: string) => void;\n send: (data: string) => void;\n };\n r.header(\"Cache-Control\", cacheControl);\n r.type(\"application/json\");\n r.send(body);\n return;\n }\n\n // Next.js / fetch-native (no res argument, or unrecognised res)\n return new Response(body, {\n status: 200,\n headers: {\n \"Content-Type\": \"application/json\",\n \"Cache-Control\": cacheControl,\n },\n });\n };\n}\n"],"mappings":"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","names":[]}
1
+ {"version":3,"sources":["../../src/config/index.ts"],"sourcesContent":["/**\n * @htilabs/platform-common-models — Runtime Config Contract Validator\n *\n * Implements contract R12.1 (platform-common home):\n * - validateAgainstContract(runtimeYamlPath, opts?) — startup validator (R3.2)\n * - createConfigEndpoint(runtimeYamlPath, opts?) — /api/config factory (R7)\n *\n * Consumers MUST call validateAgainstContract once at process startup, before\n * any other initialization that reads env vars. Build-phase variables\n * (phase: build) are NOT checked at runtime per R3.4.\n *\n * No secret VALUES are read, stored, or returned here. Secret env vars are\n * validated for presence but their values are never logged or exposed.\n *\n * Dual ESM + CJS via tsup. Plain JS consumers (pave, leads) use require():\n * const { validateAgainstContract } = require('@htilabs/platform-common-models/config');\n */\n\nimport { readFileSync } from \"node:fs\";\nimport { parse } from \"yaml\";\n\n// ─── Schema types (mirrors thread's runtime-config-lib.ts VariableSpec) ──────\n\nexport interface VariableSpec {\n type: \"string\" | \"boolean\" | \"number\" | \"enum\" | \"url\" | \"json\";\n required: boolean;\n secret: boolean;\n description: string;\n phase?: \"runtime\" | \"build\";\n values?: string[];\n default?: Record<string, unknown>;\n provider?: string;\n name?: string;\n client_visible?: boolean;\n deprecated?: { since: string; remove_after?: string; replacement?: string };\n}\n\nexport interface ServiceContract {\n service: string;\n version: number;\n environments: string[];\n // Thread extensions (tolerated, not required — R1.1 note)\n port?: number;\n build_secrets?: string[];\n variables: Record<string, VariableSpec>;\n /**\n * Optional MongoDB declaration consumed by `@htilabs/platform-common-models/mongo`.\n * Left untyped here to keep `config` free of a dependency on `mongo`; the\n * verifier validates its shape via `parseMongoBlock`.\n */\n mongo?: unknown;\n}\n\n/** Typed config accessor returned by validateAgainstContract. */\nexport type TypedConfig = Record<string, string | boolean | number | unknown>;\n\nexport interface ValidateOptions {\n /**\n * Environment name used to select per-env defaults (e.g. \"local\", \"test\").\n * Defaults to process.env.NODE_ENV, then \"local\".\n */\n env?: string;\n /**\n * If true, do not call process.exit(1) on failure; throw instead.\n * Useful for tests. Defaults to false (production mode exits).\n */\n throwOnFailure?: boolean;\n}\n\nexport interface EndpointOptions {\n /** Cache-Control header value. Defaults to \"private, no-store\". */\n cacheControl?: string;\n}\n\n/**\n * A framework-agnostic route handler that returns a JSON response.\n * Compatible with:\n * - Next.js App Router: export const GET = createConfigEndpoint(...)\n * - Fastify: instance.get('/api/config', createConfigEndpoint(...))\n * - Express: app.get('/api/config', createConfigEndpoint(...))\n */\nexport type RouteHandler = (\n req?: unknown,\n res?: unknown,\n) => Promise<Response | void> | Response | void;\n\n// ─── YAML parser ──────────────────────────────────────────────────────────────\n\nexport function loadContract(runtimeYamlPath: string): ServiceContract {\n let raw: string;\n try {\n raw = readFileSync(runtimeYamlPath, \"utf8\");\n } catch (err) {\n const msg =\n err instanceof Error ? err.message : String(err);\n throw new Error(\n `[platform-common/config] Cannot read ${runtimeYamlPath}: ${msg}`,\n );\n }\n const parsed = parse(raw) as ServiceContract | null;\n if (!parsed || typeof parsed !== \"object\") {\n throw new Error(\n `[platform-common/config] ${runtimeYamlPath}: not a YAML mapping`,\n );\n }\n if (parsed.version !== 1) {\n throw new Error(\n `[platform-common/config] ${runtimeYamlPath}: unsupported contract version ${parsed.version} (expected 1)`,\n );\n }\n if (!parsed.variables || typeof parsed.variables !== \"object\") {\n throw new Error(\n `[platform-common/config] ${runtimeYamlPath}: missing \"variables\" map`,\n );\n }\n return parsed;\n}\n\n// ─── Coercion ────────────────────────────────────────────────────────────────\n\n/**\n * Coerce a raw environment string value to the declared type.\n * Returns [ok, coerced] or [false, errorMessage].\n */\nfunction coerce(\n key: string,\n raw: string,\n spec: VariableSpec,\n): [true, unknown] | [false, string] {\n switch (spec.type) {\n case \"boolean\": {\n if (raw === \"true\" || raw === \"1\") return [true, true];\n if (raw === \"false\" || raw === \"0\") return [true, false];\n return [false, `${key}: expected boolean (\"true\"/\"false\"/\"1\"/\"0\"), got \"${raw}\"`];\n }\n case \"number\": {\n const n = Number(raw);\n if (!Number.isFinite(n)) {\n return [false, `${key}: expected number, got \"${raw}\"`];\n }\n return [true, n];\n }\n case \"enum\": {\n const vals = spec.values ?? [];\n if (!vals.includes(raw)) {\n return [false, `${key}: expected one of [${vals.join(\", \")}], got \"${raw}\"`];\n }\n return [true, raw];\n }\n case \"url\": {\n try {\n new URL(raw);\n return [true, raw];\n } catch {\n return [false, `${key}: expected a valid URL, got \"${raw}\"`];\n }\n }\n case \"json\": {\n try {\n const parsed = JSON.parse(raw) as unknown;\n return [true, parsed];\n } catch {\n return [false, `${key}: expected valid JSON, got \"${raw}\"`];\n }\n }\n default:\n // string\n return [true, raw];\n }\n}\n\n// ─── Default application ─────────────────────────────────────────────────────\n\n/**\n * Returns the default value for a variable in the given environment,\n * or undefined if no default applies.\n *\n * Exact env match only — defaults are per-environment and MUST NOT bleed\n * across envs. (A local default stays local; it does not fall back into prod.)\n */\nexport function resolveDefault(\n spec: VariableSpec,\n env: string,\n): string | undefined {\n if (!spec.default) return undefined;\n const v = spec.default[env];\n if (v === undefined) return undefined;\n return String(v);\n}\n\n// ─── validateAgainstContract ─────────────────────────────────────────────────\n\n/**\n * Parse `runtimeYamlPath`, coerce every runtime-phase variable from\n * `process.env` (with per-env defaults applied), and fail fast on any\n * missing or invalid required variable (R3.2).\n *\n * Build-phase variables (phase: build) are skipped per R3.4.\n *\n * Returns a typed config object keyed by variable name.\n */\nexport function validateAgainstContract(\n runtimeYamlPath: string,\n opts: ValidateOptions = {},\n): TypedConfig {\n const contract = loadContract(runtimeYamlPath);\n const env =\n opts.env ??\n (process.env.NODE_ENV as string | undefined) ??\n \"local\";\n\n const errors: string[] = [];\n const result: TypedConfig = {};\n\n for (const [key, spec] of Object.entries(contract.variables)) {\n // R3.4: skip build-phase variables entirely at runtime.\n if (spec.phase === \"build\") continue;\n\n const rawFromEnv = process.env[key];\n const defaultValue = resolveDefault(spec, env);\n const effective = rawFromEnv ?? defaultValue;\n\n if (effective === undefined || effective === \"\") {\n if (spec.required) {\n errors.push(\n `${key}: required but not set (no value in process.env and no default for env \"${env}\")`,\n );\n }\n // Not required and not set — omit from result.\n continue;\n }\n\n const [ok, coerced] = coerce(key, effective, spec);\n if (!ok) {\n errors.push(coerced as string);\n continue;\n }\n result[key] = coerced;\n }\n\n if (errors.length > 0) {\n const message = [\n `[platform-common/config] validateAgainstContract failed for ${runtimeYamlPath}`,\n `${errors.length} variable(s) missing or invalid:`,\n ...errors.map((e) => ` - ${e}`),\n ].join(\"\\n\");\n\n if (opts.throwOnFailure) {\n throw new Error(message);\n }\n console.error(message);\n process.exit(1);\n }\n\n return result;\n}\n\n// ─── createConfigEndpoint ────────────────────────────────────────────────────\n\n/**\n * Build a static JSON payload containing only variables that are\n * client_visible: true AND secret: false (R7.2, R7.3). Reads process.env\n * once at factory call time.\n */\nfunction buildClientPayload(\n contract: ServiceContract,\n env: string,\n): Record<string, unknown> {\n const payload: Record<string, unknown> = {};\n\n for (const [key, spec] of Object.entries(contract.variables)) {\n // R7.3: never expose secrets.\n if (spec.secret) continue;\n // R7.2: only expose client_visible vars.\n if (!spec.client_visible) continue;\n // R3.4: build-phase vars are not available at runtime.\n if (spec.phase === \"build\") continue;\n\n const raw = process.env[key] ?? resolveDefault(spec, env);\n if (raw === undefined) continue;\n\n const [ok, coerced] = coerce(key, raw, spec);\n payload[key] = ok ? coerced : raw;\n }\n\n return payload;\n}\n\n/**\n * Route-handler factory for GET /api/config (R7.1).\n *\n * Reads the contract and process.env once at factory-call time and caches\n * the JSON payload. The returned handler is compatible with:\n *\n * Next.js App Router:\n * export const GET = createConfigEndpoint(path);\n *\n * Fastify:\n * instance.get('/api/config', createConfigEndpoint(path));\n *\n * Express:\n * app.get('/api/config', createConfigEndpoint(path));\n *\n * The handler detects the calling convention at runtime:\n * - Next.js / fetch-native: called with no arguments; returns a Response.\n * - Express: called with (req, res); calls res.json() and returns void.\n * - Fastify: called with (req, reply); calls reply.send() and returns void.\n */\nexport function createConfigEndpoint(\n runtimeYamlPath: string,\n opts: EndpointOptions = {},\n): RouteHandler {\n const contract = loadContract(runtimeYamlPath);\n const env =\n (process.env.NODE_ENV as string | undefined) ?? \"local\";\n const payload = buildClientPayload(contract, env);\n const cacheControl = opts.cacheControl ?? \"private, no-store\";\n const body = JSON.stringify(payload);\n\n return function configHandler(\n _req?: unknown,\n res?: unknown,\n ): Promise<Response | void> | Response | void {\n // Express-shaped: res has .json()\n if (res && typeof (res as Record<string, unknown>)[\"json\"] === \"function\") {\n const r = res as {\n setHeader: (k: string, v: string) => void;\n json: (data: unknown) => void;\n };\n r.setHeader(\"Cache-Control\", cacheControl);\n r.setHeader(\"Content-Type\", \"application/json\");\n r.json(payload);\n return;\n }\n\n // Fastify-shaped: res has .send()\n if (res && typeof (res as Record<string, unknown>)[\"send\"] === \"function\") {\n const r = res as {\n header: (k: string, v: string) => void;\n type: (ct: string) => void;\n send: (data: string) => void;\n };\n r.header(\"Cache-Control\", cacheControl);\n r.type(\"application/json\");\n r.send(body);\n return;\n }\n\n // Next.js / fetch-native (no res argument, or unrecognised res)\n return new Response(body, {\n status: 200,\n headers: {\n \"Content-Type\": \"application/json\",\n \"Cache-Control\": cacheControl,\n },\n });\n };\n}\n"],"mappings":"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","names":[]}
@@ -39,6 +39,12 @@ interface ServiceContract {
39
39
  port?: number;
40
40
  build_secrets?: string[];
41
41
  variables: Record<string, VariableSpec>;
42
+ /**
43
+ * Optional MongoDB declaration consumed by `@htilabs/platform-common-models/mongo`.
44
+ * Left untyped here to keep `config` free of a dependency on `mongo`; the
45
+ * verifier validates its shape via `parseMongoBlock`.
46
+ */
47
+ mongo?: unknown;
42
48
  }
43
49
  /** Typed config accessor returned by validateAgainstContract. */
44
50
  type TypedConfig = Record<string, string | boolean | number | unknown>;
@@ -66,6 +72,15 @@ interface EndpointOptions {
66
72
  * - Express: app.get('/api/config', createConfigEndpoint(...))
67
73
  */
68
74
  type RouteHandler = (req?: unknown, res?: unknown) => Promise<Response | void> | Response | void;
75
+ declare function loadContract(runtimeYamlPath: string): ServiceContract;
76
+ /**
77
+ * Returns the default value for a variable in the given environment,
78
+ * or undefined if no default applies.
79
+ *
80
+ * Exact env match only — defaults are per-environment and MUST NOT bleed
81
+ * across envs. (A local default stays local; it does not fall back into prod.)
82
+ */
83
+ declare function resolveDefault(spec: VariableSpec, env: string): string | undefined;
69
84
  /**
70
85
  * Parse `runtimeYamlPath`, coerce every runtime-phase variable from
71
86
  * `process.env` (with per-env defaults applied), and fail fast on any
@@ -98,4 +113,4 @@ declare function validateAgainstContract(runtimeYamlPath: string, opts?: Validat
98
113
  */
99
114
  declare function createConfigEndpoint(runtimeYamlPath: string, opts?: EndpointOptions): RouteHandler;
100
115
 
101
- export { type EndpointOptions, type RouteHandler, type ServiceContract, type TypedConfig, type ValidateOptions, type VariableSpec, createConfigEndpoint, validateAgainstContract };
116
+ export { type EndpointOptions, type RouteHandler, type ServiceContract, type TypedConfig, type ValidateOptions, type VariableSpec, createConfigEndpoint, loadContract, resolveDefault, validateAgainstContract };
@@ -39,6 +39,12 @@ interface ServiceContract {
39
39
  port?: number;
40
40
  build_secrets?: string[];
41
41
  variables: Record<string, VariableSpec>;
42
+ /**
43
+ * Optional MongoDB declaration consumed by `@htilabs/platform-common-models/mongo`.
44
+ * Left untyped here to keep `config` free of a dependency on `mongo`; the
45
+ * verifier validates its shape via `parseMongoBlock`.
46
+ */
47
+ mongo?: unknown;
42
48
  }
43
49
  /** Typed config accessor returned by validateAgainstContract. */
44
50
  type TypedConfig = Record<string, string | boolean | number | unknown>;
@@ -66,6 +72,15 @@ interface EndpointOptions {
66
72
  * - Express: app.get('/api/config', createConfigEndpoint(...))
67
73
  */
68
74
  type RouteHandler = (req?: unknown, res?: unknown) => Promise<Response | void> | Response | void;
75
+ declare function loadContract(runtimeYamlPath: string): ServiceContract;
76
+ /**
77
+ * Returns the default value for a variable in the given environment,
78
+ * or undefined if no default applies.
79
+ *
80
+ * Exact env match only — defaults are per-environment and MUST NOT bleed
81
+ * across envs. (A local default stays local; it does not fall back into prod.)
82
+ */
83
+ declare function resolveDefault(spec: VariableSpec, env: string): string | undefined;
69
84
  /**
70
85
  * Parse `runtimeYamlPath`, coerce every runtime-phase variable from
71
86
  * `process.env` (with per-env defaults applied), and fail fast on any
@@ -98,4 +113,4 @@ declare function validateAgainstContract(runtimeYamlPath: string, opts?: Validat
98
113
  */
99
114
  declare function createConfigEndpoint(runtimeYamlPath: string, opts?: EndpointOptions): RouteHandler;
100
115
 
101
- export { type EndpointOptions, type RouteHandler, type ServiceContract, type TypedConfig, type ValidateOptions, type VariableSpec, createConfigEndpoint, validateAgainstContract };
116
+ export { type EndpointOptions, type RouteHandler, type ServiceContract, type TypedConfig, type ValidateOptions, type VariableSpec, createConfigEndpoint, loadContract, resolveDefault, validateAgainstContract };
@@ -160,6 +160,8 @@ function createConfigEndpoint(runtimeYamlPath, opts = {}) {
160
160
  }
161
161
  export {
162
162
  createConfigEndpoint,
163
+ loadContract,
164
+ resolveDefault,
163
165
  validateAgainstContract
164
166
  };
165
167
  //# sourceMappingURL=index.js.map
@@ -1 +1 @@
1
- {"version":3,"sources":["../../src/config/index.ts"],"sourcesContent":["/**\n * @htilabs/platform-common-models — Runtime Config Contract Validator\n *\n * Implements contract R12.1 (platform-common home):\n * - validateAgainstContract(runtimeYamlPath, opts?) — startup validator (R3.2)\n * - createConfigEndpoint(runtimeYamlPath, opts?) — /api/config factory (R7)\n *\n * Consumers MUST call validateAgainstContract once at process startup, before\n * any other initialization that reads env vars. Build-phase variables\n * (phase: build) are NOT checked at runtime per R3.4.\n *\n * No secret VALUES are read, stored, or returned here. Secret env vars are\n * validated for presence but their values are never logged or exposed.\n *\n * Dual ESM + CJS via tsup. Plain JS consumers (pave, leads) use require():\n * const { validateAgainstContract } = require('@htilabs/platform-common-models/config');\n */\n\nimport { readFileSync } from \"node:fs\";\nimport { parse } from \"yaml\";\n\n// ─── Schema types (mirrors thread's runtime-config-lib.ts VariableSpec) ──────\n\nexport interface VariableSpec {\n type: \"string\" | \"boolean\" | \"number\" | \"enum\" | \"url\" | \"json\";\n required: boolean;\n secret: boolean;\n description: string;\n phase?: \"runtime\" | \"build\";\n values?: string[];\n default?: Record<string, unknown>;\n provider?: string;\n name?: string;\n client_visible?: boolean;\n deprecated?: { since: string; remove_after?: string; replacement?: string };\n}\n\nexport interface ServiceContract {\n service: string;\n version: number;\n environments: string[];\n // Thread extensions (tolerated, not required — R1.1 note)\n port?: number;\n build_secrets?: string[];\n variables: Record<string, VariableSpec>;\n}\n\n/** Typed config accessor returned by validateAgainstContract. */\nexport type TypedConfig = Record<string, string | boolean | number | unknown>;\n\nexport interface ValidateOptions {\n /**\n * Environment name used to select per-env defaults (e.g. \"local\", \"test\").\n * Defaults to process.env.NODE_ENV, then \"local\".\n */\n env?: string;\n /**\n * If true, do not call process.exit(1) on failure; throw instead.\n * Useful for tests. Defaults to false (production mode exits).\n */\n throwOnFailure?: boolean;\n}\n\nexport interface EndpointOptions {\n /** Cache-Control header value. Defaults to \"private, no-store\". */\n cacheControl?: string;\n}\n\n/**\n * A framework-agnostic route handler that returns a JSON response.\n * Compatible with:\n * - Next.js App Router: export const GET = createConfigEndpoint(...)\n * - Fastify: instance.get('/api/config', createConfigEndpoint(...))\n * - Express: app.get('/api/config', createConfigEndpoint(...))\n */\nexport type RouteHandler = (\n req?: unknown,\n res?: unknown,\n) => Promise<Response | void> | Response | void;\n\n// ─── YAML parser ──────────────────────────────────────────────────────────────\n\nfunction loadContract(runtimeYamlPath: string): ServiceContract {\n let raw: string;\n try {\n raw = readFileSync(runtimeYamlPath, \"utf8\");\n } catch (err) {\n const msg =\n err instanceof Error ? err.message : String(err);\n throw new Error(\n `[platform-common/config] Cannot read ${runtimeYamlPath}: ${msg}`,\n );\n }\n const parsed = parse(raw) as ServiceContract | null;\n if (!parsed || typeof parsed !== \"object\") {\n throw new Error(\n `[platform-common/config] ${runtimeYamlPath}: not a YAML mapping`,\n );\n }\n if (parsed.version !== 1) {\n throw new Error(\n `[platform-common/config] ${runtimeYamlPath}: unsupported contract version ${parsed.version} (expected 1)`,\n );\n }\n if (!parsed.variables || typeof parsed.variables !== \"object\") {\n throw new Error(\n `[platform-common/config] ${runtimeYamlPath}: missing \"variables\" map`,\n );\n }\n return parsed;\n}\n\n// ─── Coercion ────────────────────────────────────────────────────────────────\n\n/**\n * Coerce a raw environment string value to the declared type.\n * Returns [ok, coerced] or [false, errorMessage].\n */\nfunction coerce(\n key: string,\n raw: string,\n spec: VariableSpec,\n): [true, unknown] | [false, string] {\n switch (spec.type) {\n case \"boolean\": {\n if (raw === \"true\" || raw === \"1\") return [true, true];\n if (raw === \"false\" || raw === \"0\") return [true, false];\n return [false, `${key}: expected boolean (\"true\"/\"false\"/\"1\"/\"0\"), got \"${raw}\"`];\n }\n case \"number\": {\n const n = Number(raw);\n if (!Number.isFinite(n)) {\n return [false, `${key}: expected number, got \"${raw}\"`];\n }\n return [true, n];\n }\n case \"enum\": {\n const vals = spec.values ?? [];\n if (!vals.includes(raw)) {\n return [false, `${key}: expected one of [${vals.join(\", \")}], got \"${raw}\"`];\n }\n return [true, raw];\n }\n case \"url\": {\n try {\n new URL(raw);\n return [true, raw];\n } catch {\n return [false, `${key}: expected a valid URL, got \"${raw}\"`];\n }\n }\n case \"json\": {\n try {\n const parsed = JSON.parse(raw) as unknown;\n return [true, parsed];\n } catch {\n return [false, `${key}: expected valid JSON, got \"${raw}\"`];\n }\n }\n default:\n // string\n return [true, raw];\n }\n}\n\n// ─── Default application ─────────────────────────────────────────────────────\n\n/**\n * Returns the default value for a variable in the given environment,\n * or undefined if no default applies.\n *\n * Exact env match only — defaults are per-environment and MUST NOT bleed\n * across envs. (A local default stays local; it does not fall back into prod.)\n */\nfunction resolveDefault(\n spec: VariableSpec,\n env: string,\n): string | undefined {\n if (!spec.default) return undefined;\n const v = spec.default[env];\n if (v === undefined) return undefined;\n return String(v);\n}\n\n// ─── validateAgainstContract ─────────────────────────────────────────────────\n\n/**\n * Parse `runtimeYamlPath`, coerce every runtime-phase variable from\n * `process.env` (with per-env defaults applied), and fail fast on any\n * missing or invalid required variable (R3.2).\n *\n * Build-phase variables (phase: build) are skipped per R3.4.\n *\n * Returns a typed config object keyed by variable name.\n */\nexport function validateAgainstContract(\n runtimeYamlPath: string,\n opts: ValidateOptions = {},\n): TypedConfig {\n const contract = loadContract(runtimeYamlPath);\n const env =\n opts.env ??\n (process.env.NODE_ENV as string | undefined) ??\n \"local\";\n\n const errors: string[] = [];\n const result: TypedConfig = {};\n\n for (const [key, spec] of Object.entries(contract.variables)) {\n // R3.4: skip build-phase variables entirely at runtime.\n if (spec.phase === \"build\") continue;\n\n const rawFromEnv = process.env[key];\n const defaultValue = resolveDefault(spec, env);\n const effective = rawFromEnv ?? defaultValue;\n\n if (effective === undefined || effective === \"\") {\n if (spec.required) {\n errors.push(\n `${key}: required but not set (no value in process.env and no default for env \"${env}\")`,\n );\n }\n // Not required and not set — omit from result.\n continue;\n }\n\n const [ok, coerced] = coerce(key, effective, spec);\n if (!ok) {\n errors.push(coerced as string);\n continue;\n }\n result[key] = coerced;\n }\n\n if (errors.length > 0) {\n const message = [\n `[platform-common/config] validateAgainstContract failed for ${runtimeYamlPath}`,\n `${errors.length} variable(s) missing or invalid:`,\n ...errors.map((e) => ` - ${e}`),\n ].join(\"\\n\");\n\n if (opts.throwOnFailure) {\n throw new Error(message);\n }\n console.error(message);\n process.exit(1);\n }\n\n return result;\n}\n\n// ─── createConfigEndpoint ────────────────────────────────────────────────────\n\n/**\n * Build a static JSON payload containing only variables that are\n * client_visible: true AND secret: false (R7.2, R7.3). Reads process.env\n * once at factory call time.\n */\nfunction buildClientPayload(\n contract: ServiceContract,\n env: string,\n): Record<string, unknown> {\n const payload: Record<string, unknown> = {};\n\n for (const [key, spec] of Object.entries(contract.variables)) {\n // R7.3: never expose secrets.\n if (spec.secret) continue;\n // R7.2: only expose client_visible vars.\n if (!spec.client_visible) continue;\n // R3.4: build-phase vars are not available at runtime.\n if (spec.phase === \"build\") continue;\n\n const raw = process.env[key] ?? resolveDefault(spec, env);\n if (raw === undefined) continue;\n\n const [ok, coerced] = coerce(key, raw, spec);\n payload[key] = ok ? coerced : raw;\n }\n\n return payload;\n}\n\n/**\n * Route-handler factory for GET /api/config (R7.1).\n *\n * Reads the contract and process.env once at factory-call time and caches\n * the JSON payload. The returned handler is compatible with:\n *\n * Next.js App Router:\n * export const GET = createConfigEndpoint(path);\n *\n * Fastify:\n * instance.get('/api/config', createConfigEndpoint(path));\n *\n * Express:\n * app.get('/api/config', createConfigEndpoint(path));\n *\n * The handler detects the calling convention at runtime:\n * - Next.js / fetch-native: called with no arguments; returns a Response.\n * - Express: called with (req, res); calls res.json() and returns void.\n * - Fastify: called with (req, reply); calls reply.send() and returns void.\n */\nexport function createConfigEndpoint(\n runtimeYamlPath: string,\n opts: EndpointOptions = {},\n): RouteHandler {\n const contract = loadContract(runtimeYamlPath);\n const env =\n (process.env.NODE_ENV as string | undefined) ?? \"local\";\n const payload = buildClientPayload(contract, env);\n const cacheControl = opts.cacheControl ?? \"private, no-store\";\n const body = JSON.stringify(payload);\n\n return function configHandler(\n _req?: unknown,\n res?: unknown,\n ): Promise<Response | void> | Response | void {\n // Express-shaped: res has .json()\n if (res && typeof (res as Record<string, unknown>)[\"json\"] === \"function\") {\n const r = res as {\n setHeader: (k: string, v: string) => void;\n json: (data: unknown) => void;\n };\n r.setHeader(\"Cache-Control\", cacheControl);\n r.setHeader(\"Content-Type\", \"application/json\");\n r.json(payload);\n return;\n }\n\n // Fastify-shaped: res has .send()\n if (res && typeof (res as Record<string, unknown>)[\"send\"] === \"function\") {\n const r = res as {\n header: (k: string, v: string) => void;\n type: (ct: string) => void;\n send: (data: string) => void;\n };\n r.header(\"Cache-Control\", cacheControl);\n r.type(\"application/json\");\n r.send(body);\n return;\n }\n\n // Next.js / fetch-native (no res argument, or unrecognised res)\n return new Response(body, {\n status: 200,\n headers: {\n \"Content-Type\": \"application/json\",\n \"Cache-Control\": cacheControl,\n },\n });\n };\n}\n"],"mappings":"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","names":[]}
1
+ {"version":3,"sources":["../../src/config/index.ts"],"sourcesContent":["/**\n * @htilabs/platform-common-models — Runtime Config Contract Validator\n *\n * Implements contract R12.1 (platform-common home):\n * - validateAgainstContract(runtimeYamlPath, opts?) — startup validator (R3.2)\n * - createConfigEndpoint(runtimeYamlPath, opts?) — /api/config factory (R7)\n *\n * Consumers MUST call validateAgainstContract once at process startup, before\n * any other initialization that reads env vars. Build-phase variables\n * (phase: build) are NOT checked at runtime per R3.4.\n *\n * No secret VALUES are read, stored, or returned here. Secret env vars are\n * validated for presence but their values are never logged or exposed.\n *\n * Dual ESM + CJS via tsup. Plain JS consumers (pave, leads) use require():\n * const { validateAgainstContract } = require('@htilabs/platform-common-models/config');\n */\n\nimport { readFileSync } from \"node:fs\";\nimport { parse } from \"yaml\";\n\n// ─── Schema types (mirrors thread's runtime-config-lib.ts VariableSpec) ──────\n\nexport interface VariableSpec {\n type: \"string\" | \"boolean\" | \"number\" | \"enum\" | \"url\" | \"json\";\n required: boolean;\n secret: boolean;\n description: string;\n phase?: \"runtime\" | \"build\";\n values?: string[];\n default?: Record<string, unknown>;\n provider?: string;\n name?: string;\n client_visible?: boolean;\n deprecated?: { since: string; remove_after?: string; replacement?: string };\n}\n\nexport interface ServiceContract {\n service: string;\n version: number;\n environments: string[];\n // Thread extensions (tolerated, not required — R1.1 note)\n port?: number;\n build_secrets?: string[];\n variables: Record<string, VariableSpec>;\n /**\n * Optional MongoDB declaration consumed by `@htilabs/platform-common-models/mongo`.\n * Left untyped here to keep `config` free of a dependency on `mongo`; the\n * verifier validates its shape via `parseMongoBlock`.\n */\n mongo?: unknown;\n}\n\n/** Typed config accessor returned by validateAgainstContract. */\nexport type TypedConfig = Record<string, string | boolean | number | unknown>;\n\nexport interface ValidateOptions {\n /**\n * Environment name used to select per-env defaults (e.g. \"local\", \"test\").\n * Defaults to process.env.NODE_ENV, then \"local\".\n */\n env?: string;\n /**\n * If true, do not call process.exit(1) on failure; throw instead.\n * Useful for tests. Defaults to false (production mode exits).\n */\n throwOnFailure?: boolean;\n}\n\nexport interface EndpointOptions {\n /** Cache-Control header value. Defaults to \"private, no-store\". */\n cacheControl?: string;\n}\n\n/**\n * A framework-agnostic route handler that returns a JSON response.\n * Compatible with:\n * - Next.js App Router: export const GET = createConfigEndpoint(...)\n * - Fastify: instance.get('/api/config', createConfigEndpoint(...))\n * - Express: app.get('/api/config', createConfigEndpoint(...))\n */\nexport type RouteHandler = (\n req?: unknown,\n res?: unknown,\n) => Promise<Response | void> | Response | void;\n\n// ─── YAML parser ──────────────────────────────────────────────────────────────\n\nexport function loadContract(runtimeYamlPath: string): ServiceContract {\n let raw: string;\n try {\n raw = readFileSync(runtimeYamlPath, \"utf8\");\n } catch (err) {\n const msg =\n err instanceof Error ? err.message : String(err);\n throw new Error(\n `[platform-common/config] Cannot read ${runtimeYamlPath}: ${msg}`,\n );\n }\n const parsed = parse(raw) as ServiceContract | null;\n if (!parsed || typeof parsed !== \"object\") {\n throw new Error(\n `[platform-common/config] ${runtimeYamlPath}: not a YAML mapping`,\n );\n }\n if (parsed.version !== 1) {\n throw new Error(\n `[platform-common/config] ${runtimeYamlPath}: unsupported contract version ${parsed.version} (expected 1)`,\n );\n }\n if (!parsed.variables || typeof parsed.variables !== \"object\") {\n throw new Error(\n `[platform-common/config] ${runtimeYamlPath}: missing \"variables\" map`,\n );\n }\n return parsed;\n}\n\n// ─── Coercion ────────────────────────────────────────────────────────────────\n\n/**\n * Coerce a raw environment string value to the declared type.\n * Returns [ok, coerced] or [false, errorMessage].\n */\nfunction coerce(\n key: string,\n raw: string,\n spec: VariableSpec,\n): [true, unknown] | [false, string] {\n switch (spec.type) {\n case \"boolean\": {\n if (raw === \"true\" || raw === \"1\") return [true, true];\n if (raw === \"false\" || raw === \"0\") return [true, false];\n return [false, `${key}: expected boolean (\"true\"/\"false\"/\"1\"/\"0\"), got \"${raw}\"`];\n }\n case \"number\": {\n const n = Number(raw);\n if (!Number.isFinite(n)) {\n return [false, `${key}: expected number, got \"${raw}\"`];\n }\n return [true, n];\n }\n case \"enum\": {\n const vals = spec.values ?? [];\n if (!vals.includes(raw)) {\n return [false, `${key}: expected one of [${vals.join(\", \")}], got \"${raw}\"`];\n }\n return [true, raw];\n }\n case \"url\": {\n try {\n new URL(raw);\n return [true, raw];\n } catch {\n return [false, `${key}: expected a valid URL, got \"${raw}\"`];\n }\n }\n case \"json\": {\n try {\n const parsed = JSON.parse(raw) as unknown;\n return [true, parsed];\n } catch {\n return [false, `${key}: expected valid JSON, got \"${raw}\"`];\n }\n }\n default:\n // string\n return [true, raw];\n }\n}\n\n// ─── Default application ─────────────────────────────────────────────────────\n\n/**\n * Returns the default value for a variable in the given environment,\n * or undefined if no default applies.\n *\n * Exact env match only — defaults are per-environment and MUST NOT bleed\n * across envs. (A local default stays local; it does not fall back into prod.)\n */\nexport function resolveDefault(\n spec: VariableSpec,\n env: string,\n): string | undefined {\n if (!spec.default) return undefined;\n const v = spec.default[env];\n if (v === undefined) return undefined;\n return String(v);\n}\n\n// ─── validateAgainstContract ─────────────────────────────────────────────────\n\n/**\n * Parse `runtimeYamlPath`, coerce every runtime-phase variable from\n * `process.env` (with per-env defaults applied), and fail fast on any\n * missing or invalid required variable (R3.2).\n *\n * Build-phase variables (phase: build) are skipped per R3.4.\n *\n * Returns a typed config object keyed by variable name.\n */\nexport function validateAgainstContract(\n runtimeYamlPath: string,\n opts: ValidateOptions = {},\n): TypedConfig {\n const contract = loadContract(runtimeYamlPath);\n const env =\n opts.env ??\n (process.env.NODE_ENV as string | undefined) ??\n \"local\";\n\n const errors: string[] = [];\n const result: TypedConfig = {};\n\n for (const [key, spec] of Object.entries(contract.variables)) {\n // R3.4: skip build-phase variables entirely at runtime.\n if (spec.phase === \"build\") continue;\n\n const rawFromEnv = process.env[key];\n const defaultValue = resolveDefault(spec, env);\n const effective = rawFromEnv ?? defaultValue;\n\n if (effective === undefined || effective === \"\") {\n if (spec.required) {\n errors.push(\n `${key}: required but not set (no value in process.env and no default for env \"${env}\")`,\n );\n }\n // Not required and not set — omit from result.\n continue;\n }\n\n const [ok, coerced] = coerce(key, effective, spec);\n if (!ok) {\n errors.push(coerced as string);\n continue;\n }\n result[key] = coerced;\n }\n\n if (errors.length > 0) {\n const message = [\n `[platform-common/config] validateAgainstContract failed for ${runtimeYamlPath}`,\n `${errors.length} variable(s) missing or invalid:`,\n ...errors.map((e) => ` - ${e}`),\n ].join(\"\\n\");\n\n if (opts.throwOnFailure) {\n throw new Error(message);\n }\n console.error(message);\n process.exit(1);\n }\n\n return result;\n}\n\n// ─── createConfigEndpoint ────────────────────────────────────────────────────\n\n/**\n * Build a static JSON payload containing only variables that are\n * client_visible: true AND secret: false (R7.2, R7.3). Reads process.env\n * once at factory call time.\n */\nfunction buildClientPayload(\n contract: ServiceContract,\n env: string,\n): Record<string, unknown> {\n const payload: Record<string, unknown> = {};\n\n for (const [key, spec] of Object.entries(contract.variables)) {\n // R7.3: never expose secrets.\n if (spec.secret) continue;\n // R7.2: only expose client_visible vars.\n if (!spec.client_visible) continue;\n // R3.4: build-phase vars are not available at runtime.\n if (spec.phase === \"build\") continue;\n\n const raw = process.env[key] ?? resolveDefault(spec, env);\n if (raw === undefined) continue;\n\n const [ok, coerced] = coerce(key, raw, spec);\n payload[key] = ok ? coerced : raw;\n }\n\n return payload;\n}\n\n/**\n * Route-handler factory for GET /api/config (R7.1).\n *\n * Reads the contract and process.env once at factory-call time and caches\n * the JSON payload. The returned handler is compatible with:\n *\n * Next.js App Router:\n * export const GET = createConfigEndpoint(path);\n *\n * Fastify:\n * instance.get('/api/config', createConfigEndpoint(path));\n *\n * Express:\n * app.get('/api/config', createConfigEndpoint(path));\n *\n * The handler detects the calling convention at runtime:\n * - Next.js / fetch-native: called with no arguments; returns a Response.\n * - Express: called with (req, res); calls res.json() and returns void.\n * - Fastify: called with (req, reply); calls reply.send() and returns void.\n */\nexport function createConfigEndpoint(\n runtimeYamlPath: string,\n opts: EndpointOptions = {},\n): RouteHandler {\n const contract = loadContract(runtimeYamlPath);\n const env =\n (process.env.NODE_ENV as string | undefined) ?? \"local\";\n const payload = buildClientPayload(contract, env);\n const cacheControl = opts.cacheControl ?? \"private, no-store\";\n const body = JSON.stringify(payload);\n\n return function configHandler(\n _req?: unknown,\n res?: unknown,\n ): Promise<Response | void> | Response | void {\n // Express-shaped: res has .json()\n if (res && typeof (res as Record<string, unknown>)[\"json\"] === \"function\") {\n const r = res as {\n setHeader: (k: string, v: string) => void;\n json: (data: unknown) => void;\n };\n r.setHeader(\"Cache-Control\", cacheControl);\n r.setHeader(\"Content-Type\", \"application/json\");\n r.json(payload);\n return;\n }\n\n // Fastify-shaped: res has .send()\n if (res && typeof (res as Record<string, unknown>)[\"send\"] === \"function\") {\n const r = res as {\n header: (k: string, v: string) => void;\n type: (ct: string) => void;\n send: (data: string) => void;\n };\n r.header(\"Cache-Control\", cacheControl);\n r.type(\"application/json\");\n r.send(body);\n return;\n }\n\n // Next.js / fetch-native (no res argument, or unrecognised res)\n return new Response(body, {\n status: 200,\n headers: {\n \"Content-Type\": \"application/json\",\n \"Cache-Control\": cacheControl,\n },\n });\n };\n}\n"],"mappings":"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","names":[]}
@@ -4220,6 +4220,7 @@ var CVC_136_CORE_INDICATOR_VALUES = [
4220
4220
  "cannot_stop_working_or_freely_leave",
4221
4221
  "child_not_abusers_in_household",
4222
4222
  "child_welfare_system_involvement",
4223
+ "clients_unaware_of_third_party_coordination",
4223
4224
  "coerced_to_misrepresent_identity_or_activity",
4224
4225
  "coercive_debt_pressure",
4225
4226
  "coercive_debt_pressure_youth",
@@ -4242,6 +4243,7 @@ var CVC_136_CORE_INDICATOR_VALUES = [
4242
4243
  "debt_terms_deceptive_youth",
4243
4244
  "denied_basic_needs",
4244
4245
  "depends_on_employer_for_immigration_status",
4246
+ "depends_on_spouse_or_family_for_immigration_status",
4245
4247
  "does_not_control_finances_or_earnings",
4246
4248
  "does_not_control_identity_documents",
4247
4249
  "elevated_lethality_risk_signal",
@@ -4335,6 +4337,8 @@ var CVC_136_CORE_INDICATOR_VALUES = [
4335
4337
  "several_cell_phones_or_frequent_number_changes",
4336
4338
  "sex_acts_in_own_residence",
4337
4339
  "sexual_exploitation",
4340
+ "sexualized_content_in_person_performance_activity",
4341
+ "sexualized_content_online_performance_activity",
4338
4342
  "sexualized_content_performance_activity",
4339
4343
  "shared_contact_network",
4340
4344
  "signs_of_physical_abuse_confinement_or_neglect",
@@ -4380,6 +4384,7 @@ var CVC_136_CORE_INDICATOR_VALUES = [
4380
4384
  "trafficking_experience_past_10plusy",
4381
4385
  "trafficking_experience_past_3to10y",
4382
4386
  "trafficking_experience_past_lt3y",
4387
+ "trauma_perpetrator_is_current_manager",
4383
4388
  "travel_organized_by_third_party",
4384
4389
  "tricked_or_pressured_into_unwanted_acts",
4385
4390
  "under_18_advertised_age",
@@ -4432,6 +4437,7 @@ var CVC_136_CORE_INDICATOR_LABELS = {
4432
4437
  "cannot_stop_working_or_freely_leave": "Cannot stop working or freely leave home/work",
4433
4438
  "child_not_abusers_in_household": "Child in household who is not the abuser's biological child",
4434
4439
  "child_welfare_system_involvement": "Child welfare system involvement (history)",
4440
+ "clients_unaware_of_third_party_coordination": "Clients unaware they are coordinating with a third party (concealed dispatch)",
4435
4441
  "coerced_to_misrepresent_identity_or_activity": "Coerced to misrepresent age, identity, or work activity to outsiders",
4436
4442
  "coercive_debt_pressure": "Pressured to do things to pay off debt (coercive debt repayment)",
4437
4443
  "coercive_debt_pressure_youth": "Pressured to do things to pay off debt (youth missing-from-care)",
@@ -4454,6 +4460,7 @@ var CVC_136_CORE_INDICATOR_LABELS = {
4454
4460
  "debt_terms_deceptive_youth": "Debt repayment terms differed from what was expected (youth missing-from-care)",
4455
4461
  "denied_basic_needs": "Denied basic needs (food, water, sleep, medical care)",
4456
4462
  "depends_on_employer_for_immigration_status": "Depends on employer for immigration status (tied visa / living with employer)",
4463
+ "depends_on_spouse_or_family_for_immigration_status": "Depends on spouse / family member for immigration status (tied family visa)",
4457
4464
  "does_not_control_finances_or_earnings": "Limited independence: does not control finances or earnings",
4458
4465
  "does_not_control_identity_documents": "Limited independence: does not control identity documents",
4459
4466
  "elevated_lethality_risk_signal": "Elevated lethality risk",
@@ -4547,6 +4554,8 @@ var CVC_136_CORE_INDICATOR_LABELS = {
4547
4554
  "several_cell_phones_or_frequent_number_changes": "Several cell phones or frequently changing phone number",
4548
4555
  "sex_acts_in_own_residence": "Sex acts take place in person's own residence",
4549
4556
  "sexual_exploitation": "Sexual exploitation (general)",
4557
+ "sexualized_content_in_person_performance_activity": "In-person sexualized performance / appearance-based activity",
4558
+ "sexualized_content_online_performance_activity": "Online sexual performance / interactive sexual content activity",
4550
4559
  "sexualized_content_performance_activity": "Sexualized content, performance, or communications activity",
4551
4560
  "shared_contact_network": "Shares a contact network (phones/handles)",
4552
4561
  "signs_of_physical_abuse_confinement_or_neglect": "Signs of physical abuse, confinement, or neglect (observed)",
@@ -4592,6 +4601,7 @@ var CVC_136_CORE_INDICATOR_LABELS = {
4592
4601
  "trafficking_experience_past_10plusy": "Trafficking experience recency: 10+ years since last experience",
4593
4602
  "trafficking_experience_past_3to10y": "Trafficking experience recency: 3\u201310 years since last experience",
4594
4603
  "trafficking_experience_past_lt3y": "Trafficking experience recency: less than 3 years since last experience",
4604
+ "trauma_perpetrator_is_current_manager": "Trauma perpetrator is a current manager / facilitator (trauma-bonded control)",
4595
4605
  "travel_organized_by_third_party": "Travel organized by a third party (sex provider does not control own movement)",
4596
4606
  "tricked_or_pressured_into_unwanted_acts": "Tricked or pressured into unwanted acts or activities (generic coercion)",
4597
4607
  "under_18_advertised_age": "Under 18 (ad-derived / advertised age)",