@htilabs/platform-common-models 0.12.0 → 0.12.1
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.
- package/dist/config/index.cjs +0 -81
- package/dist/config/index.cjs.map +1 -1
- package/dist/config/index.d.cts +4 -79
- package/dist/config/index.d.ts +4 -79
- package/dist/config/index.js +1 -79
- package/dist/config/index.js.map +1 -1
- package/dist/constants/index.cjs +18 -2
- package/dist/constants/index.cjs.map +1 -1
- package/dist/constants/index.d.cts +1 -1
- package/dist/constants/index.d.ts +1 -1
- package/dist/constants/index.js +18 -2
- package/dist/constants/index.js.map +1 -1
- package/dist/cvc-Cp4uWnAa.d.cts +298 -0
- package/dist/cvc-Cp4uWnAa.d.ts +298 -0
- package/dist/cvcs/index.cjs +6678 -221
- package/dist/cvcs/index.cjs.map +1 -1
- package/dist/cvcs/index.d.cts +15019 -8052
- package/dist/cvcs/index.d.ts +15019 -8052
- package/dist/cvcs/index.js +6666 -221
- package/dist/cvcs/index.js.map +1 -1
- package/dist/enums/index.cjs +4557 -0
- package/dist/enums/index.cjs.map +1 -0
- package/dist/enums/index.d.cts +5257 -0
- package/dist/enums/index.d.ts +5257 -0
- package/dist/enums/index.js +4354 -0
- package/dist/enums/index.js.map +1 -0
- package/dist/{index-I-DiX9eQ.d.ts → index-CDoqrfc1.d.ts} +1 -1
- package/dist/{index-CoVr1jIV.d.cts → index-Zu_mOJRn.d.cts} +1 -1
- package/dist/index.cjs +7219 -232
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +7 -4700
- package/dist/index.d.ts +7 -4700
- package/dist/index.js +7195 -232
- package/dist/index.js.map +1 -1
- package/dist/models/index.d.cts +2 -2
- package/dist/models/index.d.ts +2 -2
- package/dist/mongo/index.cjs +0 -1
- package/dist/mongo/index.cjs.map +1 -1
- package/dist/mongo/index.js +1 -2
- package/dist/mongo/index.js.map +1 -1
- package/dist/{platform-auth-v53r3BhN.d.cts → platform-auth-Dv5fu0Fh.d.cts} +5 -4
- package/dist/{platform-auth-v53r3BhN.d.ts → platform-auth-Dv5fu0Fh.d.ts} +5 -4
- package/dist/schemas/index.cjs +5 -1
- package/dist/schemas/index.cjs.map +1 -1
- package/dist/schemas/index.d.cts +25 -25
- package/dist/schemas/index.d.ts +25 -25
- package/dist/schemas/index.js +5 -1
- package/dist/schemas/index.js.map +1 -1
- package/dist/types/index.d.cts +2 -2
- package/dist/types/index.d.ts +2 -2
- package/dist/validation/index.cjs +58 -0
- package/dist/validation/index.cjs.map +1 -1
- package/dist/validation/index.d.cts +82 -283
- package/dist/validation/index.d.ts +82 -283
- package/dist/validation/index.js +57 -0
- package/dist/validation/index.js.map +1 -1
- package/package.json +10 -1
- package/src/__sot__/README.md +36 -1
- package/src/__sot__/coreIndicatorFields.ts +331 -0
- package/src/__sot__/coreIndicators.pin.json +1936 -2
- package/src/__sot__/cvcIndex.pin.json +8 -4
- package/src/__tests__/__snapshots__/cvc-sot.snap +41 -13
- package/src/__tests__/core-information-scope-invariant.test.ts +134 -0
- package/src/__tests__/cvc-136-scoring-invariant.test.ts +8 -3
- package/src/__tests__/cvc-181-182-country-parity.test.ts +163 -0
- package/src/__tests__/cvc-drift-gate.test.ts +445 -12
- package/src/__tests__/cvc-sot-snapshot.test.ts +73 -11
- package/src/__tests__/cvc-status-parser.test.ts +150 -0
- package/src/__tests__/cvc-structural.test.ts +14 -0
- package/src/__tests__/runtime-contract-validator.test.ts +1 -325
- package/src/config/index.ts +4 -189
- package/src/constants/ic.ts +120 -3
- package/src/cvcs/assertionDomain.v1.1.0.json +19 -1
- package/src/cvcs/assertionStatus.v1.0.0.json +80 -0
- package/src/cvcs/carCorrectionReason.v1.0.0.json +89 -0
- package/src/cvcs/caseShareState.v1.0.0.json +62 -0
- package/src/cvcs/coreIndicators.v1.0.0.json +83 -5
- package/src/cvcs/coreInformationScope.v1.0.0.json +1165 -0
- package/src/cvcs/countries.v1.0.0.json +3077 -0
- package/src/cvcs/createdBySystem.v1.0.0.json +89 -0
- package/src/cvcs/criminalOrgCategory.v1.0.0.json +116 -0
- package/src/cvcs/determinationHelperCategories.v1.0.0.json +1166 -0
- package/src/cvcs/incidentParticipationRoles.v1.0.0.json +11 -1
- package/src/cvcs/index.ts +32 -0
- package/src/cvcs/minorAdultStatus.v1.0.0.json +80 -0
- package/src/cvcs/personRelationships.v1.0.0.json +67 -2
- package/src/cvcs/referralOrigin.v1.0.0.json +26 -0
- package/src/cvcs/relationshipConcern.v1.0.0.json +28 -19
- package/src/cvcs/riskIdentificationMilestone.v1.0.0.json +109 -0
- package/src/cvcs/sessionTemplate.v1.0.0.json +22 -0
- package/src/cvcs/sharePurpose.v1.0.0.json +80 -12
- package/src/cvcs/subjectType.v1.0.0.json +80 -0
- package/src/generated/cvc-enums.ts +606 -20
- package/src/validation/cvcStatus.ts +209 -0
- package/src/validation/index.ts +1 -0
- package/dist/{cvcEntry-BCj1OWqL.d.cts → cvcEntry-0BIB9sen.d.cts} +8 -8
- package/dist/{cvcEntry-BCj1OWqL.d.ts → cvcEntry-0BIB9sen.d.ts} +8 -8
package/dist/models/index.d.cts
CHANGED
|
@@ -1,3 +1,3 @@
|
|
|
1
|
-
export { a as CvcEntry, b as CvcRegistry, F as Form, P as PlatformFunction, d as PlatformRole, Q as Question, f as ScoringRule, h as Section } from '../cvcEntry-
|
|
1
|
+
export { a as CvcEntry, b as CvcRegistry, F as Form, P as PlatformFunction, d as PlatformRole, Q as Question, f as ScoringRule, h as Section } from '../cvcEntry-0BIB9sen.cjs';
|
|
2
2
|
import 'mongoose';
|
|
3
|
-
export { C as CvcEntryDoc, a as CvcRegistryDoc, F as FormDoc, P as PlatformFunctionDoc, b as PlatformModels, c as PlatformRoleDoc, Q as QuestionDoc, S as ScoringRuleDoc, d as SectionDoc, g as createPlatformModels, h as cvcEntryModel, i as cvcRegistryModel, j as formModel, p as platformFunctionModel, k as platformRoleModel, q as questionModel, s as scoringRuleModel, l as sectionModel } from '../index-
|
|
3
|
+
export { C as CvcEntryDoc, a as CvcRegistryDoc, F as FormDoc, P as PlatformFunctionDoc, b as PlatformModels, c as PlatformRoleDoc, Q as QuestionDoc, S as ScoringRuleDoc, d as SectionDoc, g as createPlatformModels, h as cvcEntryModel, i as cvcRegistryModel, j as formModel, p as platformFunctionModel, k as platformRoleModel, q as questionModel, s as scoringRuleModel, l as sectionModel } from '../index-Zu_mOJRn.cjs';
|
package/dist/models/index.d.ts
CHANGED
|
@@ -1,3 +1,3 @@
|
|
|
1
|
-
export { a as CvcEntry, b as CvcRegistry, F as Form, P as PlatformFunction, d as PlatformRole, Q as Question, f as ScoringRule, h as Section } from '../cvcEntry-
|
|
1
|
+
export { a as CvcEntry, b as CvcRegistry, F as Form, P as PlatformFunction, d as PlatformRole, Q as Question, f as ScoringRule, h as Section } from '../cvcEntry-0BIB9sen.js';
|
|
2
2
|
import 'mongoose';
|
|
3
|
-
export { C as CvcEntryDoc, a as CvcRegistryDoc, F as FormDoc, P as PlatformFunctionDoc, b as PlatformModels, c as PlatformRoleDoc, Q as QuestionDoc, S as ScoringRuleDoc, d as SectionDoc, g as createPlatformModels, h as cvcEntryModel, i as cvcRegistryModel, j as formModel, p as platformFunctionModel, k as platformRoleModel, q as questionModel, s as scoringRuleModel, l as sectionModel } from '../index-
|
|
3
|
+
export { C as CvcEntryDoc, a as CvcRegistryDoc, F as FormDoc, P as PlatformFunctionDoc, b as PlatformModels, c as PlatformRoleDoc, Q as QuestionDoc, S as ScoringRuleDoc, d as SectionDoc, g as createPlatformModels, h as cvcEntryModel, i as cvcRegistryModel, j as formModel, p as platformFunctionModel, k as platformRoleModel, q as questionModel, s as scoringRuleModel, l as sectionModel } from '../index-CDoqrfc1.js';
|
package/dist/mongo/index.cjs
CHANGED
package/dist/mongo/index.cjs.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"sources":["../../src/mongo/index.ts","../../src/config/index.ts","../../src/mongo/contract.ts","../../src/mongo/similarity.ts","../../src/mongo/uri.ts","../../src/mongo/catalog.ts"],"sourcesContent":["/**\n * @htilabs/platform-common-models — MongoDB connection/collection verifier\n *\n * Sibling to `./config`. Where `validateAgainstContract` proves the env vars\n * are present and well-typed, `verifyMongo` proves they point somewhere real.\n *\n * ## What this catches\n * - a database name that does not exist and looks like a typo of one that does\n * - a collection name that does not exist and looks like a typo of one that does\n * - a database name that does not belong to the current environment\n * (env-affinity; needs no connection — generalizes thread's `assertTestDb`)\n * - collections present in MongoDB but undeclared by the service (reported)\n *\n * ## What this CANNOT catch\n * A plausible-but-wrong POPULATED database. `leads-platform-prod-test` exists\n * and carries the same collection names as `leads-platform-test`; every\n * name-existence check passes. Detecting that needs an identity marker\n * written inside the database, which is outside this utility's read-only\n * remit. Do not claim otherwise in adoption docs.\n *\n * ## Read-only\n * Reaches MongoDB solely through {@link MongoCatalog}: listDatabases and\n * listCollections. It never creates, writes, or drops anything.\n *\n * ## Severity\n * MongoDB creates namespaces lazily, so ABSENCE IS AMBIGUOUS (typo vs\n * unseeded environment). Absence alone warns; absence with a plausible\n * near-neighbour is fatal. See `similarity.ts`.\n *\n * FACT (verified 2026-07-10, read-only): thread registers the Mongoose model\n * `AgencyInfo` (collection `agencyinfos`), and that collection exists in\n * neither `platform-test` (15 collections) nor `platform-dev` (41). A\n * registered model with zero documents has no collection. The warn-on-absence\n * rule exists because of this; do not \"tighten\" it to fatal.\n */\n\nimport {\n loadContract,\n resolveDefault,\n type ServiceContract,\n} from \"../config/index.js\";\nimport {\n parseMongoBlock,\n checkEnvAffinity,\n type MongoContractBlock,\n type MongoDbSpec,\n} from \"./contract.js\";\nimport { nearestNames, formatSuggestions } from \"./similarity.js\";\nimport { parseDbName } from \"./uri.js\";\nimport type { MongoCatalog } from \"./catalog.js\";\n\nexport type { MongoCatalog, MongoClientLike, MongooseConnectionLike } from \"./catalog.js\";\nexport { catalogFromClient, catalogFromMongoose } from \"./catalog.js\";\nexport type { MongoContractBlock, MongoDbSpec, EnvAffinity } from \"./contract.js\";\nexport { parseDbName, isTestDb, TEST_DB_SUFFIX } from \"./uri.js\";\n\nconst TAG = \"[platform-common/mongo]\";\n\nexport type Severity = \"fatal\" | \"warn\";\n\nexport type FindingKind =\n | \"env_var_missing\"\n | \"db_shape_violation\"\n | \"db_absent_typo\"\n | \"db_absent_unseeded\"\n | \"collection_absent_typo\"\n | \"collection_absent_unseeded\"\n | \"collection_undeclared\";\n\nexport interface Finding {\n severity: Severity;\n kind: FindingKind;\n message: string;\n dbVar?: string;\n database?: string;\n collection?: string;\n /**\n * Existing names this looks like a typo of. More than one means the evidence\n * is ambiguous — the message lists them all rather than guessing.\n */\n suggestions?: string[];\n}\n\nexport interface MongoVerifyReport {\n /** True when no fatal finding was produced. Warnings do not clear `ok`. */\n ok: boolean;\n findings: Finding[];\n}\n\nexport interface VerifyMongoOptions {\n /** Read-only catalogue. Required — this package takes no driver dependency. */\n catalog: MongoCatalog;\n /** Environment name for affinity checks. Defaults to NODE_ENV, then \"local\". */\n env?: string;\n /** Env source. Defaults to `process.env`. */\n processEnv?: NodeJS.ProcessEnv;\n /** If true, throw instead of `exit(1)`. Defaults to false (production exits). */\n throwOnFailure?: boolean;\n /** Injected for tests. Defaults to `process.exit`. */\n exit?: (code: number) => never;\n /** Injected for tests. Defaults to `console`. */\n logger?: Pick<Console, \"error\" | \"warn\">;\n}\n\n/**\n * Resolve the database name for a spec, applying the same per-environment\n * defaults that `validateAgainstContract` applies. Reading `process.env` alone\n * would miss a value the contract supplies as a default (thread declares\n * `PLATFORM_DB.default.prod: platform-prod`) and report a false fatal.\n *\n * When `db_var` and `uri_var` name the same variable, the database is embedded\n * in the connection string (auth does this for `LEADS_MONGODB_URI` and\n * friends) and must be parsed out of it.\n *\n * A variable the contract marks `required: false` and that carries no value is\n * SKIPPED, not failed: thread's `PAVE_DB` is optional and its absence simply\n * means the read-only pave connection is not configured. Required-ness comes\n * from the contract so there is no second place to declare it.\n */\nfunction resolveDbName(\n spec: MongoDbSpec,\n contract: ServiceContract,\n env: string,\n processEnv: NodeJS.ProcessEnv,\n): { name?: string; error?: string; skip?: boolean } {\n const varSpec = contract.variables[spec.db_var];\n const raw =\n processEnv[spec.db_var] ??\n (varSpec ? resolveDefault(varSpec, env) : undefined);\n\n if (raw === undefined || raw === \"\") {\n // A variable absent from `variables` is treated as required: the mongo\n // block references something the contract never declared.\n if (varSpec && varSpec.required === false) return { skip: true };\n return { error: `${spec.db_var}: required by mongo contract but not set` };\n }\n\n if (spec.db_var !== spec.uri_var) return { name: raw };\n\n const parsed = parseDbName(raw);\n if (parsed === null) {\n return {\n error:\n `${spec.db_var}: connection string carries no database name. ` +\n `Either embed one (mongodb://host/<db>) or declare a separate db_var.`,\n };\n }\n return { name: parsed };\n}\n\nasync function verifyDatabase(\n spec: MongoDbSpec,\n dbName: string,\n block: MongoContractBlock,\n env: string,\n catalog: MongoCatalog,\n existingDatabases: readonly string[],\n): Promise<Finding[]> {\n const findings: Finding[] = [];\n\n // 1. Env affinity — no connection required, and the only check that catches\n // a test run pointed at production.\n const violation = checkEnvAffinity(dbName, spec.db_var, env, block.env_affinity);\n if (violation) {\n findings.push({\n severity: \"fatal\",\n kind: \"db_shape_violation\",\n message: violation,\n dbVar: spec.db_var,\n database: dbName,\n });\n // A database in the wrong environment must not be probed further.\n return findings;\n }\n\n // 2. Existence.\n if (!existingDatabases.includes(dbName)) {\n const suggestions = nearestNames(dbName, existingDatabases);\n if (suggestions.length > 0) {\n findings.push({\n severity: \"fatal\",\n kind: \"db_absent_typo\",\n message:\n `${spec.db_var}=\"${dbName}\" does not exist. ` +\n `Did you mean ${formatSuggestions(suggestions)}?`,\n dbVar: spec.db_var,\n database: dbName,\n suggestions,\n });\n } else {\n findings.push({\n severity: \"warn\",\n kind: \"db_absent_unseeded\",\n message:\n `${spec.db_var}=\"${dbName}\" does not exist yet. Treating as an ` +\n `unseeded environment; MongoDB will create it on first write.`,\n dbVar: spec.db_var,\n database: dbName,\n });\n }\n // Nothing to compare collections against.\n return findings;\n }\n\n // 3. An empty `collections` list opts out of collection checking: verify the\n // database NAME only. This lets a service adopt incrementally — expansion\n // reaches the leads databases but enumerating their collections is not\n // tractable, and sweeping a 467MB database would emit a warning per\n // collection. Declaring even one collection opts back in.\n if (spec.collections.length === 0) return findings;\n\n // 4. Collections, both directions.\n const actual = await catalog.listCollections(dbName);\n\n for (const declared of spec.collections) {\n if (actual.includes(declared)) continue;\n\n const suggestions = nearestNames(declared, actual);\n if (suggestions.length > 0) {\n findings.push({\n severity: \"fatal\",\n kind: \"collection_absent_typo\",\n message:\n `${dbName}: declared collection \"${declared}\" does not exist. ` +\n `Did you mean ${formatSuggestions(suggestions)}?`,\n dbVar: spec.db_var,\n database: dbName,\n collection: declared,\n suggestions,\n });\n } else {\n findings.push({\n severity: \"warn\",\n kind: \"collection_absent_unseeded\",\n message:\n `${dbName}: declared collection \"${declared}\" does not exist yet ` +\n `(no documents written). MongoDB creates collections lazily.`,\n dbVar: spec.db_var,\n database: dbName,\n collection: declared,\n });\n }\n }\n\n const declaredSet = new Set(spec.collections);\n for (const present of actual) {\n if (declaredSet.has(present)) continue;\n findings.push({\n severity: \"warn\",\n kind: \"collection_undeclared\",\n message:\n `${dbName}: collection \"${present}\" exists but is not declared in the ` +\n `mongo contract.`,\n dbVar: spec.db_var,\n database: dbName,\n collection: present,\n });\n }\n\n return findings;\n}\n\n/**\n * Verify every database and collection declared in `runtimeYamlPath` against a\n * live MongoDB catalogue.\n *\n * Collects ALL findings before deciding, exactly as `validateAgainstContract`\n * does — an operator fixing a misconfiguration should see every problem at\n * once, not one per restart.\n *\n * Resolves to the report when no fatal finding is produced. On a fatal finding\n * it prints every finding and calls `exit(1)`, or throws when\n * `throwOnFailure` is set.\n *\n * A contract with no `mongo:` block is a no-op success.\n */\nexport async function verifyMongo(\n runtimeYamlPath: string,\n opts: VerifyMongoOptions,\n): Promise<MongoVerifyReport> {\n const processEnv = opts.processEnv ?? process.env;\n const logger = opts.logger ?? console;\n const exit = opts.exit ?? ((code: number) => process.exit(code));\n const env = opts.env ?? processEnv.NODE_ENV ?? \"local\";\n\n const contract = loadContract(runtimeYamlPath);\n const block = parseMongoBlock(contract.mongo, runtimeYamlPath);\n if (block === null) return { ok: true, findings: [] };\n\n const findings: Finding[] = [];\n const resolved: Array<{ spec: MongoDbSpec; name: string }> = [];\n\n for (const spec of block.databases) {\n const { name, error, skip } = resolveDbName(spec, contract, env, processEnv);\n if (skip) continue; // optional database, not configured in this environment\n if (error !== undefined || name === undefined) {\n findings.push({\n severity: \"fatal\",\n kind: \"env_var_missing\",\n message: error ?? `${spec.db_var}: unresolved`,\n dbVar: spec.db_var,\n });\n continue;\n }\n resolved.push({ spec, name });\n }\n\n // One catalogue read shared across every database in the contract.\n const existingDatabases =\n resolved.length > 0 ? await opts.catalog.listDatabases() : [];\n\n for (const { spec, name } of resolved) {\n findings.push(\n ...(await verifyDatabase(\n spec,\n name,\n block,\n env,\n opts.catalog,\n existingDatabases,\n )),\n );\n }\n\n const fatals = findings.filter((f) => f.severity === \"fatal\");\n const warns = findings.filter((f) => f.severity === \"warn\");\n\n for (const w of warns) logger.warn(`${TAG} ${w.message}`);\n\n if (fatals.length > 0) {\n const message = [\n `${TAG} verifyMongo failed for ${runtimeYamlPath} (env \"${env}\")`,\n `${fatals.length} fatal finding(s):`,\n ...fatals.map((f) => ` - ${f.message}`),\n ].join(\"\\n\");\n\n if (opts.throwOnFailure) throw new Error(message);\n logger.error(message);\n exit(1);\n }\n\n return { ok: fatals.length === 0, findings };\n}\n","/**\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 * validateAgainstContract also LOADS config, not just validates it: it applies\n * the contract's per-tier defaults into process.env so that code reading\n * process.env.FOO directly sees the same value the validator resolved. This is\n * what removes the need for a materialized `.env.generated` file in local dev.\n *\n * Precedence, highest first:\n * 1. .env.local — local developer overrides; beat everything\n * 2. process.env — real deployed / materialized task-def values\n * 3. contract default — spec.default[<tier>]\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 { existsSync, readFileSync } from \"node:fs\";\nimport { join } from \"node:path\";\n\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 * Apply the contract's defaults for the resolved env into process.env for\n * every runtime variable that is not already set. Defaults to true.\n * An existing process.env value is never overwritten.\n */\n applyDefaults?: boolean;\n /**\n * Load `.env.local` and apply it over process.env before anything else.\n * Defaults to true; the file is optional, so a missing file is a no-op.\n */\n applyEnvLocal?: boolean;\n /**\n * Explicit path to the `.env.local` override file.\n * Defaults to `<process.cwd()>/.env.local`.\n */\n envLocalPath?: string;\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/**\n * Write the contract's defaults for `env` into process.env for every\n * runtime-phase variable that is not already set.\n *\n * A value already present in process.env — a real deployed env var, or one\n * materialized into a task definition — always wins and is left untouched.\n * An explicitly empty value (\"\") counts as present: it is a deliberate\n * choice by whoever set it, and the required-variable check still rejects it.\n *\n * Build-phase variables are skipped (R3.4); secret variables are NOT skipped,\n * so process.env agrees with the value the validator itself resolved. Secret\n * values are never logged.\n *\n * Returns the names of the variables that were applied.\n */\nexport function applyContractDefaults(\n contract: ServiceContract,\n env: string,\n): string[] {\n const applied: string[] = [];\n\n for (const [key, spec] of Object.entries(contract.variables)) {\n if (spec.phase === \"build\") continue;\n if (process.env[key] !== undefined) continue;\n\n const value = resolveDefault(spec, env);\n if (value === undefined) continue;\n\n process.env[key] = value;\n applied.push(key);\n }\n\n return applied;\n}\n\n// ─── .env.local overrides ────────────────────────────────────────────────────\n\n/** `KEY=`, `export KEY=`; everything after the first `=` is the raw value. */\nconst DOTENV_LINE = /^(?:export\\s+)?([A-Za-z_][A-Za-z0-9_]*)\\s*=(.*)$/;\n\n/** Index of the next `quote` not preceded by a backslash, or -1. */\nfunction indexOfUnescaped(s: string, quote: string): number {\n for (let i = 0; i < s.length; i += 1) {\n if (s[i] === \"\\\\\") {\n i += 1;\n continue;\n }\n if (s[i] === quote) return i;\n }\n return -1;\n}\n\n/**\n * Parse `.env` file content into a plain object.\n *\n * Supported: blank lines, `#` comments, an optional `export ` prefix,\n * single-quoted / double-quoted / backtick-quoted values (which may span\n * multiple lines), and `\\n` `\\r` `\\t` `\\\\` escapes inside double quotes.\n * An unquoted value ends at a ` #` inline comment, so `#` may still be used\n * freely inside a quoted value or in the middle of a bare word.\n *\n * Malformed lines are skipped rather than thrown on: a typo in a developer's\n * local override file should not take down the whole process.\n */\nexport function parseDotenv(content: string): Record<string, string> {\n const out: Record<string, string> = {};\n const lines = content.split(/\\r?\\n/);\n\n for (let i = 0; i < lines.length; i += 1) {\n const trimmed = lines[i].trim();\n if (trimmed === \"\" || trimmed.startsWith(\"#\")) continue;\n\n const match = DOTENV_LINE.exec(trimmed);\n if (!match) continue;\n\n const key = match[1];\n const rest = match[2].trim();\n const quote = rest.charAt(0);\n\n if (quote === '\"' || quote === \"'\" || quote === \"`\") {\n // Quoted value — keep consuming lines until the closing quote.\n let body = rest.slice(1);\n let end = indexOfUnescaped(body, quote);\n while (end === -1 && i + 1 < lines.length) {\n i += 1;\n body += `\\n${lines[i]}`;\n end = indexOfUnescaped(body, quote);\n }\n if (end === -1) continue; // unterminated quote — skip the entry\n\n const value = body.slice(0, end);\n out[key] =\n quote === '\"'\n ? value\n .replace(/\\\\n/g, \"\\n\")\n .replace(/\\\\r/g, \"\\r\")\n .replace(/\\\\t/g, \"\\t\")\n .replace(/\\\\\"/g, '\"')\n .replace(/\\\\\\\\/g, \"\\\\\")\n : value;\n continue;\n }\n\n out[key] = rest.split(/\\s+#/)[0].trimEnd();\n }\n\n return out;\n}\n\n/**\n * Apply `.env.local` over process.env.\n *\n * `.env.local` has the last word in local development: it overwrites values\n * already present in process.env, and it runs before defaults are applied, so\n * it also beats every contract default. It may declare variables the contract\n * does not know about — a developer can add config without editing the\n * contract. The file is optional; a missing file is a no-op.\n *\n * Returns the names of the variables that were applied.\n */\nexport function applyEnvLocal(path?: string): string[] {\n const file = path ?? join(process.cwd(), \".env.local\");\n if (!existsSync(file)) return [];\n\n let raw: string;\n try {\n raw = readFileSync(file, \"utf8\");\n } catch (err) {\n const msg = err instanceof Error ? err.message : String(err);\n throw new Error(`[platform-common/config] Cannot read ${file}: ${msg}`);\n }\n\n const parsed = parseDotenv(raw);\n for (const [key, value] of Object.entries(parsed)) {\n process.env[key] = value;\n }\n\n return Object.keys(parsed);\n}\n\n// ─── validateAgainstContract ─────────────────────────────────────────────────\n\n/**\n * Parse `runtimeYamlPath`, load config into `process.env`, coerce every\n * runtime-phase variable, and fail fast on any missing or invalid required\n * variable (R3.2).\n *\n * Loading happens before validation, in precedence order:\n * 1. `.env.local` is applied over process.env (opts.applyEnvLocal)\n * 2. contract defaults for the resolved env fill anything still unset\n * (opts.applyDefaults)\n *\n * `.env.local` is applied first so a developer can set NODE_ENV there and\n * have it select the tier whose defaults are applied.\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\n if (opts.applyEnvLocal !== false) {\n applyEnvLocal(opts.envLocalPath);\n }\n\n const env =\n opts.env ??\n (process.env.NODE_ENV as string | undefined) ??\n \"local\";\n\n if (opts.applyDefaults !== false) {\n applyContractDefaults(contract, env);\n }\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","/**\n * @htilabs/platform-common-models — `mongo:` contract block\n *\n * Extends the HTI Runtime Config Contract (`config/runtime/<service>.yaml`)\n * with a declaration of the databases and collections a service expects.\n *\n * The declaration is deliberately data, not code: `expansion` is Python and\n * parses the same YAML. Nothing here may depend on a TypeScript-only construct.\n *\n * ## Why declared rather than introspected\n *\n * Reading collection names off registered Mongoose models would cover only the\n * Mongoose apps (thread, leads, pave) and would report false findings: thread\n * registers `AgencyInfo` (collection `agencyinfos`), which exists in NO\n * database because nothing has ever written to it. Mongo creates collections\n * lazily. A declaration states intent; introspection only restates the code.\n */\n\n/** One database a service connects to, and the collections it uses. */\nexport interface MongoDbSpec {\n /** Contract variable holding the database NAME (e.g. `THREAD_DB`). */\n db_var: string;\n /**\n * Contract variable holding the connection URI or cluster prefix\n * (e.g. `MONGODB_CLUSTER`). When the URI already embeds a database name and\n * no `db_var` applies, set `db_var` to the same variable — the name is then\n * parsed out of the URI.\n */\n uri_var: string;\n /**\n * Collections the service reads or writes. Declare only what the service\n * USES — not everything present in the database. An undeclared collection\n * present in Mongo is reported, never fatal.\n *\n * An EMPTY list opts out of collection checking entirely: only the database\n * name is verified, and `listCollections` is never called. Use it when a\n * service reaches a database whose collections it cannot practically\n * enumerate. Declaring even one collection opts back in.\n */\n collections: string[];\n}\n\n/**\n * Per-environment database-name affinity. When the deploy environment has an\n * entry here, every resolved database name must end with the given suffix.\n *\n * This generalizes thread's `assertTestDb` (packages/db/src/connections.ts):\n * it is the only check that catches a test run pointed at a production\n * database, and it needs no connection to MongoDB.\n */\nexport type EnvAffinity = Record<string, string>;\n\nexport interface MongoContractBlock {\n /** e.g. `{ test: \"-test\", dev: \"-dev\" }`. Environments omitted are unconstrained. */\n env_affinity?: EnvAffinity;\n databases: MongoDbSpec[];\n}\n\n/** Prefix for every diagnostic this module emits. */\nconst TAG = \"[platform-common/mongo]\";\n\n/**\n * Validate and normalize the `mongo:` block of a parsed contract.\n *\n * Returns `null` when the contract declares no `mongo:` block — a service that\n * does not use MongoDB is not an error.\n *\n * Throws on a malformed block: a contract that lies about its shape is a\n * programming error, not a runtime finding.\n */\nexport function parseMongoBlock(\n raw: unknown,\n contractPath: string,\n): MongoContractBlock | null {\n if (raw === undefined || raw === null) return null;\n\n if (typeof raw !== \"object\" || Array.isArray(raw)) {\n throw new Error(`${TAG} ${contractPath}: \"mongo\" must be a mapping`);\n }\n\n const block = raw as Partial<MongoContractBlock>;\n\n if (!Array.isArray(block.databases) || block.databases.length === 0) {\n throw new Error(\n `${TAG} ${contractPath}: \"mongo.databases\" must be a non-empty list`,\n );\n }\n\n block.databases.forEach((db, i) => {\n const where = `${contractPath}: mongo.databases[${i}]`;\n if (!db || typeof db !== \"object\") {\n throw new Error(`${TAG} ${where} must be a mapping`);\n }\n if (typeof db.db_var !== \"string\" || db.db_var.length === 0) {\n throw new Error(`${TAG} ${where}.db_var must be a non-empty string`);\n }\n if (typeof db.uri_var !== \"string\" || db.uri_var.length === 0) {\n throw new Error(`${TAG} ${where}.uri_var must be a non-empty string`);\n }\n if (!Array.isArray(db.collections)) {\n throw new Error(`${TAG} ${where}.collections must be a list`);\n }\n db.collections.forEach((c, j) => {\n if (typeof c !== \"string\" || c.length === 0) {\n throw new Error(\n `${TAG} ${where}.collections[${j}] must be a non-empty string`,\n );\n }\n });\n });\n\n if (block.env_affinity !== undefined) {\n if (typeof block.env_affinity !== \"object\" || Array.isArray(block.env_affinity)) {\n throw new Error(\n `${TAG} ${contractPath}: \"mongo.env_affinity\" must be a mapping of env -> suffix`,\n );\n }\n for (const [env, suffix] of Object.entries(block.env_affinity)) {\n if (typeof suffix !== \"string\" || suffix.length === 0) {\n throw new Error(\n `${TAG} ${contractPath}: mongo.env_affinity.${env} must be a non-empty string`,\n );\n }\n }\n }\n\n return {\n env_affinity: block.env_affinity,\n databases: block.databases as MongoDbSpec[],\n };\n}\n\n/**\n * Check a resolved database name against the environment's affinity suffix.\n *\n * Returns `null` when the name is acceptable (or the environment declares no\n * affinity), otherwise a human-readable violation message.\n *\n * Requires NO MongoDB connection. This is the check that catches\n * `NODE_ENV=test` pointed at `platform-db`.\n */\nexport function checkEnvAffinity(\n dbName: string,\n dbVar: string,\n env: string,\n affinity: EnvAffinity | undefined,\n): string | null {\n const suffix = affinity?.[env];\n if (!suffix) return null;\n if (dbName.endsWith(suffix)) return null;\n\n return (\n `${dbVar}=\"${dbName}\" is not valid in environment \"${env}\": ` +\n `database names must end with \"${suffix}\". ` +\n `Refusing to run against a database outside this environment.`\n );\n}\n","/**\n * @htilabs/platform-common-models — name-similarity heuristic\n *\n * A missing database or collection is AMBIGUOUS. MongoDB creates namespaces\n * lazily, on first write, so \"absent\" means either:\n *\n * (a) a typo — the name is wrong and the real one exists nearby, or\n * (b) unseeded — the environment is new and nothing has been written yet.\n *\n * Guessing wrong in direction (b) is expensive: a fatal check would ground\n * every cold-start ephemeral deploy. So absence alone is never fatal. Only\n * absence WITH a plausible near-neighbour is treated as a typo.\n */\n\n/** Maximum edit distance at which a neighbouring name is considered a typo. */\nexport const TYPO_DISTANCE_THRESHOLD = 2;\n\n/**\n * Optimal String Alignment distance (Damerau-Levenshtein restricted to\n * adjacent transpositions), bounded: returns `max + 1` as soon as the true\n * distance is known to exceed `max`. Bounding keeps this cheap across the\n * ~90-database catalogue scanned on each lookup.\n *\n * A transposition MUST cost 1, not 2. `platform-dve` is a transposition of\n * `platform-dev`, but plain Levenshtein scores it 2 -- tying it with the\n * unrelated PRODUCTION name `platform-db` and letting iteration order pick.\n * Steering an operator toward a production database because they typo'd a dev\n * one is a worse failure than suggesting nothing at all.\n */\nexport function editDistance(a: string, b: string, max = Infinity): number {\n if (a === b) return 0;\n if (Math.abs(a.length - b.length) > max) return max + 1;\n\n // Three rows: prev2 carries i-2 so an adjacent transposition costs 1.\n let prev2 = new Array<number>(b.length + 1).fill(0);\n let prev = Array.from({ length: b.length + 1 }, (_, i) => i);\n let curr = new Array<number>(b.length + 1);\n\n for (let i = 1; i <= a.length; i++) {\n curr[0] = i;\n let rowMin = curr[0];\n for (let j = 1; j <= b.length; j++) {\n const cost = a[i - 1] === b[j - 1] ? 0 : 1;\n let d = Math.min(\n prev[j] + 1, // deletion\n curr[j - 1] + 1, // insertion\n prev[j - 1] + cost, // substitution\n );\n if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1]) {\n d = Math.min(d, prev2[j - 2] + 1); // adjacent transposition\n }\n curr[j] = d;\n if (d < rowMin) rowMin = d;\n }\n // Every remaining row can only grow: bail out early.\n if (rowMin > max) return max + 1;\n [prev2, prev, curr] = [prev, curr, prev2];\n }\n\n return prev[b.length];\n}\n\n/** Strip a trailing ordinal token: `demo2` -> `demo`, `cypress-tests-3` -> `cypress-tests`. */\nfunction stripOrdinal(name: string): string {\n return name.replace(/[-_]?\\d+$/, \"\");\n}\n\n/**\n * True when two names look like sibling environments rather than a typo of\n * each other — that is, they differ ONLY in a trailing ordinal.\n *\n * This guard is mandatory, not cosmetic. The live cluster contains\n * `leads-platform-demo` beside `leads-platform-demo2` (edit distance 1) and\n * `cypress-tests-1/2/3`. Without it, provisioning `leads-platform-demo3` would\n * find `demo2` one edit away, be branded a typo, and hard-fail a healthy new\n * environment — reintroducing exactly the cold-start breakage the severity\n * model exists to prevent.\n *\n * The guard is deliberately biased toward WARN: a genuine typo that happens to\n * differ only in a trailing digit is downgraded to a warning rather than\n * risking a false fatal.\n */\nexport function isOrdinalSibling(a: string, b: string): boolean {\n if (a === b) return false;\n const baseA = stripOrdinal(a);\n const baseB = stripOrdinal(b);\n // Both must reduce to the same base, and at least one must have carried an\n // ordinal (otherwise stripping changed nothing and this is a real edit).\n return baseA === baseB && (baseA !== a || baseB !== b);\n}\n\n/**\n * Find the existing names most likely to be what `name` was meant to be.\n *\n * Returns EVERY candidate at the minimal distance, not one arbitrary winner.\n * `thread-dv` is one edit from both `thread-dev` and `thread-db`; picking\n * between them by iteration order could point an operator at production. When\n * the evidence is ambiguous, say so.\n *\n * Returns an empty array when nothing is close enough, or when the only close\n * matches are sibling environments (see {@link isOrdinalSibling}). Empty means\n * \"absent, but no evidence of a typo\" — the caller warns rather than fails.\n *\n * Results are sorted for deterministic messages.\n */\nexport function nearestNames(name: string, candidates: readonly string[]): string[] {\n let best: string[] = [];\n let bestDistance = TYPO_DISTANCE_THRESHOLD + 1;\n\n for (const candidate of candidates) {\n if (candidate === name) return []; // exact match: not missing at all\n if (isOrdinalSibling(name, candidate)) continue;\n\n const d = editDistance(name, candidate, TYPO_DISTANCE_THRESHOLD);\n if (d > TYPO_DISTANCE_THRESHOLD) continue;\n\n if (d < bestDistance) {\n bestDistance = d;\n best = [candidate];\n } else if (d === bestDistance) {\n best.push(candidate);\n }\n }\n\n return best.sort();\n}\n\n/** Render one or more suggestions as `\"a\"`, or `\"a\" or \"b\"`, or `\"a\", \"b\" or \"c\"`. */\nexport function formatSuggestions(names: readonly string[]): string {\n const quoted = names.map((n) => `\"${n}\"`);\n if (quoted.length <= 1) return quoted[0] ?? \"\";\n return `${quoted.slice(0, -1).join(\", \")} or ${quoted[quoted.length - 1]}`;\n}\n","/**\n * @htilabs/platform-common-models — MongoDB URI parsing\n *\n * Home of the connection-string parsing shared by the seed guard\n * (`scripts/lib/confirmTargetDb.ts`) and the runtime verifier\n * (`src/mongo/index.ts`). It lives in `src/` so both can import one\n * implementation; `scripts/` cannot be imported from `src/` at build time.\n */\n\n/** Suffix that marks a database as a non-production scratch/test database. */\nexport const TEST_DB_SUFFIX = \"-test\";\n\n/**\n * Parse the target database name out of a MongoDB connection URI.\n *\n * The database name is the path segment after the host(s), before any query\n * string (`?...`). Handles both `mongodb://` and `mongodb+srv://` URIs and any\n * userinfo / multi-host / option components. Returns `null` when the URI\n * carries no database name (e.g. `mongodb://localhost:27017` or a trailing\n * slash with nothing after it) — callers must treat a `null` name as\n * prod-shaped and never silently default to a production database.\n *\n * Implemented as manual string parsing rather than `new URL()` because Node's\n * URL parser rejects multi-host `mongodb+srv` authorities and mishandles the\n * comma-separated seed-list form that real connection strings use.\n */\nexport function parseDbName(uri: string): string | null {\n // Strip the scheme.\n const schemeMatch = /^mongodb(\\+srv)?:\\/\\//i.exec(uri);\n if (!schemeMatch) return null;\n let rest = uri.slice(schemeMatch[0].length);\n\n // Drop query string and fragment — the DB name precedes both.\n const qIdx = rest.search(/[?#]/);\n if (qIdx !== -1) rest = rest.slice(0, qIdx);\n\n // The path begins at the first '/' after the authority. Everything before\n // that first slash is userinfo + host(s); everything after is the DB name.\n const slashIdx = rest.indexOf(\"/\");\n if (slashIdx === -1) return null;\n\n const dbName = rest.slice(slashIdx + 1).trim();\n return dbName.length > 0 ? dbName : null;\n}\n\n/**\n * Classify a database name. A name is a \"test\" database (no confirmation\n * required) only when it is non-null and ends in {@link TEST_DB_SUFFIX}.\n * Everything else — including a `null` name — is prod-shaped.\n */\nexport function isTestDb(dbName: string | null): boolean {\n return dbName !== null && dbName.endsWith(TEST_DB_SUFFIX);\n}\n","/**\n * @htilabs/platform-common-models — read-only MongoDB catalogue\n *\n * The verifier reaches MongoDB ONLY through this interface. It exposes two\n * read operations and nothing else: there is no method here that can create,\n * write, or drop anything. The read-only guarantee is enforced by the type,\n * not by convention.\n *\n * Injecting the catalogue also keeps the package's test suite free of a real\n * MongoDB, matching how `runCvcBootCheck` injects `exit` and `logger`.\n */\n\nexport interface MongoCatalog {\n /** Names of databases that physically exist (i.e. hold data). */\n listDatabases(): Promise<string[]>;\n /** Names of collections that physically exist in `database`. */\n listCollections(database: string): Promise<string[]>;\n}\n\n/**\n * Minimal structural view of a `mongodb` MongoClient. Declared structurally so\n * this package takes no dependency on the `mongodb` driver — apps pass their\n * own client, whatever major version they are on.\n */\nexport interface MongoClientLike {\n db(name?: string): {\n admin(): {\n listDatabases(): Promise<{ databases: Array<{ name: string }> }>;\n };\n listCollections(\n filter?: Record<string, unknown>,\n options?: Record<string, unknown>,\n ): { toArray(): Promise<Array<{ name: string }>> };\n };\n}\n\n/** Minimal structural view of a Mongoose Connection. */\nexport interface MongooseConnectionLike {\n getClient(): MongoClientLike;\n}\n\n/** Build a catalogue from a native `mongodb` client. */\nexport function catalogFromClient(client: MongoClientLike): MongoCatalog {\n return {\n async listDatabases(): Promise<string[]> {\n const { databases } = await client.db().admin().listDatabases();\n return databases.map((d) => d.name);\n },\n async listCollections(database: string): Promise<string[]> {\n // `nameOnly` keeps the server from materializing collection options.\n const infos = await client\n .db(database)\n .listCollections({}, { nameOnly: true })\n .toArray();\n return infos.map((c) => c.name);\n },\n };\n}\n\n/** Build a catalogue from an open Mongoose connection. */\nexport function catalogFromMongoose(\n connection: MongooseConnectionLike,\n): MongoCatalog {\n return catalogFromClient(connection.getClient());\n}\n"],"mappings":"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","names":["TAG"]}
|
|
1
|
+
{"version":3,"sources":["../../src/mongo/index.ts","../../src/config/index.ts","../../src/mongo/contract.ts","../../src/mongo/similarity.ts","../../src/mongo/uri.ts","../../src/mongo/catalog.ts"],"sourcesContent":["/**\n * @htilabs/platform-common-models — MongoDB connection/collection verifier\n *\n * Sibling to `./config`. Where `validateAgainstContract` proves the env vars\n * are present and well-typed, `verifyMongo` proves they point somewhere real.\n *\n * ## What this catches\n * - a database name that does not exist and looks like a typo of one that does\n * - a collection name that does not exist and looks like a typo of one that does\n * - a database name that does not belong to the current environment\n * (env-affinity; needs no connection — generalizes thread's `assertTestDb`)\n * - collections present in MongoDB but undeclared by the service (reported)\n *\n * ## What this CANNOT catch\n * A plausible-but-wrong POPULATED database. `leads-platform-prod-test` exists\n * and carries the same collection names as `leads-platform-test`; every\n * name-existence check passes. Detecting that needs an identity marker\n * written inside the database, which is outside this utility's read-only\n * remit. Do not claim otherwise in adoption docs.\n *\n * ## Read-only\n * Reaches MongoDB solely through {@link MongoCatalog}: listDatabases and\n * listCollections. It never creates, writes, or drops anything.\n *\n * ## Severity\n * MongoDB creates namespaces lazily, so ABSENCE IS AMBIGUOUS (typo vs\n * unseeded environment). Absence alone warns; absence with a plausible\n * near-neighbour is fatal. See `similarity.ts`.\n *\n * FACT (verified 2026-07-10, read-only): thread registers the Mongoose model\n * `AgencyInfo` (collection `agencyinfos`), and that collection exists in\n * neither `platform-test` (15 collections) nor `platform-dev` (41). A\n * registered model with zero documents has no collection. The warn-on-absence\n * rule exists because of this; do not \"tighten\" it to fatal.\n */\n\nimport {\n loadContract,\n resolveDefault,\n type ServiceContract,\n} from \"../config/index.js\";\nimport {\n parseMongoBlock,\n checkEnvAffinity,\n type MongoContractBlock,\n type MongoDbSpec,\n} from \"./contract.js\";\nimport { nearestNames, formatSuggestions } from \"./similarity.js\";\nimport { parseDbName } from \"./uri.js\";\nimport type { MongoCatalog } from \"./catalog.js\";\n\nexport type { MongoCatalog, MongoClientLike, MongooseConnectionLike } from \"./catalog.js\";\nexport { catalogFromClient, catalogFromMongoose } from \"./catalog.js\";\nexport type { MongoContractBlock, MongoDbSpec, EnvAffinity } from \"./contract.js\";\nexport { parseDbName, isTestDb, TEST_DB_SUFFIX } from \"./uri.js\";\n\nconst TAG = \"[platform-common/mongo]\";\n\nexport type Severity = \"fatal\" | \"warn\";\n\nexport type FindingKind =\n | \"env_var_missing\"\n | \"db_shape_violation\"\n | \"db_absent_typo\"\n | \"db_absent_unseeded\"\n | \"collection_absent_typo\"\n | \"collection_absent_unseeded\"\n | \"collection_undeclared\";\n\nexport interface Finding {\n severity: Severity;\n kind: FindingKind;\n message: string;\n dbVar?: string;\n database?: string;\n collection?: string;\n /**\n * Existing names this looks like a typo of. More than one means the evidence\n * is ambiguous — the message lists them all rather than guessing.\n */\n suggestions?: string[];\n}\n\nexport interface MongoVerifyReport {\n /** True when no fatal finding was produced. Warnings do not clear `ok`. */\n ok: boolean;\n findings: Finding[];\n}\n\nexport interface VerifyMongoOptions {\n /** Read-only catalogue. Required — this package takes no driver dependency. */\n catalog: MongoCatalog;\n /** Environment name for affinity checks. Defaults to NODE_ENV, then \"local\". */\n env?: string;\n /** Env source. Defaults to `process.env`. */\n processEnv?: NodeJS.ProcessEnv;\n /** If true, throw instead of `exit(1)`. Defaults to false (production exits). */\n throwOnFailure?: boolean;\n /** Injected for tests. Defaults to `process.exit`. */\n exit?: (code: number) => never;\n /** Injected for tests. Defaults to `console`. */\n logger?: Pick<Console, \"error\" | \"warn\">;\n}\n\n/**\n * Resolve the database name for a spec, applying the same per-environment\n * defaults that `validateAgainstContract` applies. Reading `process.env` alone\n * would miss a value the contract supplies as a default (thread declares\n * `PLATFORM_DB.default.prod: platform-prod`) and report a false fatal.\n *\n * When `db_var` and `uri_var` name the same variable, the database is embedded\n * in the connection string (auth does this for `LEADS_MONGODB_URI` and\n * friends) and must be parsed out of it.\n *\n * A variable the contract marks `required: false` and that carries no value is\n * SKIPPED, not failed: thread's `PAVE_DB` is optional and its absence simply\n * means the read-only pave connection is not configured. Required-ness comes\n * from the contract so there is no second place to declare it.\n */\nfunction resolveDbName(\n spec: MongoDbSpec,\n contract: ServiceContract,\n env: string,\n processEnv: NodeJS.ProcessEnv,\n): { name?: string; error?: string; skip?: boolean } {\n const varSpec = contract.variables[spec.db_var];\n const raw =\n processEnv[spec.db_var] ??\n (varSpec ? resolveDefault(varSpec, env) : undefined);\n\n if (raw === undefined || raw === \"\") {\n // A variable absent from `variables` is treated as required: the mongo\n // block references something the contract never declared.\n if (varSpec && varSpec.required === false) return { skip: true };\n return { error: `${spec.db_var}: required by mongo contract but not set` };\n }\n\n if (spec.db_var !== spec.uri_var) return { name: raw };\n\n const parsed = parseDbName(raw);\n if (parsed === null) {\n return {\n error:\n `${spec.db_var}: connection string carries no database name. ` +\n `Either embed one (mongodb://host/<db>) or declare a separate db_var.`,\n };\n }\n return { name: parsed };\n}\n\nasync function verifyDatabase(\n spec: MongoDbSpec,\n dbName: string,\n block: MongoContractBlock,\n env: string,\n catalog: MongoCatalog,\n existingDatabases: readonly string[],\n): Promise<Finding[]> {\n const findings: Finding[] = [];\n\n // 1. Env affinity — no connection required, and the only check that catches\n // a test run pointed at production.\n const violation = checkEnvAffinity(dbName, spec.db_var, env, block.env_affinity);\n if (violation) {\n findings.push({\n severity: \"fatal\",\n kind: \"db_shape_violation\",\n message: violation,\n dbVar: spec.db_var,\n database: dbName,\n });\n // A database in the wrong environment must not be probed further.\n return findings;\n }\n\n // 2. Existence.\n if (!existingDatabases.includes(dbName)) {\n const suggestions = nearestNames(dbName, existingDatabases);\n if (suggestions.length > 0) {\n findings.push({\n severity: \"fatal\",\n kind: \"db_absent_typo\",\n message:\n `${spec.db_var}=\"${dbName}\" does not exist. ` +\n `Did you mean ${formatSuggestions(suggestions)}?`,\n dbVar: spec.db_var,\n database: dbName,\n suggestions,\n });\n } else {\n findings.push({\n severity: \"warn\",\n kind: \"db_absent_unseeded\",\n message:\n `${spec.db_var}=\"${dbName}\" does not exist yet. Treating as an ` +\n `unseeded environment; MongoDB will create it on first write.`,\n dbVar: spec.db_var,\n database: dbName,\n });\n }\n // Nothing to compare collections against.\n return findings;\n }\n\n // 3. An empty `collections` list opts out of collection checking: verify the\n // database NAME only. This lets a service adopt incrementally — expansion\n // reaches the leads databases but enumerating their collections is not\n // tractable, and sweeping a 467MB database would emit a warning per\n // collection. Declaring even one collection opts back in.\n if (spec.collections.length === 0) return findings;\n\n // 4. Collections, both directions.\n const actual = await catalog.listCollections(dbName);\n\n for (const declared of spec.collections) {\n if (actual.includes(declared)) continue;\n\n const suggestions = nearestNames(declared, actual);\n if (suggestions.length > 0) {\n findings.push({\n severity: \"fatal\",\n kind: \"collection_absent_typo\",\n message:\n `${dbName}: declared collection \"${declared}\" does not exist. ` +\n `Did you mean ${formatSuggestions(suggestions)}?`,\n dbVar: spec.db_var,\n database: dbName,\n collection: declared,\n suggestions,\n });\n } else {\n findings.push({\n severity: \"warn\",\n kind: \"collection_absent_unseeded\",\n message:\n `${dbName}: declared collection \"${declared}\" does not exist yet ` +\n `(no documents written). MongoDB creates collections lazily.`,\n dbVar: spec.db_var,\n database: dbName,\n collection: declared,\n });\n }\n }\n\n const declaredSet = new Set(spec.collections);\n for (const present of actual) {\n if (declaredSet.has(present)) continue;\n findings.push({\n severity: \"warn\",\n kind: \"collection_undeclared\",\n message:\n `${dbName}: collection \"${present}\" exists but is not declared in the ` +\n `mongo contract.`,\n dbVar: spec.db_var,\n database: dbName,\n collection: present,\n });\n }\n\n return findings;\n}\n\n/**\n * Verify every database and collection declared in `runtimeYamlPath` against a\n * live MongoDB catalogue.\n *\n * Collects ALL findings before deciding, exactly as `validateAgainstContract`\n * does — an operator fixing a misconfiguration should see every problem at\n * once, not one per restart.\n *\n * Resolves to the report when no fatal finding is produced. On a fatal finding\n * it prints every finding and calls `exit(1)`, or throws when\n * `throwOnFailure` is set.\n *\n * A contract with no `mongo:` block is a no-op success.\n */\nexport async function verifyMongo(\n runtimeYamlPath: string,\n opts: VerifyMongoOptions,\n): Promise<MongoVerifyReport> {\n const processEnv = opts.processEnv ?? process.env;\n const logger = opts.logger ?? console;\n const exit = opts.exit ?? ((code: number) => process.exit(code));\n const env = opts.env ?? processEnv.NODE_ENV ?? \"local\";\n\n const contract = loadContract(runtimeYamlPath);\n const block = parseMongoBlock(contract.mongo, runtimeYamlPath);\n if (block === null) return { ok: true, findings: [] };\n\n const findings: Finding[] = [];\n const resolved: Array<{ spec: MongoDbSpec; name: string }> = [];\n\n for (const spec of block.databases) {\n const { name, error, skip } = resolveDbName(spec, contract, env, processEnv);\n if (skip) continue; // optional database, not configured in this environment\n if (error !== undefined || name === undefined) {\n findings.push({\n severity: \"fatal\",\n kind: \"env_var_missing\",\n message: error ?? `${spec.db_var}: unresolved`,\n dbVar: spec.db_var,\n });\n continue;\n }\n resolved.push({ spec, name });\n }\n\n // One catalogue read shared across every database in the contract.\n const existingDatabases =\n resolved.length > 0 ? await opts.catalog.listDatabases() : [];\n\n for (const { spec, name } of resolved) {\n findings.push(\n ...(await verifyDatabase(\n spec,\n name,\n block,\n env,\n opts.catalog,\n existingDatabases,\n )),\n );\n }\n\n const fatals = findings.filter((f) => f.severity === \"fatal\");\n const warns = findings.filter((f) => f.severity === \"warn\");\n\n for (const w of warns) logger.warn(`${TAG} ${w.message}`);\n\n if (fatals.length > 0) {\n const message = [\n `${TAG} verifyMongo failed for ${runtimeYamlPath} (env \"${env}\")`,\n `${fatals.length} fatal finding(s):`,\n ...fatals.map((f) => ` - ${f.message}`),\n ].join(\"\\n\");\n\n if (opts.throwOnFailure) throw new Error(message);\n logger.error(message);\n exit(1);\n }\n\n return { ok: fatals.length === 0, findings };\n}\n","/**\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","/**\n * @htilabs/platform-common-models — `mongo:` contract block\n *\n * Extends the HTI Runtime Config Contract (`config/runtime/<service>.yaml`)\n * with a declaration of the databases and collections a service expects.\n *\n * The declaration is deliberately data, not code: `expansion` is Python and\n * parses the same YAML. Nothing here may depend on a TypeScript-only construct.\n *\n * ## Why declared rather than introspected\n *\n * Reading collection names off registered Mongoose models would cover only the\n * Mongoose apps (thread, leads, pave) and would report false findings: thread\n * registers `AgencyInfo` (collection `agencyinfos`), which exists in NO\n * database because nothing has ever written to it. Mongo creates collections\n * lazily. A declaration states intent; introspection only restates the code.\n */\n\n/** One database a service connects to, and the collections it uses. */\nexport interface MongoDbSpec {\n /** Contract variable holding the database NAME (e.g. `THREAD_DB`). */\n db_var: string;\n /**\n * Contract variable holding the connection URI or cluster prefix\n * (e.g. `MONGODB_CLUSTER`). When the URI already embeds a database name and\n * no `db_var` applies, set `db_var` to the same variable — the name is then\n * parsed out of the URI.\n */\n uri_var: string;\n /**\n * Collections the service reads or writes. Declare only what the service\n * USES — not everything present in the database. An undeclared collection\n * present in Mongo is reported, never fatal.\n *\n * An EMPTY list opts out of collection checking entirely: only the database\n * name is verified, and `listCollections` is never called. Use it when a\n * service reaches a database whose collections it cannot practically\n * enumerate. Declaring even one collection opts back in.\n */\n collections: string[];\n}\n\n/**\n * Per-environment database-name affinity. When the deploy environment has an\n * entry here, every resolved database name must end with the given suffix.\n *\n * This generalizes thread's `assertTestDb` (packages/db/src/connections.ts):\n * it is the only check that catches a test run pointed at a production\n * database, and it needs no connection to MongoDB.\n */\nexport type EnvAffinity = Record<string, string>;\n\nexport interface MongoContractBlock {\n /** e.g. `{ test: \"-test\", dev: \"-dev\" }`. Environments omitted are unconstrained. */\n env_affinity?: EnvAffinity;\n databases: MongoDbSpec[];\n}\n\n/** Prefix for every diagnostic this module emits. */\nconst TAG = \"[platform-common/mongo]\";\n\n/**\n * Validate and normalize the `mongo:` block of a parsed contract.\n *\n * Returns `null` when the contract declares no `mongo:` block — a service that\n * does not use MongoDB is not an error.\n *\n * Throws on a malformed block: a contract that lies about its shape is a\n * programming error, not a runtime finding.\n */\nexport function parseMongoBlock(\n raw: unknown,\n contractPath: string,\n): MongoContractBlock | null {\n if (raw === undefined || raw === null) return null;\n\n if (typeof raw !== \"object\" || Array.isArray(raw)) {\n throw new Error(`${TAG} ${contractPath}: \"mongo\" must be a mapping`);\n }\n\n const block = raw as Partial<MongoContractBlock>;\n\n if (!Array.isArray(block.databases) || block.databases.length === 0) {\n throw new Error(\n `${TAG} ${contractPath}: \"mongo.databases\" must be a non-empty list`,\n );\n }\n\n block.databases.forEach((db, i) => {\n const where = `${contractPath}: mongo.databases[${i}]`;\n if (!db || typeof db !== \"object\") {\n throw new Error(`${TAG} ${where} must be a mapping`);\n }\n if (typeof db.db_var !== \"string\" || db.db_var.length === 0) {\n throw new Error(`${TAG} ${where}.db_var must be a non-empty string`);\n }\n if (typeof db.uri_var !== \"string\" || db.uri_var.length === 0) {\n throw new Error(`${TAG} ${where}.uri_var must be a non-empty string`);\n }\n if (!Array.isArray(db.collections)) {\n throw new Error(`${TAG} ${where}.collections must be a list`);\n }\n db.collections.forEach((c, j) => {\n if (typeof c !== \"string\" || c.length === 0) {\n throw new Error(\n `${TAG} ${where}.collections[${j}] must be a non-empty string`,\n );\n }\n });\n });\n\n if (block.env_affinity !== undefined) {\n if (typeof block.env_affinity !== \"object\" || Array.isArray(block.env_affinity)) {\n throw new Error(\n `${TAG} ${contractPath}: \"mongo.env_affinity\" must be a mapping of env -> suffix`,\n );\n }\n for (const [env, suffix] of Object.entries(block.env_affinity)) {\n if (typeof suffix !== \"string\" || suffix.length === 0) {\n throw new Error(\n `${TAG} ${contractPath}: mongo.env_affinity.${env} must be a non-empty string`,\n );\n }\n }\n }\n\n return {\n env_affinity: block.env_affinity,\n databases: block.databases as MongoDbSpec[],\n };\n}\n\n/**\n * Check a resolved database name against the environment's affinity suffix.\n *\n * Returns `null` when the name is acceptable (or the environment declares no\n * affinity), otherwise a human-readable violation message.\n *\n * Requires NO MongoDB connection. This is the check that catches\n * `NODE_ENV=test` pointed at `platform-db`.\n */\nexport function checkEnvAffinity(\n dbName: string,\n dbVar: string,\n env: string,\n affinity: EnvAffinity | undefined,\n): string | null {\n const suffix = affinity?.[env];\n if (!suffix) return null;\n if (dbName.endsWith(suffix)) return null;\n\n return (\n `${dbVar}=\"${dbName}\" is not valid in environment \"${env}\": ` +\n `database names must end with \"${suffix}\". ` +\n `Refusing to run against a database outside this environment.`\n );\n}\n","/**\n * @htilabs/platform-common-models — name-similarity heuristic\n *\n * A missing database or collection is AMBIGUOUS. MongoDB creates namespaces\n * lazily, on first write, so \"absent\" means either:\n *\n * (a) a typo — the name is wrong and the real one exists nearby, or\n * (b) unseeded — the environment is new and nothing has been written yet.\n *\n * Guessing wrong in direction (b) is expensive: a fatal check would ground\n * every cold-start ephemeral deploy. So absence alone is never fatal. Only\n * absence WITH a plausible near-neighbour is treated as a typo.\n */\n\n/** Maximum edit distance at which a neighbouring name is considered a typo. */\nexport const TYPO_DISTANCE_THRESHOLD = 2;\n\n/**\n * Optimal String Alignment distance (Damerau-Levenshtein restricted to\n * adjacent transpositions), bounded: returns `max + 1` as soon as the true\n * distance is known to exceed `max`. Bounding keeps this cheap across the\n * ~90-database catalogue scanned on each lookup.\n *\n * A transposition MUST cost 1, not 2. `platform-dve` is a transposition of\n * `platform-dev`, but plain Levenshtein scores it 2 -- tying it with the\n * unrelated PRODUCTION name `platform-db` and letting iteration order pick.\n * Steering an operator toward a production database because they typo'd a dev\n * one is a worse failure than suggesting nothing at all.\n */\nexport function editDistance(a: string, b: string, max = Infinity): number {\n if (a === b) return 0;\n if (Math.abs(a.length - b.length) > max) return max + 1;\n\n // Three rows: prev2 carries i-2 so an adjacent transposition costs 1.\n let prev2 = new Array<number>(b.length + 1).fill(0);\n let prev = Array.from({ length: b.length + 1 }, (_, i) => i);\n let curr = new Array<number>(b.length + 1);\n\n for (let i = 1; i <= a.length; i++) {\n curr[0] = i;\n let rowMin = curr[0];\n for (let j = 1; j <= b.length; j++) {\n const cost = a[i - 1] === b[j - 1] ? 0 : 1;\n let d = Math.min(\n prev[j] + 1, // deletion\n curr[j - 1] + 1, // insertion\n prev[j - 1] + cost, // substitution\n );\n if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1]) {\n d = Math.min(d, prev2[j - 2] + 1); // adjacent transposition\n }\n curr[j] = d;\n if (d < rowMin) rowMin = d;\n }\n // Every remaining row can only grow: bail out early.\n if (rowMin > max) return max + 1;\n [prev2, prev, curr] = [prev, curr, prev2];\n }\n\n return prev[b.length];\n}\n\n/** Strip a trailing ordinal token: `demo2` -> `demo`, `cypress-tests-3` -> `cypress-tests`. */\nfunction stripOrdinal(name: string): string {\n return name.replace(/[-_]?\\d+$/, \"\");\n}\n\n/**\n * True when two names look like sibling environments rather than a typo of\n * each other — that is, they differ ONLY in a trailing ordinal.\n *\n * This guard is mandatory, not cosmetic. The live cluster contains\n * `leads-platform-demo` beside `leads-platform-demo2` (edit distance 1) and\n * `cypress-tests-1/2/3`. Without it, provisioning `leads-platform-demo3` would\n * find `demo2` one edit away, be branded a typo, and hard-fail a healthy new\n * environment — reintroducing exactly the cold-start breakage the severity\n * model exists to prevent.\n *\n * The guard is deliberately biased toward WARN: a genuine typo that happens to\n * differ only in a trailing digit is downgraded to a warning rather than\n * risking a false fatal.\n */\nexport function isOrdinalSibling(a: string, b: string): boolean {\n if (a === b) return false;\n const baseA = stripOrdinal(a);\n const baseB = stripOrdinal(b);\n // Both must reduce to the same base, and at least one must have carried an\n // ordinal (otherwise stripping changed nothing and this is a real edit).\n return baseA === baseB && (baseA !== a || baseB !== b);\n}\n\n/**\n * Find the existing names most likely to be what `name` was meant to be.\n *\n * Returns EVERY candidate at the minimal distance, not one arbitrary winner.\n * `thread-dv` is one edit from both `thread-dev` and `thread-db`; picking\n * between them by iteration order could point an operator at production. When\n * the evidence is ambiguous, say so.\n *\n * Returns an empty array when nothing is close enough, or when the only close\n * matches are sibling environments (see {@link isOrdinalSibling}). Empty means\n * \"absent, but no evidence of a typo\" — the caller warns rather than fails.\n *\n * Results are sorted for deterministic messages.\n */\nexport function nearestNames(name: string, candidates: readonly string[]): string[] {\n let best: string[] = [];\n let bestDistance = TYPO_DISTANCE_THRESHOLD + 1;\n\n for (const candidate of candidates) {\n if (candidate === name) return []; // exact match: not missing at all\n if (isOrdinalSibling(name, candidate)) continue;\n\n const d = editDistance(name, candidate, TYPO_DISTANCE_THRESHOLD);\n if (d > TYPO_DISTANCE_THRESHOLD) continue;\n\n if (d < bestDistance) {\n bestDistance = d;\n best = [candidate];\n } else if (d === bestDistance) {\n best.push(candidate);\n }\n }\n\n return best.sort();\n}\n\n/** Render one or more suggestions as `\"a\"`, or `\"a\" or \"b\"`, or `\"a\", \"b\" or \"c\"`. */\nexport function formatSuggestions(names: readonly string[]): string {\n const quoted = names.map((n) => `\"${n}\"`);\n if (quoted.length <= 1) return quoted[0] ?? \"\";\n return `${quoted.slice(0, -1).join(\", \")} or ${quoted[quoted.length - 1]}`;\n}\n","/**\n * @htilabs/platform-common-models — MongoDB URI parsing\n *\n * Home of the connection-string parsing shared by the seed guard\n * (`scripts/lib/confirmTargetDb.ts`) and the runtime verifier\n * (`src/mongo/index.ts`). It lives in `src/` so both can import one\n * implementation; `scripts/` cannot be imported from `src/` at build time.\n */\n\n/** Suffix that marks a database as a non-production scratch/test database. */\nexport const TEST_DB_SUFFIX = \"-test\";\n\n/**\n * Parse the target database name out of a MongoDB connection URI.\n *\n * The database name is the path segment after the host(s), before any query\n * string (`?...`). Handles both `mongodb://` and `mongodb+srv://` URIs and any\n * userinfo / multi-host / option components. Returns `null` when the URI\n * carries no database name (e.g. `mongodb://localhost:27017` or a trailing\n * slash with nothing after it) — callers must treat a `null` name as\n * prod-shaped and never silently default to a production database.\n *\n * Implemented as manual string parsing rather than `new URL()` because Node's\n * URL parser rejects multi-host `mongodb+srv` authorities and mishandles the\n * comma-separated seed-list form that real connection strings use.\n */\nexport function parseDbName(uri: string): string | null {\n // Strip the scheme.\n const schemeMatch = /^mongodb(\\+srv)?:\\/\\//i.exec(uri);\n if (!schemeMatch) return null;\n let rest = uri.slice(schemeMatch[0].length);\n\n // Drop query string and fragment — the DB name precedes both.\n const qIdx = rest.search(/[?#]/);\n if (qIdx !== -1) rest = rest.slice(0, qIdx);\n\n // The path begins at the first '/' after the authority. Everything before\n // that first slash is userinfo + host(s); everything after is the DB name.\n const slashIdx = rest.indexOf(\"/\");\n if (slashIdx === -1) return null;\n\n const dbName = rest.slice(slashIdx + 1).trim();\n return dbName.length > 0 ? dbName : null;\n}\n\n/**\n * Classify a database name. A name is a \"test\" database (no confirmation\n * required) only when it is non-null and ends in {@link TEST_DB_SUFFIX}.\n * Everything else — including a `null` name — is prod-shaped.\n */\nexport function isTestDb(dbName: string | null): boolean {\n return dbName !== null && dbName.endsWith(TEST_DB_SUFFIX);\n}\n","/**\n * @htilabs/platform-common-models — read-only MongoDB catalogue\n *\n * The verifier reaches MongoDB ONLY through this interface. It exposes two\n * read operations and nothing else: there is no method here that can create,\n * write, or drop anything. The read-only guarantee is enforced by the type,\n * not by convention.\n *\n * Injecting the catalogue also keeps the package's test suite free of a real\n * MongoDB, matching how `runCvcBootCheck` injects `exit` and `logger`.\n */\n\nexport interface MongoCatalog {\n /** Names of databases that physically exist (i.e. hold data). */\n listDatabases(): Promise<string[]>;\n /** Names of collections that physically exist in `database`. */\n listCollections(database: string): Promise<string[]>;\n}\n\n/**\n * Minimal structural view of a `mongodb` MongoClient. Declared structurally so\n * this package takes no dependency on the `mongodb` driver — apps pass their\n * own client, whatever major version they are on.\n */\nexport interface MongoClientLike {\n db(name?: string): {\n admin(): {\n listDatabases(): Promise<{ databases: Array<{ name: string }> }>;\n };\n listCollections(\n filter?: Record<string, unknown>,\n options?: Record<string, unknown>,\n ): { toArray(): Promise<Array<{ name: string }>> };\n };\n}\n\n/** Minimal structural view of a Mongoose Connection. */\nexport interface MongooseConnectionLike {\n getClient(): MongoClientLike;\n}\n\n/** Build a catalogue from a native `mongodb` client. */\nexport function catalogFromClient(client: MongoClientLike): MongoCatalog {\n return {\n async listDatabases(): Promise<string[]> {\n const { databases } = await client.db().admin().listDatabases();\n return databases.map((d) => d.name);\n },\n async listCollections(database: string): Promise<string[]> {\n // `nameOnly` keeps the server from materializing collection options.\n const infos = await client\n .db(database)\n .listCollections({}, { nameOnly: true })\n .toArray();\n return infos.map((c) => c.name);\n },\n };\n}\n\n/** Build a catalogue from an open Mongoose connection. */\nexport function catalogFromMongoose(\n connection: MongooseConnectionLike,\n): MongoCatalog {\n return catalogFromClient(connection.getClient());\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACkBA,qBAA6B;AAC7B,kBAAsB;AAqEf,SAAS,aAAa,iBAA0C;AACrE,MAAI;AACJ,MAAI;AACF,cAAM,6BAAa,iBAAiB,MAAM;AAAA,EAC5C,SAAS,KAAK;AACZ,UAAM,MACJ,eAAe,QAAQ,IAAI,UAAU,OAAO,GAAG;AACjD,UAAM,IAAI;AAAA,MACR,wCAAwC,eAAe,KAAK,GAAG;AAAA,IACjE;AAAA,EACF;AACA,QAAM,aAAS,mBAAM,GAAG;AACxB,MAAI,CAAC,UAAU,OAAO,WAAW,UAAU;AACzC,UAAM,IAAI;AAAA,MACR,4BAA4B,eAAe;AAAA,IAC7C;AAAA,EACF;AACA,MAAI,OAAO,YAAY,GAAG;AACxB,UAAM,IAAI;AAAA,MACR,4BAA4B,eAAe,kCAAkC,OAAO,OAAO;AAAA,IAC7F;AAAA,EACF;AACA,MAAI,CAAC,OAAO,aAAa,OAAO,OAAO,cAAc,UAAU;AAC7D,UAAM,IAAI;AAAA,MACR,4BAA4B,eAAe;AAAA,IAC7C;AAAA,EACF;AACA,SAAO;AACT;AAgEO,SAAS,eACd,MACA,KACoB;AACpB,MAAI,CAAC,KAAK,QAAS,QAAO;AAC1B,QAAM,IAAI,KAAK,QAAQ,GAAG;AAC1B,MAAI,MAAM,OAAW,QAAO;AAC5B,SAAO,OAAO,CAAC;AACjB;;;ACjIA,IAAM,MAAM;AAWL,SAAS,gBACd,KACA,cAC2B;AAC3B,MAAI,QAAQ,UAAa,QAAQ,KAAM,QAAO;AAE9C,MAAI,OAAO,QAAQ,YAAY,MAAM,QAAQ,GAAG,GAAG;AACjD,UAAM,IAAI,MAAM,GAAG,GAAG,IAAI,YAAY,6BAA6B;AAAA,EACrE;AAEA,QAAM,QAAQ;AAEd,MAAI,CAAC,MAAM,QAAQ,MAAM,SAAS,KAAK,MAAM,UAAU,WAAW,GAAG;AACnE,UAAM,IAAI;AAAA,MACR,GAAG,GAAG,IAAI,YAAY;AAAA,IACxB;AAAA,EACF;AAEA,QAAM,UAAU,QAAQ,CAAC,IAAI,MAAM;AACjC,UAAM,QAAQ,GAAG,YAAY,qBAAqB,CAAC;AACnD,QAAI,CAAC,MAAM,OAAO,OAAO,UAAU;AACjC,YAAM,IAAI,MAAM,GAAG,GAAG,IAAI,KAAK,oBAAoB;AAAA,IACrD;AACA,QAAI,OAAO,GAAG,WAAW,YAAY,GAAG,OAAO,WAAW,GAAG;AAC3D,YAAM,IAAI,MAAM,GAAG,GAAG,IAAI,KAAK,oCAAoC;AAAA,IACrE;AACA,QAAI,OAAO,GAAG,YAAY,YAAY,GAAG,QAAQ,WAAW,GAAG;AAC7D,YAAM,IAAI,MAAM,GAAG,GAAG,IAAI,KAAK,qCAAqC;AAAA,IACtE;AACA,QAAI,CAAC,MAAM,QAAQ,GAAG,WAAW,GAAG;AAClC,YAAM,IAAI,MAAM,GAAG,GAAG,IAAI,KAAK,6BAA6B;AAAA,IAC9D;AACA,OAAG,YAAY,QAAQ,CAAC,GAAG,MAAM;AAC/B,UAAI,OAAO,MAAM,YAAY,EAAE,WAAW,GAAG;AAC3C,cAAM,IAAI;AAAA,UACR,GAAG,GAAG,IAAI,KAAK,gBAAgB,CAAC;AAAA,QAClC;AAAA,MACF;AAAA,IACF,CAAC;AAAA,EACH,CAAC;AAED,MAAI,MAAM,iBAAiB,QAAW;AACpC,QAAI,OAAO,MAAM,iBAAiB,YAAY,MAAM,QAAQ,MAAM,YAAY,GAAG;AAC/E,YAAM,IAAI;AAAA,QACR,GAAG,GAAG,IAAI,YAAY;AAAA,MACxB;AAAA,IACF;AACA,eAAW,CAAC,KAAK,MAAM,KAAK,OAAO,QAAQ,MAAM,YAAY,GAAG;AAC9D,UAAI,OAAO,WAAW,YAAY,OAAO,WAAW,GAAG;AACrD,cAAM,IAAI;AAAA,UACR,GAAG,GAAG,IAAI,YAAY,wBAAwB,GAAG;AAAA,QACnD;AAAA,MACF;AAAA,IACF;AAAA,EACF;AAEA,SAAO;AAAA,IACL,cAAc,MAAM;AAAA,IACpB,WAAW,MAAM;AAAA,EACnB;AACF;AAWO,SAAS,iBACd,QACA,OACA,KACA,UACe;AACf,QAAM,SAAS,WAAW,GAAG;AAC7B,MAAI,CAAC,OAAQ,QAAO;AACpB,MAAI,OAAO,SAAS,MAAM,EAAG,QAAO;AAEpC,SACE,GAAG,KAAK,KAAK,MAAM,kCAAkC,GAAG,oCACvB,MAAM;AAG3C;;;AC7IO,IAAM,0BAA0B;AAchC,SAAS,aAAa,GAAW,GAAW,MAAM,UAAkB;AACzE,MAAI,MAAM,EAAG,QAAO;AACpB,MAAI,KAAK,IAAI,EAAE,SAAS,EAAE,MAAM,IAAI,IAAK,QAAO,MAAM;AAGtD,MAAI,QAAQ,IAAI,MAAc,EAAE,SAAS,CAAC,EAAE,KAAK,CAAC;AAClD,MAAI,OAAO,MAAM,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,GAAG,CAAC,GAAG,MAAM,CAAC;AAC3D,MAAI,OAAO,IAAI,MAAc,EAAE,SAAS,CAAC;AAEzC,WAAS,IAAI,GAAG,KAAK,EAAE,QAAQ,KAAK;AAClC,SAAK,CAAC,IAAI;AACV,QAAI,SAAS,KAAK,CAAC;AACnB,aAAS,IAAI,GAAG,KAAK,EAAE,QAAQ,KAAK;AAClC,YAAM,OAAO,EAAE,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,IAAI,IAAI;AACzC,UAAI,IAAI,KAAK;AAAA,QACX,KAAK,CAAC,IAAI;AAAA;AAAA,QACV,KAAK,IAAI,CAAC,IAAI;AAAA;AAAA,QACd,KAAK,IAAI,CAAC,IAAI;AAAA;AAAA,MAChB;AACA,UAAI,IAAI,KAAK,IAAI,KAAK,EAAE,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,GAAG;AACpE,YAAI,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC;AAAA,MAClC;AACA,WAAK,CAAC,IAAI;AACV,UAAI,IAAI,OAAQ,UAAS;AAAA,IAC3B;AAEA,QAAI,SAAS,IAAK,QAAO,MAAM;AAC/B,KAAC,OAAO,MAAM,IAAI,IAAI,CAAC,MAAM,MAAM,KAAK;AAAA,EAC1C;AAEA,SAAO,KAAK,EAAE,MAAM;AACtB;AAGA,SAAS,aAAa,MAAsB;AAC1C,SAAO,KAAK,QAAQ,aAAa,EAAE;AACrC;AAiBO,SAAS,iBAAiB,GAAW,GAAoB;AAC9D,MAAI,MAAM,EAAG,QAAO;AACpB,QAAM,QAAQ,aAAa,CAAC;AAC5B,QAAM,QAAQ,aAAa,CAAC;AAG5B,SAAO,UAAU,UAAU,UAAU,KAAK,UAAU;AACtD;AAgBO,SAAS,aAAa,MAAc,YAAyC;AAClF,MAAI,OAAiB,CAAC;AACtB,MAAI,eAAe,0BAA0B;AAE7C,aAAW,aAAa,YAAY;AAClC,QAAI,cAAc,KAAM,QAAO,CAAC;AAChC,QAAI,iBAAiB,MAAM,SAAS,EAAG;AAEvC,UAAM,IAAI,aAAa,MAAM,WAAW,uBAAuB;AAC/D,QAAI,IAAI,wBAAyB;AAEjC,QAAI,IAAI,cAAc;AACpB,qBAAe;AACf,aAAO,CAAC,SAAS;AAAA,IACnB,WAAW,MAAM,cAAc;AAC7B,WAAK,KAAK,SAAS;AAAA,IACrB;AAAA,EACF;AAEA,SAAO,KAAK,KAAK;AACnB;AAGO,SAAS,kBAAkB,OAAkC;AAClE,QAAM,SAAS,MAAM,IAAI,CAAC,MAAM,IAAI,CAAC,GAAG;AACxC,MAAI,OAAO,UAAU,EAAG,QAAO,OAAO,CAAC,KAAK;AAC5C,SAAO,GAAG,OAAO,MAAM,GAAG,EAAE,EAAE,KAAK,IAAI,CAAC,OAAO,OAAO,OAAO,SAAS,CAAC,CAAC;AAC1E;;;AC1HO,IAAM,iBAAiB;AAgBvB,SAAS,YAAY,KAA4B;AAEtD,QAAM,cAAc,yBAAyB,KAAK,GAAG;AACrD,MAAI,CAAC,YAAa,QAAO;AACzB,MAAI,OAAO,IAAI,MAAM,YAAY,CAAC,EAAE,MAAM;AAG1C,QAAM,OAAO,KAAK,OAAO,MAAM;AAC/B,MAAI,SAAS,GAAI,QAAO,KAAK,MAAM,GAAG,IAAI;AAI1C,QAAM,WAAW,KAAK,QAAQ,GAAG;AACjC,MAAI,aAAa,GAAI,QAAO;AAE5B,QAAM,SAAS,KAAK,MAAM,WAAW,CAAC,EAAE,KAAK;AAC7C,SAAO,OAAO,SAAS,IAAI,SAAS;AACtC;AAOO,SAAS,SAAS,QAAgC;AACvD,SAAO,WAAW,QAAQ,OAAO,SAAS,cAAc;AAC1D;;;ACVO,SAAS,kBAAkB,QAAuC;AACvE,SAAO;AAAA,IACL,MAAM,gBAAmC;AACvC,YAAM,EAAE,UAAU,IAAI,MAAM,OAAO,GAAG,EAAE,MAAM,EAAE,cAAc;AAC9D,aAAO,UAAU,IAAI,CAAC,MAAM,EAAE,IAAI;AAAA,IACpC;AAAA,IACA,MAAM,gBAAgB,UAAqC;AAEzD,YAAM,QAAQ,MAAM,OACjB,GAAG,QAAQ,EACX,gBAAgB,CAAC,GAAG,EAAE,UAAU,KAAK,CAAC,EACtC,QAAQ;AACX,aAAO,MAAM,IAAI,CAAC,MAAM,EAAE,IAAI;AAAA,IAChC;AAAA,EACF;AACF;AAGO,SAAS,oBACd,YACc;AACd,SAAO,kBAAkB,WAAW,UAAU,CAAC;AACjD;;;ALRA,IAAMA,OAAM;AA+DZ,SAAS,cACP,MACA,UACA,KACA,YACmD;AACnD,QAAM,UAAU,SAAS,UAAU,KAAK,MAAM;AAC9C,QAAM,MACJ,WAAW,KAAK,MAAM,MACrB,UAAU,eAAe,SAAS,GAAG,IAAI;AAE5C,MAAI,QAAQ,UAAa,QAAQ,IAAI;AAGnC,QAAI,WAAW,QAAQ,aAAa,MAAO,QAAO,EAAE,MAAM,KAAK;AAC/D,WAAO,EAAE,OAAO,GAAG,KAAK,MAAM,2CAA2C;AAAA,EAC3E;AAEA,MAAI,KAAK,WAAW,KAAK,QAAS,QAAO,EAAE,MAAM,IAAI;AAErD,QAAM,SAAS,YAAY,GAAG;AAC9B,MAAI,WAAW,MAAM;AACnB,WAAO;AAAA,MACL,OACE,GAAG,KAAK,MAAM;AAAA,IAElB;AAAA,EACF;AACA,SAAO,EAAE,MAAM,OAAO;AACxB;AAEA,eAAe,eACb,MACA,QACA,OACA,KACA,SACA,mBACoB;AACpB,QAAM,WAAsB,CAAC;AAI7B,QAAM,YAAY,iBAAiB,QAAQ,KAAK,QAAQ,KAAK,MAAM,YAAY;AAC/E,MAAI,WAAW;AACb,aAAS,KAAK;AAAA,MACZ,UAAU;AAAA,MACV,MAAM;AAAA,MACN,SAAS;AAAA,MACT,OAAO,KAAK;AAAA,MACZ,UAAU;AAAA,IACZ,CAAC;AAED,WAAO;AAAA,EACT;AAGA,MAAI,CAAC,kBAAkB,SAAS,MAAM,GAAG;AACvC,UAAM,cAAc,aAAa,QAAQ,iBAAiB;AAC1D,QAAI,YAAY,SAAS,GAAG;AAC1B,eAAS,KAAK;AAAA,QACZ,UAAU;AAAA,QACV,MAAM;AAAA,QACN,SACE,GAAG,KAAK,MAAM,KAAK,MAAM,kCACT,kBAAkB,WAAW,CAAC;AAAA,QAChD,OAAO,KAAK;AAAA,QACZ,UAAU;AAAA,QACV;AAAA,MACF,CAAC;AAAA,IACH,OAAO;AACL,eAAS,KAAK;AAAA,QACZ,UAAU;AAAA,QACV,MAAM;AAAA,QACN,SACE,GAAG,KAAK,MAAM,KAAK,MAAM;AAAA,QAE3B,OAAO,KAAK;AAAA,QACZ,UAAU;AAAA,MACZ,CAAC;AAAA,IACH;AAEA,WAAO;AAAA,EACT;AAOA,MAAI,KAAK,YAAY,WAAW,EAAG,QAAO;AAG1C,QAAM,SAAS,MAAM,QAAQ,gBAAgB,MAAM;AAEnD,aAAW,YAAY,KAAK,aAAa;AACvC,QAAI,OAAO,SAAS,QAAQ,EAAG;AAE/B,UAAM,cAAc,aAAa,UAAU,MAAM;AACjD,QAAI,YAAY,SAAS,GAAG;AAC1B,eAAS,KAAK;AAAA,QACZ,UAAU;AAAA,QACV,MAAM;AAAA,QACN,SACE,GAAG,MAAM,0BAA0B,QAAQ,kCAC3B,kBAAkB,WAAW,CAAC;AAAA,QAChD,OAAO,KAAK;AAAA,QACZ,UAAU;AAAA,QACV,YAAY;AAAA,QACZ;AAAA,MACF,CAAC;AAAA,IACH,OAAO;AACL,eAAS,KAAK;AAAA,QACZ,UAAU;AAAA,QACV,MAAM;AAAA,QACN,SACE,GAAG,MAAM,0BAA0B,QAAQ;AAAA,QAE7C,OAAO,KAAK;AAAA,QACZ,UAAU;AAAA,QACV,YAAY;AAAA,MACd,CAAC;AAAA,IACH;AAAA,EACF;AAEA,QAAM,cAAc,IAAI,IAAI,KAAK,WAAW;AAC5C,aAAW,WAAW,QAAQ;AAC5B,QAAI,YAAY,IAAI,OAAO,EAAG;AAC9B,aAAS,KAAK;AAAA,MACZ,UAAU;AAAA,MACV,MAAM;AAAA,MACN,SACE,GAAG,MAAM,iBAAiB,OAAO;AAAA,MAEnC,OAAO,KAAK;AAAA,MACZ,UAAU;AAAA,MACV,YAAY;AAAA,IACd,CAAC;AAAA,EACH;AAEA,SAAO;AACT;AAgBA,eAAsB,YACpB,iBACA,MAC4B;AAC5B,QAAM,aAAa,KAAK,cAAc,QAAQ;AAC9C,QAAM,SAAS,KAAK,UAAU;AAC9B,QAAM,OAAO,KAAK,SAAS,CAAC,SAAiB,QAAQ,KAAK,IAAI;AAC9D,QAAM,MAAM,KAAK,OAAO,WAAW,YAAY;AAE/C,QAAM,WAAW,aAAa,eAAe;AAC7C,QAAM,QAAQ,gBAAgB,SAAS,OAAO,eAAe;AAC7D,MAAI,UAAU,KAAM,QAAO,EAAE,IAAI,MAAM,UAAU,CAAC,EAAE;AAEpD,QAAM,WAAsB,CAAC;AAC7B,QAAM,WAAuD,CAAC;AAE9D,aAAW,QAAQ,MAAM,WAAW;AAClC,UAAM,EAAE,MAAM,OAAO,KAAK,IAAI,cAAc,MAAM,UAAU,KAAK,UAAU;AAC3E,QAAI,KAAM;AACV,QAAI,UAAU,UAAa,SAAS,QAAW;AAC7C,eAAS,KAAK;AAAA,QACZ,UAAU;AAAA,QACV,MAAM;AAAA,QACN,SAAS,SAAS,GAAG,KAAK,MAAM;AAAA,QAChC,OAAO,KAAK;AAAA,MACd,CAAC;AACD;AAAA,IACF;AACA,aAAS,KAAK,EAAE,MAAM,KAAK,CAAC;AAAA,EAC9B;AAGA,QAAM,oBACJ,SAAS,SAAS,IAAI,MAAM,KAAK,QAAQ,cAAc,IAAI,CAAC;AAE9D,aAAW,EAAE,MAAM,KAAK,KAAK,UAAU;AACrC,aAAS;AAAA,MACP,GAAI,MAAM;AAAA,QACR;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA,QACA,KAAK;AAAA,QACL;AAAA,MACF;AAAA,IACF;AAAA,EACF;AAEA,QAAM,SAAS,SAAS,OAAO,CAAC,MAAM,EAAE,aAAa,OAAO;AAC5D,QAAM,QAAQ,SAAS,OAAO,CAAC,MAAM,EAAE,aAAa,MAAM;AAE1D,aAAW,KAAK,MAAO,QAAO,KAAK,GAAGA,IAAG,IAAI,EAAE,OAAO,EAAE;AAExD,MAAI,OAAO,SAAS,GAAG;AACrB,UAAM,UAAU;AAAA,MACd,GAAGA,IAAG,2BAA2B,eAAe,UAAU,GAAG;AAAA,MAC7D,GAAG,OAAO,MAAM;AAAA,MAChB,GAAG,OAAO,IAAI,CAAC,MAAM,OAAO,EAAE,OAAO,EAAE;AAAA,IACzC,EAAE,KAAK,IAAI;AAEX,QAAI,KAAK,eAAgB,OAAM,IAAI,MAAM,OAAO;AAChD,WAAO,MAAM,OAAO;AACpB,SAAK,CAAC;AAAA,EACR;AAEA,SAAO,EAAE,IAAI,OAAO,WAAW,GAAG,SAAS;AAC7C;","names":["TAG"]}
|
package/dist/mongo/index.js
CHANGED
package/dist/mongo/index.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"sources":["../../src/config/index.ts","../../src/mongo/contract.ts","../../src/mongo/similarity.ts","../../src/mongo/uri.ts","../../src/mongo/catalog.ts","../../src/mongo/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 * validateAgainstContract also LOADS config, not just validates it: it applies\n * the contract's per-tier defaults into process.env so that code reading\n * process.env.FOO directly sees the same value the validator resolved. This is\n * what removes the need for a materialized `.env.generated` file in local dev.\n *\n * Precedence, highest first:\n * 1. .env.local — local developer overrides; beat everything\n * 2. process.env — real deployed / materialized task-def values\n * 3. contract default — spec.default[<tier>]\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 { existsSync, readFileSync } from \"node:fs\";\nimport { join } from \"node:path\";\n\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 * Apply the contract's defaults for the resolved env into process.env for\n * every runtime variable that is not already set. Defaults to true.\n * An existing process.env value is never overwritten.\n */\n applyDefaults?: boolean;\n /**\n * Load `.env.local` and apply it over process.env before anything else.\n * Defaults to true; the file is optional, so a missing file is a no-op.\n */\n applyEnvLocal?: boolean;\n /**\n * Explicit path to the `.env.local` override file.\n * Defaults to `<process.cwd()>/.env.local`.\n */\n envLocalPath?: string;\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/**\n * Write the contract's defaults for `env` into process.env for every\n * runtime-phase variable that is not already set.\n *\n * A value already present in process.env — a real deployed env var, or one\n * materialized into a task definition — always wins and is left untouched.\n * An explicitly empty value (\"\") counts as present: it is a deliberate\n * choice by whoever set it, and the required-variable check still rejects it.\n *\n * Build-phase variables are skipped (R3.4); secret variables are NOT skipped,\n * so process.env agrees with the value the validator itself resolved. Secret\n * values are never logged.\n *\n * Returns the names of the variables that were applied.\n */\nexport function applyContractDefaults(\n contract: ServiceContract,\n env: string,\n): string[] {\n const applied: string[] = [];\n\n for (const [key, spec] of Object.entries(contract.variables)) {\n if (spec.phase === \"build\") continue;\n if (process.env[key] !== undefined) continue;\n\n const value = resolveDefault(spec, env);\n if (value === undefined) continue;\n\n process.env[key] = value;\n applied.push(key);\n }\n\n return applied;\n}\n\n// ─── .env.local overrides ────────────────────────────────────────────────────\n\n/** `KEY=`, `export KEY=`; everything after the first `=` is the raw value. */\nconst DOTENV_LINE = /^(?:export\\s+)?([A-Za-z_][A-Za-z0-9_]*)\\s*=(.*)$/;\n\n/** Index of the next `quote` not preceded by a backslash, or -1. */\nfunction indexOfUnescaped(s: string, quote: string): number {\n for (let i = 0; i < s.length; i += 1) {\n if (s[i] === \"\\\\\") {\n i += 1;\n continue;\n }\n if (s[i] === quote) return i;\n }\n return -1;\n}\n\n/**\n * Parse `.env` file content into a plain object.\n *\n * Supported: blank lines, `#` comments, an optional `export ` prefix,\n * single-quoted / double-quoted / backtick-quoted values (which may span\n * multiple lines), and `\\n` `\\r` `\\t` `\\\\` escapes inside double quotes.\n * An unquoted value ends at a ` #` inline comment, so `#` may still be used\n * freely inside a quoted value or in the middle of a bare word.\n *\n * Malformed lines are skipped rather than thrown on: a typo in a developer's\n * local override file should not take down the whole process.\n */\nexport function parseDotenv(content: string): Record<string, string> {\n const out: Record<string, string> = {};\n const lines = content.split(/\\r?\\n/);\n\n for (let i = 0; i < lines.length; i += 1) {\n const trimmed = lines[i].trim();\n if (trimmed === \"\" || trimmed.startsWith(\"#\")) continue;\n\n const match = DOTENV_LINE.exec(trimmed);\n if (!match) continue;\n\n const key = match[1];\n const rest = match[2].trim();\n const quote = rest.charAt(0);\n\n if (quote === '\"' || quote === \"'\" || quote === \"`\") {\n // Quoted value — keep consuming lines until the closing quote.\n let body = rest.slice(1);\n let end = indexOfUnescaped(body, quote);\n while (end === -1 && i + 1 < lines.length) {\n i += 1;\n body += `\\n${lines[i]}`;\n end = indexOfUnescaped(body, quote);\n }\n if (end === -1) continue; // unterminated quote — skip the entry\n\n const value = body.slice(0, end);\n out[key] =\n quote === '\"'\n ? value\n .replace(/\\\\n/g, \"\\n\")\n .replace(/\\\\r/g, \"\\r\")\n .replace(/\\\\t/g, \"\\t\")\n .replace(/\\\\\"/g, '\"')\n .replace(/\\\\\\\\/g, \"\\\\\")\n : value;\n continue;\n }\n\n out[key] = rest.split(/\\s+#/)[0].trimEnd();\n }\n\n return out;\n}\n\n/**\n * Apply `.env.local` over process.env.\n *\n * `.env.local` has the last word in local development: it overwrites values\n * already present in process.env, and it runs before defaults are applied, so\n * it also beats every contract default. It may declare variables the contract\n * does not know about — a developer can add config without editing the\n * contract. The file is optional; a missing file is a no-op.\n *\n * Returns the names of the variables that were applied.\n */\nexport function applyEnvLocal(path?: string): string[] {\n const file = path ?? join(process.cwd(), \".env.local\");\n if (!existsSync(file)) return [];\n\n let raw: string;\n try {\n raw = readFileSync(file, \"utf8\");\n } catch (err) {\n const msg = err instanceof Error ? err.message : String(err);\n throw new Error(`[platform-common/config] Cannot read ${file}: ${msg}`);\n }\n\n const parsed = parseDotenv(raw);\n for (const [key, value] of Object.entries(parsed)) {\n process.env[key] = value;\n }\n\n return Object.keys(parsed);\n}\n\n// ─── validateAgainstContract ─────────────────────────────────────────────────\n\n/**\n * Parse `runtimeYamlPath`, load config into `process.env`, coerce every\n * runtime-phase variable, and fail fast on any missing or invalid required\n * variable (R3.2).\n *\n * Loading happens before validation, in precedence order:\n * 1. `.env.local` is applied over process.env (opts.applyEnvLocal)\n * 2. contract defaults for the resolved env fill anything still unset\n * (opts.applyDefaults)\n *\n * `.env.local` is applied first so a developer can set NODE_ENV there and\n * have it select the tier whose defaults are applied.\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\n if (opts.applyEnvLocal !== false) {\n applyEnvLocal(opts.envLocalPath);\n }\n\n const env =\n opts.env ??\n (process.env.NODE_ENV as string | undefined) ??\n \"local\";\n\n if (opts.applyDefaults !== false) {\n applyContractDefaults(contract, env);\n }\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","/**\n * @htilabs/platform-common-models — `mongo:` contract block\n *\n * Extends the HTI Runtime Config Contract (`config/runtime/<service>.yaml`)\n * with a declaration of the databases and collections a service expects.\n *\n * The declaration is deliberately data, not code: `expansion` is Python and\n * parses the same YAML. Nothing here may depend on a TypeScript-only construct.\n *\n * ## Why declared rather than introspected\n *\n * Reading collection names off registered Mongoose models would cover only the\n * Mongoose apps (thread, leads, pave) and would report false findings: thread\n * registers `AgencyInfo` (collection `agencyinfos`), which exists in NO\n * database because nothing has ever written to it. Mongo creates collections\n * lazily. A declaration states intent; introspection only restates the code.\n */\n\n/** One database a service connects to, and the collections it uses. */\nexport interface MongoDbSpec {\n /** Contract variable holding the database NAME (e.g. `THREAD_DB`). */\n db_var: string;\n /**\n * Contract variable holding the connection URI or cluster prefix\n * (e.g. `MONGODB_CLUSTER`). When the URI already embeds a database name and\n * no `db_var` applies, set `db_var` to the same variable — the name is then\n * parsed out of the URI.\n */\n uri_var: string;\n /**\n * Collections the service reads or writes. Declare only what the service\n * USES — not everything present in the database. An undeclared collection\n * present in Mongo is reported, never fatal.\n *\n * An EMPTY list opts out of collection checking entirely: only the database\n * name is verified, and `listCollections` is never called. Use it when a\n * service reaches a database whose collections it cannot practically\n * enumerate. Declaring even one collection opts back in.\n */\n collections: string[];\n}\n\n/**\n * Per-environment database-name affinity. When the deploy environment has an\n * entry here, every resolved database name must end with the given suffix.\n *\n * This generalizes thread's `assertTestDb` (packages/db/src/connections.ts):\n * it is the only check that catches a test run pointed at a production\n * database, and it needs no connection to MongoDB.\n */\nexport type EnvAffinity = Record<string, string>;\n\nexport interface MongoContractBlock {\n /** e.g. `{ test: \"-test\", dev: \"-dev\" }`. Environments omitted are unconstrained. */\n env_affinity?: EnvAffinity;\n databases: MongoDbSpec[];\n}\n\n/** Prefix for every diagnostic this module emits. */\nconst TAG = \"[platform-common/mongo]\";\n\n/**\n * Validate and normalize the `mongo:` block of a parsed contract.\n *\n * Returns `null` when the contract declares no `mongo:` block — a service that\n * does not use MongoDB is not an error.\n *\n * Throws on a malformed block: a contract that lies about its shape is a\n * programming error, not a runtime finding.\n */\nexport function parseMongoBlock(\n raw: unknown,\n contractPath: string,\n): MongoContractBlock | null {\n if (raw === undefined || raw === null) return null;\n\n if (typeof raw !== \"object\" || Array.isArray(raw)) {\n throw new Error(`${TAG} ${contractPath}: \"mongo\" must be a mapping`);\n }\n\n const block = raw as Partial<MongoContractBlock>;\n\n if (!Array.isArray(block.databases) || block.databases.length === 0) {\n throw new Error(\n `${TAG} ${contractPath}: \"mongo.databases\" must be a non-empty list`,\n );\n }\n\n block.databases.forEach((db, i) => {\n const where = `${contractPath}: mongo.databases[${i}]`;\n if (!db || typeof db !== \"object\") {\n throw new Error(`${TAG} ${where} must be a mapping`);\n }\n if (typeof db.db_var !== \"string\" || db.db_var.length === 0) {\n throw new Error(`${TAG} ${where}.db_var must be a non-empty string`);\n }\n if (typeof db.uri_var !== \"string\" || db.uri_var.length === 0) {\n throw new Error(`${TAG} ${where}.uri_var must be a non-empty string`);\n }\n if (!Array.isArray(db.collections)) {\n throw new Error(`${TAG} ${where}.collections must be a list`);\n }\n db.collections.forEach((c, j) => {\n if (typeof c !== \"string\" || c.length === 0) {\n throw new Error(\n `${TAG} ${where}.collections[${j}] must be a non-empty string`,\n );\n }\n });\n });\n\n if (block.env_affinity !== undefined) {\n if (typeof block.env_affinity !== \"object\" || Array.isArray(block.env_affinity)) {\n throw new Error(\n `${TAG} ${contractPath}: \"mongo.env_affinity\" must be a mapping of env -> suffix`,\n );\n }\n for (const [env, suffix] of Object.entries(block.env_affinity)) {\n if (typeof suffix !== \"string\" || suffix.length === 0) {\n throw new Error(\n `${TAG} ${contractPath}: mongo.env_affinity.${env} must be a non-empty string`,\n );\n }\n }\n }\n\n return {\n env_affinity: block.env_affinity,\n databases: block.databases as MongoDbSpec[],\n };\n}\n\n/**\n * Check a resolved database name against the environment's affinity suffix.\n *\n * Returns `null` when the name is acceptable (or the environment declares no\n * affinity), otherwise a human-readable violation message.\n *\n * Requires NO MongoDB connection. This is the check that catches\n * `NODE_ENV=test` pointed at `platform-db`.\n */\nexport function checkEnvAffinity(\n dbName: string,\n dbVar: string,\n env: string,\n affinity: EnvAffinity | undefined,\n): string | null {\n const suffix = affinity?.[env];\n if (!suffix) return null;\n if (dbName.endsWith(suffix)) return null;\n\n return (\n `${dbVar}=\"${dbName}\" is not valid in environment \"${env}\": ` +\n `database names must end with \"${suffix}\". ` +\n `Refusing to run against a database outside this environment.`\n );\n}\n","/**\n * @htilabs/platform-common-models — name-similarity heuristic\n *\n * A missing database or collection is AMBIGUOUS. MongoDB creates namespaces\n * lazily, on first write, so \"absent\" means either:\n *\n * (a) a typo — the name is wrong and the real one exists nearby, or\n * (b) unseeded — the environment is new and nothing has been written yet.\n *\n * Guessing wrong in direction (b) is expensive: a fatal check would ground\n * every cold-start ephemeral deploy. So absence alone is never fatal. Only\n * absence WITH a plausible near-neighbour is treated as a typo.\n */\n\n/** Maximum edit distance at which a neighbouring name is considered a typo. */\nexport const TYPO_DISTANCE_THRESHOLD = 2;\n\n/**\n * Optimal String Alignment distance (Damerau-Levenshtein restricted to\n * adjacent transpositions), bounded: returns `max + 1` as soon as the true\n * distance is known to exceed `max`. Bounding keeps this cheap across the\n * ~90-database catalogue scanned on each lookup.\n *\n * A transposition MUST cost 1, not 2. `platform-dve` is a transposition of\n * `platform-dev`, but plain Levenshtein scores it 2 -- tying it with the\n * unrelated PRODUCTION name `platform-db` and letting iteration order pick.\n * Steering an operator toward a production database because they typo'd a dev\n * one is a worse failure than suggesting nothing at all.\n */\nexport function editDistance(a: string, b: string, max = Infinity): number {\n if (a === b) return 0;\n if (Math.abs(a.length - b.length) > max) return max + 1;\n\n // Three rows: prev2 carries i-2 so an adjacent transposition costs 1.\n let prev2 = new Array<number>(b.length + 1).fill(0);\n let prev = Array.from({ length: b.length + 1 }, (_, i) => i);\n let curr = new Array<number>(b.length + 1);\n\n for (let i = 1; i <= a.length; i++) {\n curr[0] = i;\n let rowMin = curr[0];\n for (let j = 1; j <= b.length; j++) {\n const cost = a[i - 1] === b[j - 1] ? 0 : 1;\n let d = Math.min(\n prev[j] + 1, // deletion\n curr[j - 1] + 1, // insertion\n prev[j - 1] + cost, // substitution\n );\n if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1]) {\n d = Math.min(d, prev2[j - 2] + 1); // adjacent transposition\n }\n curr[j] = d;\n if (d < rowMin) rowMin = d;\n }\n // Every remaining row can only grow: bail out early.\n if (rowMin > max) return max + 1;\n [prev2, prev, curr] = [prev, curr, prev2];\n }\n\n return prev[b.length];\n}\n\n/** Strip a trailing ordinal token: `demo2` -> `demo`, `cypress-tests-3` -> `cypress-tests`. */\nfunction stripOrdinal(name: string): string {\n return name.replace(/[-_]?\\d+$/, \"\");\n}\n\n/**\n * True when two names look like sibling environments rather than a typo of\n * each other — that is, they differ ONLY in a trailing ordinal.\n *\n * This guard is mandatory, not cosmetic. The live cluster contains\n * `leads-platform-demo` beside `leads-platform-demo2` (edit distance 1) and\n * `cypress-tests-1/2/3`. Without it, provisioning `leads-platform-demo3` would\n * find `demo2` one edit away, be branded a typo, and hard-fail a healthy new\n * environment — reintroducing exactly the cold-start breakage the severity\n * model exists to prevent.\n *\n * The guard is deliberately biased toward WARN: a genuine typo that happens to\n * differ only in a trailing digit is downgraded to a warning rather than\n * risking a false fatal.\n */\nexport function isOrdinalSibling(a: string, b: string): boolean {\n if (a === b) return false;\n const baseA = stripOrdinal(a);\n const baseB = stripOrdinal(b);\n // Both must reduce to the same base, and at least one must have carried an\n // ordinal (otherwise stripping changed nothing and this is a real edit).\n return baseA === baseB && (baseA !== a || baseB !== b);\n}\n\n/**\n * Find the existing names most likely to be what `name` was meant to be.\n *\n * Returns EVERY candidate at the minimal distance, not one arbitrary winner.\n * `thread-dv` is one edit from both `thread-dev` and `thread-db`; picking\n * between them by iteration order could point an operator at production. When\n * the evidence is ambiguous, say so.\n *\n * Returns an empty array when nothing is close enough, or when the only close\n * matches are sibling environments (see {@link isOrdinalSibling}). Empty means\n * \"absent, but no evidence of a typo\" — the caller warns rather than fails.\n *\n * Results are sorted for deterministic messages.\n */\nexport function nearestNames(name: string, candidates: readonly string[]): string[] {\n let best: string[] = [];\n let bestDistance = TYPO_DISTANCE_THRESHOLD + 1;\n\n for (const candidate of candidates) {\n if (candidate === name) return []; // exact match: not missing at all\n if (isOrdinalSibling(name, candidate)) continue;\n\n const d = editDistance(name, candidate, TYPO_DISTANCE_THRESHOLD);\n if (d > TYPO_DISTANCE_THRESHOLD) continue;\n\n if (d < bestDistance) {\n bestDistance = d;\n best = [candidate];\n } else if (d === bestDistance) {\n best.push(candidate);\n }\n }\n\n return best.sort();\n}\n\n/** Render one or more suggestions as `\"a\"`, or `\"a\" or \"b\"`, or `\"a\", \"b\" or \"c\"`. */\nexport function formatSuggestions(names: readonly string[]): string {\n const quoted = names.map((n) => `\"${n}\"`);\n if (quoted.length <= 1) return quoted[0] ?? \"\";\n return `${quoted.slice(0, -1).join(\", \")} or ${quoted[quoted.length - 1]}`;\n}\n","/**\n * @htilabs/platform-common-models — MongoDB URI parsing\n *\n * Home of the connection-string parsing shared by the seed guard\n * (`scripts/lib/confirmTargetDb.ts`) and the runtime verifier\n * (`src/mongo/index.ts`). It lives in `src/` so both can import one\n * implementation; `scripts/` cannot be imported from `src/` at build time.\n */\n\n/** Suffix that marks a database as a non-production scratch/test database. */\nexport const TEST_DB_SUFFIX = \"-test\";\n\n/**\n * Parse the target database name out of a MongoDB connection URI.\n *\n * The database name is the path segment after the host(s), before any query\n * string (`?...`). Handles both `mongodb://` and `mongodb+srv://` URIs and any\n * userinfo / multi-host / option components. Returns `null` when the URI\n * carries no database name (e.g. `mongodb://localhost:27017` or a trailing\n * slash with nothing after it) — callers must treat a `null` name as\n * prod-shaped and never silently default to a production database.\n *\n * Implemented as manual string parsing rather than `new URL()` because Node's\n * URL parser rejects multi-host `mongodb+srv` authorities and mishandles the\n * comma-separated seed-list form that real connection strings use.\n */\nexport function parseDbName(uri: string): string | null {\n // Strip the scheme.\n const schemeMatch = /^mongodb(\\+srv)?:\\/\\//i.exec(uri);\n if (!schemeMatch) return null;\n let rest = uri.slice(schemeMatch[0].length);\n\n // Drop query string and fragment — the DB name precedes both.\n const qIdx = rest.search(/[?#]/);\n if (qIdx !== -1) rest = rest.slice(0, qIdx);\n\n // The path begins at the first '/' after the authority. Everything before\n // that first slash is userinfo + host(s); everything after is the DB name.\n const slashIdx = rest.indexOf(\"/\");\n if (slashIdx === -1) return null;\n\n const dbName = rest.slice(slashIdx + 1).trim();\n return dbName.length > 0 ? dbName : null;\n}\n\n/**\n * Classify a database name. A name is a \"test\" database (no confirmation\n * required) only when it is non-null and ends in {@link TEST_DB_SUFFIX}.\n * Everything else — including a `null` name — is prod-shaped.\n */\nexport function isTestDb(dbName: string | null): boolean {\n return dbName !== null && dbName.endsWith(TEST_DB_SUFFIX);\n}\n","/**\n * @htilabs/platform-common-models — read-only MongoDB catalogue\n *\n * The verifier reaches MongoDB ONLY through this interface. It exposes two\n * read operations and nothing else: there is no method here that can create,\n * write, or drop anything. The read-only guarantee is enforced by the type,\n * not by convention.\n *\n * Injecting the catalogue also keeps the package's test suite free of a real\n * MongoDB, matching how `runCvcBootCheck` injects `exit` and `logger`.\n */\n\nexport interface MongoCatalog {\n /** Names of databases that physically exist (i.e. hold data). */\n listDatabases(): Promise<string[]>;\n /** Names of collections that physically exist in `database`. */\n listCollections(database: string): Promise<string[]>;\n}\n\n/**\n * Minimal structural view of a `mongodb` MongoClient. Declared structurally so\n * this package takes no dependency on the `mongodb` driver — apps pass their\n * own client, whatever major version they are on.\n */\nexport interface MongoClientLike {\n db(name?: string): {\n admin(): {\n listDatabases(): Promise<{ databases: Array<{ name: string }> }>;\n };\n listCollections(\n filter?: Record<string, unknown>,\n options?: Record<string, unknown>,\n ): { toArray(): Promise<Array<{ name: string }>> };\n };\n}\n\n/** Minimal structural view of a Mongoose Connection. */\nexport interface MongooseConnectionLike {\n getClient(): MongoClientLike;\n}\n\n/** Build a catalogue from a native `mongodb` client. */\nexport function catalogFromClient(client: MongoClientLike): MongoCatalog {\n return {\n async listDatabases(): Promise<string[]> {\n const { databases } = await client.db().admin().listDatabases();\n return databases.map((d) => d.name);\n },\n async listCollections(database: string): Promise<string[]> {\n // `nameOnly` keeps the server from materializing collection options.\n const infos = await client\n .db(database)\n .listCollections({}, { nameOnly: true })\n .toArray();\n return infos.map((c) => c.name);\n },\n };\n}\n\n/** Build a catalogue from an open Mongoose connection. */\nexport function catalogFromMongoose(\n connection: MongooseConnectionLike,\n): MongoCatalog {\n return catalogFromClient(connection.getClient());\n}\n","/**\n * @htilabs/platform-common-models — MongoDB connection/collection verifier\n *\n * Sibling to `./config`. Where `validateAgainstContract` proves the env vars\n * are present and well-typed, `verifyMongo` proves they point somewhere real.\n *\n * ## What this catches\n * - a database name that does not exist and looks like a typo of one that does\n * - a collection name that does not exist and looks like a typo of one that does\n * - a database name that does not belong to the current environment\n * (env-affinity; needs no connection — generalizes thread's `assertTestDb`)\n * - collections present in MongoDB but undeclared by the service (reported)\n *\n * ## What this CANNOT catch\n * A plausible-but-wrong POPULATED database. `leads-platform-prod-test` exists\n * and carries the same collection names as `leads-platform-test`; every\n * name-existence check passes. Detecting that needs an identity marker\n * written inside the database, which is outside this utility's read-only\n * remit. Do not claim otherwise in adoption docs.\n *\n * ## Read-only\n * Reaches MongoDB solely through {@link MongoCatalog}: listDatabases and\n * listCollections. It never creates, writes, or drops anything.\n *\n * ## Severity\n * MongoDB creates namespaces lazily, so ABSENCE IS AMBIGUOUS (typo vs\n * unseeded environment). Absence alone warns; absence with a plausible\n * near-neighbour is fatal. See `similarity.ts`.\n *\n * FACT (verified 2026-07-10, read-only): thread registers the Mongoose model\n * `AgencyInfo` (collection `agencyinfos`), and that collection exists in\n * neither `platform-test` (15 collections) nor `platform-dev` (41). A\n * registered model with zero documents has no collection. The warn-on-absence\n * rule exists because of this; do not \"tighten\" it to fatal.\n */\n\nimport {\n loadContract,\n resolveDefault,\n type ServiceContract,\n} from \"../config/index.js\";\nimport {\n parseMongoBlock,\n checkEnvAffinity,\n type MongoContractBlock,\n type MongoDbSpec,\n} from \"./contract.js\";\nimport { nearestNames, formatSuggestions } from \"./similarity.js\";\nimport { parseDbName } from \"./uri.js\";\nimport type { MongoCatalog } from \"./catalog.js\";\n\nexport type { MongoCatalog, MongoClientLike, MongooseConnectionLike } from \"./catalog.js\";\nexport { catalogFromClient, catalogFromMongoose } from \"./catalog.js\";\nexport type { MongoContractBlock, MongoDbSpec, EnvAffinity } from \"./contract.js\";\nexport { parseDbName, isTestDb, TEST_DB_SUFFIX } from \"./uri.js\";\n\nconst TAG = \"[platform-common/mongo]\";\n\nexport type Severity = \"fatal\" | \"warn\";\n\nexport type FindingKind =\n | \"env_var_missing\"\n | \"db_shape_violation\"\n | \"db_absent_typo\"\n | \"db_absent_unseeded\"\n | \"collection_absent_typo\"\n | \"collection_absent_unseeded\"\n | \"collection_undeclared\";\n\nexport interface Finding {\n severity: Severity;\n kind: FindingKind;\n message: string;\n dbVar?: string;\n database?: string;\n collection?: string;\n /**\n * Existing names this looks like a typo of. More than one means the evidence\n * is ambiguous — the message lists them all rather than guessing.\n */\n suggestions?: string[];\n}\n\nexport interface MongoVerifyReport {\n /** True when no fatal finding was produced. Warnings do not clear `ok`. */\n ok: boolean;\n findings: Finding[];\n}\n\nexport interface VerifyMongoOptions {\n /** Read-only catalogue. Required — this package takes no driver dependency. */\n catalog: MongoCatalog;\n /** Environment name for affinity checks. Defaults to NODE_ENV, then \"local\". */\n env?: string;\n /** Env source. Defaults to `process.env`. */\n processEnv?: NodeJS.ProcessEnv;\n /** If true, throw instead of `exit(1)`. Defaults to false (production exits). */\n throwOnFailure?: boolean;\n /** Injected for tests. Defaults to `process.exit`. */\n exit?: (code: number) => never;\n /** Injected for tests. Defaults to `console`. */\n logger?: Pick<Console, \"error\" | \"warn\">;\n}\n\n/**\n * Resolve the database name for a spec, applying the same per-environment\n * defaults that `validateAgainstContract` applies. Reading `process.env` alone\n * would miss a value the contract supplies as a default (thread declares\n * `PLATFORM_DB.default.prod: platform-prod`) and report a false fatal.\n *\n * When `db_var` and `uri_var` name the same variable, the database is embedded\n * in the connection string (auth does this for `LEADS_MONGODB_URI` and\n * friends) and must be parsed out of it.\n *\n * A variable the contract marks `required: false` and that carries no value is\n * SKIPPED, not failed: thread's `PAVE_DB` is optional and its absence simply\n * means the read-only pave connection is not configured. Required-ness comes\n * from the contract so there is no second place to declare it.\n */\nfunction resolveDbName(\n spec: MongoDbSpec,\n contract: ServiceContract,\n env: string,\n processEnv: NodeJS.ProcessEnv,\n): { name?: string; error?: string; skip?: boolean } {\n const varSpec = contract.variables[spec.db_var];\n const raw =\n processEnv[spec.db_var] ??\n (varSpec ? resolveDefault(varSpec, env) : undefined);\n\n if (raw === undefined || raw === \"\") {\n // A variable absent from `variables` is treated as required: the mongo\n // block references something the contract never declared.\n if (varSpec && varSpec.required === false) return { skip: true };\n return { error: `${spec.db_var}: required by mongo contract but not set` };\n }\n\n if (spec.db_var !== spec.uri_var) return { name: raw };\n\n const parsed = parseDbName(raw);\n if (parsed === null) {\n return {\n error:\n `${spec.db_var}: connection string carries no database name. ` +\n `Either embed one (mongodb://host/<db>) or declare a separate db_var.`,\n };\n }\n return { name: parsed };\n}\n\nasync function verifyDatabase(\n spec: MongoDbSpec,\n dbName: string,\n block: MongoContractBlock,\n env: string,\n catalog: MongoCatalog,\n existingDatabases: readonly string[],\n): Promise<Finding[]> {\n const findings: Finding[] = [];\n\n // 1. Env affinity — no connection required, and the only check that catches\n // a test run pointed at production.\n const violation = checkEnvAffinity(dbName, spec.db_var, env, block.env_affinity);\n if (violation) {\n findings.push({\n severity: \"fatal\",\n kind: \"db_shape_violation\",\n message: violation,\n dbVar: spec.db_var,\n database: dbName,\n });\n // A database in the wrong environment must not be probed further.\n return findings;\n }\n\n // 2. Existence.\n if (!existingDatabases.includes(dbName)) {\n const suggestions = nearestNames(dbName, existingDatabases);\n if (suggestions.length > 0) {\n findings.push({\n severity: \"fatal\",\n kind: \"db_absent_typo\",\n message:\n `${spec.db_var}=\"${dbName}\" does not exist. ` +\n `Did you mean ${formatSuggestions(suggestions)}?`,\n dbVar: spec.db_var,\n database: dbName,\n suggestions,\n });\n } else {\n findings.push({\n severity: \"warn\",\n kind: \"db_absent_unseeded\",\n message:\n `${spec.db_var}=\"${dbName}\" does not exist yet. Treating as an ` +\n `unseeded environment; MongoDB will create it on first write.`,\n dbVar: spec.db_var,\n database: dbName,\n });\n }\n // Nothing to compare collections against.\n return findings;\n }\n\n // 3. An empty `collections` list opts out of collection checking: verify the\n // database NAME only. This lets a service adopt incrementally — expansion\n // reaches the leads databases but enumerating their collections is not\n // tractable, and sweeping a 467MB database would emit a warning per\n // collection. Declaring even one collection opts back in.\n if (spec.collections.length === 0) return findings;\n\n // 4. Collections, both directions.\n const actual = await catalog.listCollections(dbName);\n\n for (const declared of spec.collections) {\n if (actual.includes(declared)) continue;\n\n const suggestions = nearestNames(declared, actual);\n if (suggestions.length > 0) {\n findings.push({\n severity: \"fatal\",\n kind: \"collection_absent_typo\",\n message:\n `${dbName}: declared collection \"${declared}\" does not exist. ` +\n `Did you mean ${formatSuggestions(suggestions)}?`,\n dbVar: spec.db_var,\n database: dbName,\n collection: declared,\n suggestions,\n });\n } else {\n findings.push({\n severity: \"warn\",\n kind: \"collection_absent_unseeded\",\n message:\n `${dbName}: declared collection \"${declared}\" does not exist yet ` +\n `(no documents written). MongoDB creates collections lazily.`,\n dbVar: spec.db_var,\n database: dbName,\n collection: declared,\n });\n }\n }\n\n const declaredSet = new Set(spec.collections);\n for (const present of actual) {\n if (declaredSet.has(present)) continue;\n findings.push({\n severity: \"warn\",\n kind: \"collection_undeclared\",\n message:\n `${dbName}: collection \"${present}\" exists but is not declared in the ` +\n `mongo contract.`,\n dbVar: spec.db_var,\n database: dbName,\n collection: present,\n });\n }\n\n return findings;\n}\n\n/**\n * Verify every database and collection declared in `runtimeYamlPath` against a\n * live MongoDB catalogue.\n *\n * Collects ALL findings before deciding, exactly as `validateAgainstContract`\n * does — an operator fixing a misconfiguration should see every problem at\n * once, not one per restart.\n *\n * Resolves to the report when no fatal finding is produced. On a fatal finding\n * it prints every finding and calls `exit(1)`, or throws when\n * `throwOnFailure` is set.\n *\n * A contract with no `mongo:` block is a no-op success.\n */\nexport async function verifyMongo(\n runtimeYamlPath: string,\n opts: VerifyMongoOptions,\n): Promise<MongoVerifyReport> {\n const processEnv = opts.processEnv ?? process.env;\n const logger = opts.logger ?? console;\n const exit = opts.exit ?? ((code: number) => process.exit(code));\n const env = opts.env ?? processEnv.NODE_ENV ?? \"local\";\n\n const contract = loadContract(runtimeYamlPath);\n const block = parseMongoBlock(contract.mongo, runtimeYamlPath);\n if (block === null) return { ok: true, findings: [] };\n\n const findings: Finding[] = [];\n const resolved: Array<{ spec: MongoDbSpec; name: string }> = [];\n\n for (const spec of block.databases) {\n const { name, error, skip } = resolveDbName(spec, contract, env, processEnv);\n if (skip) continue; // optional database, not configured in this environment\n if (error !== undefined || name === undefined) {\n findings.push({\n severity: \"fatal\",\n kind: \"env_var_missing\",\n message: error ?? `${spec.db_var}: unresolved`,\n dbVar: spec.db_var,\n });\n continue;\n }\n resolved.push({ spec, name });\n }\n\n // One catalogue read shared across every database in the contract.\n const existingDatabases =\n resolved.length > 0 ? await opts.catalog.listDatabases() : [];\n\n for (const { spec, name } of resolved) {\n findings.push(\n ...(await verifyDatabase(\n spec,\n name,\n block,\n env,\n opts.catalog,\n existingDatabases,\n )),\n );\n }\n\n const fatals = findings.filter((f) => f.severity === \"fatal\");\n const warns = findings.filter((f) => f.severity === \"warn\");\n\n for (const w of warns) logger.warn(`${TAG} ${w.message}`);\n\n if (fatals.length > 0) {\n const message = [\n `${TAG} verifyMongo failed for ${runtimeYamlPath} (env \"${env}\")`,\n `${fatals.length} fatal finding(s):`,\n ...fatals.map((f) => ` - ${f.message}`),\n ].join(\"\\n\");\n\n if (opts.throwOnFailure) throw new Error(message);\n logger.error(message);\n exit(1);\n }\n\n return { ok: fatals.length === 0, findings };\n}\n"],"mappings":";AA4BA,SAAS,YAAY,oBAAoB;AACzC,SAAS,YAAY;AAErB,SAAS,aAAa;AAqFf,SAAS,aAAa,iBAA0C;AACrE,MAAI;AACJ,MAAI;AACF,UAAM,aAAa,iBAAiB,MAAM;AAAA,EAC5C,SAAS,KAAK;AACZ,UAAM,MACJ,eAAe,QAAQ,IAAI,UAAU,OAAO,GAAG;AACjD,UAAM,IAAI;AAAA,MACR,wCAAwC,eAAe,KAAK,GAAG;AAAA,IACjE;AAAA,EACF;AACA,QAAM,SAAS,MAAM,GAAG;AACxB,MAAI,CAAC,UAAU,OAAO,WAAW,UAAU;AACzC,UAAM,IAAI;AAAA,MACR,4BAA4B,eAAe;AAAA,IAC7C;AAAA,EACF;AACA,MAAI,OAAO,YAAY,GAAG;AACxB,UAAM,IAAI;AAAA,MACR,4BAA4B,eAAe,kCAAkC,OAAO,OAAO;AAAA,IAC7F;AAAA,EACF;AACA,MAAI,CAAC,OAAO,aAAa,OAAO,OAAO,cAAc,UAAU;AAC7D,UAAM,IAAI;AAAA,MACR,4BAA4B,eAAe;AAAA,IAC7C;AAAA,EACF;AACA,SAAO;AACT;AAgEO,SAAS,eACd,MACA,KACoB;AACpB,MAAI,CAAC,KAAK,QAAS,QAAO;AAC1B,QAAM,IAAI,KAAK,QAAQ,GAAG;AAC1B,MAAI,MAAM,OAAW,QAAO;AAC5B,SAAO,OAAO,CAAC;AACjB;;;AC7JA,IAAM,MAAM;AAWL,SAAS,gBACd,KACA,cAC2B;AAC3B,MAAI,QAAQ,UAAa,QAAQ,KAAM,QAAO;AAE9C,MAAI,OAAO,QAAQ,YAAY,MAAM,QAAQ,GAAG,GAAG;AACjD,UAAM,IAAI,MAAM,GAAG,GAAG,IAAI,YAAY,6BAA6B;AAAA,EACrE;AAEA,QAAM,QAAQ;AAEd,MAAI,CAAC,MAAM,QAAQ,MAAM,SAAS,KAAK,MAAM,UAAU,WAAW,GAAG;AACnE,UAAM,IAAI;AAAA,MACR,GAAG,GAAG,IAAI,YAAY;AAAA,IACxB;AAAA,EACF;AAEA,QAAM,UAAU,QAAQ,CAAC,IAAI,MAAM;AACjC,UAAM,QAAQ,GAAG,YAAY,qBAAqB,CAAC;AACnD,QAAI,CAAC,MAAM,OAAO,OAAO,UAAU;AACjC,YAAM,IAAI,MAAM,GAAG,GAAG,IAAI,KAAK,oBAAoB;AAAA,IACrD;AACA,QAAI,OAAO,GAAG,WAAW,YAAY,GAAG,OAAO,WAAW,GAAG;AAC3D,YAAM,IAAI,MAAM,GAAG,GAAG,IAAI,KAAK,oCAAoC;AAAA,IACrE;AACA,QAAI,OAAO,GAAG,YAAY,YAAY,GAAG,QAAQ,WAAW,GAAG;AAC7D,YAAM,IAAI,MAAM,GAAG,GAAG,IAAI,KAAK,qCAAqC;AAAA,IACtE;AACA,QAAI,CAAC,MAAM,QAAQ,GAAG,WAAW,GAAG;AAClC,YAAM,IAAI,MAAM,GAAG,GAAG,IAAI,KAAK,6BAA6B;AAAA,IAC9D;AACA,OAAG,YAAY,QAAQ,CAAC,GAAG,MAAM;AAC/B,UAAI,OAAO,MAAM,YAAY,EAAE,WAAW,GAAG;AAC3C,cAAM,IAAI;AAAA,UACR,GAAG,GAAG,IAAI,KAAK,gBAAgB,CAAC;AAAA,QAClC;AAAA,MACF;AAAA,IACF,CAAC;AAAA,EACH,CAAC;AAED,MAAI,MAAM,iBAAiB,QAAW;AACpC,QAAI,OAAO,MAAM,iBAAiB,YAAY,MAAM,QAAQ,MAAM,YAAY,GAAG;AAC/E,YAAM,IAAI;AAAA,QACR,GAAG,GAAG,IAAI,YAAY;AAAA,MACxB;AAAA,IACF;AACA,eAAW,CAAC,KAAK,MAAM,KAAK,OAAO,QAAQ,MAAM,YAAY,GAAG;AAC9D,UAAI,OAAO,WAAW,YAAY,OAAO,WAAW,GAAG;AACrD,cAAM,IAAI;AAAA,UACR,GAAG,GAAG,IAAI,YAAY,wBAAwB,GAAG;AAAA,QACnD;AAAA,MACF;AAAA,IACF;AAAA,EACF;AAEA,SAAO;AAAA,IACL,cAAc,MAAM;AAAA,IACpB,WAAW,MAAM;AAAA,EACnB;AACF;AAWO,SAAS,iBACd,QACA,OACA,KACA,UACe;AACf,QAAM,SAAS,WAAW,GAAG;AAC7B,MAAI,CAAC,OAAQ,QAAO;AACpB,MAAI,OAAO,SAAS,MAAM,EAAG,QAAO;AAEpC,SACE,GAAG,KAAK,KAAK,MAAM,kCAAkC,GAAG,oCACvB,MAAM;AAG3C;;;AC7IO,IAAM,0BAA0B;AAchC,SAAS,aAAa,GAAW,GAAW,MAAM,UAAkB;AACzE,MAAI,MAAM,EAAG,QAAO;AACpB,MAAI,KAAK,IAAI,EAAE,SAAS,EAAE,MAAM,IAAI,IAAK,QAAO,MAAM;AAGtD,MAAI,QAAQ,IAAI,MAAc,EAAE,SAAS,CAAC,EAAE,KAAK,CAAC;AAClD,MAAI,OAAO,MAAM,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,GAAG,CAAC,GAAG,MAAM,CAAC;AAC3D,MAAI,OAAO,IAAI,MAAc,EAAE,SAAS,CAAC;AAEzC,WAAS,IAAI,GAAG,KAAK,EAAE,QAAQ,KAAK;AAClC,SAAK,CAAC,IAAI;AACV,QAAI,SAAS,KAAK,CAAC;AACnB,aAAS,IAAI,GAAG,KAAK,EAAE,QAAQ,KAAK;AAClC,YAAM,OAAO,EAAE,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,IAAI,IAAI;AACzC,UAAI,IAAI,KAAK;AAAA,QACX,KAAK,CAAC,IAAI;AAAA;AAAA,QACV,KAAK,IAAI,CAAC,IAAI;AAAA;AAAA,QACd,KAAK,IAAI,CAAC,IAAI;AAAA;AAAA,MAChB;AACA,UAAI,IAAI,KAAK,IAAI,KAAK,EAAE,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,GAAG;AACpE,YAAI,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC;AAAA,MAClC;AACA,WAAK,CAAC,IAAI;AACV,UAAI,IAAI,OAAQ,UAAS;AAAA,IAC3B;AAEA,QAAI,SAAS,IAAK,QAAO,MAAM;AAC/B,KAAC,OAAO,MAAM,IAAI,IAAI,CAAC,MAAM,MAAM,KAAK;AAAA,EAC1C;AAEA,SAAO,KAAK,EAAE,MAAM;AACtB;AAGA,SAAS,aAAa,MAAsB;AAC1C,SAAO,KAAK,QAAQ,aAAa,EAAE;AACrC;AAiBO,SAAS,iBAAiB,GAAW,GAAoB;AAC9D,MAAI,MAAM,EAAG,QAAO;AACpB,QAAM,QAAQ,aAAa,CAAC;AAC5B,QAAM,QAAQ,aAAa,CAAC;AAG5B,SAAO,UAAU,UAAU,UAAU,KAAK,UAAU;AACtD;AAgBO,SAAS,aAAa,MAAc,YAAyC;AAClF,MAAI,OAAiB,CAAC;AACtB,MAAI,eAAe,0BAA0B;AAE7C,aAAW,aAAa,YAAY;AAClC,QAAI,cAAc,KAAM,QAAO,CAAC;AAChC,QAAI,iBAAiB,MAAM,SAAS,EAAG;AAEvC,UAAM,IAAI,aAAa,MAAM,WAAW,uBAAuB;AAC/D,QAAI,IAAI,wBAAyB;AAEjC,QAAI,IAAI,cAAc;AACpB,qBAAe;AACf,aAAO,CAAC,SAAS;AAAA,IACnB,WAAW,MAAM,cAAc;AAC7B,WAAK,KAAK,SAAS;AAAA,IACrB;AAAA,EACF;AAEA,SAAO,KAAK,KAAK;AACnB;AAGO,SAAS,kBAAkB,OAAkC;AAClE,QAAM,SAAS,MAAM,IAAI,CAAC,MAAM,IAAI,CAAC,GAAG;AACxC,MAAI,OAAO,UAAU,EAAG,QAAO,OAAO,CAAC,KAAK;AAC5C,SAAO,GAAG,OAAO,MAAM,GAAG,EAAE,EAAE,KAAK,IAAI,CAAC,OAAO,OAAO,OAAO,SAAS,CAAC,CAAC;AAC1E;;;AC1HO,IAAM,iBAAiB;AAgBvB,SAAS,YAAY,KAA4B;AAEtD,QAAM,cAAc,yBAAyB,KAAK,GAAG;AACrD,MAAI,CAAC,YAAa,QAAO;AACzB,MAAI,OAAO,IAAI,MAAM,YAAY,CAAC,EAAE,MAAM;AAG1C,QAAM,OAAO,KAAK,OAAO,MAAM;AAC/B,MAAI,SAAS,GAAI,QAAO,KAAK,MAAM,GAAG,IAAI;AAI1C,QAAM,WAAW,KAAK,QAAQ,GAAG;AACjC,MAAI,aAAa,GAAI,QAAO;AAE5B,QAAM,SAAS,KAAK,MAAM,WAAW,CAAC,EAAE,KAAK;AAC7C,SAAO,OAAO,SAAS,IAAI,SAAS;AACtC;AAOO,SAAS,SAAS,QAAgC;AACvD,SAAO,WAAW,QAAQ,OAAO,SAAS,cAAc;AAC1D;;;ACVO,SAAS,kBAAkB,QAAuC;AACvE,SAAO;AAAA,IACL,MAAM,gBAAmC;AACvC,YAAM,EAAE,UAAU,IAAI,MAAM,OAAO,GAAG,EAAE,MAAM,EAAE,cAAc;AAC9D,aAAO,UAAU,IAAI,CAAC,MAAM,EAAE,IAAI;AAAA,IACpC;AAAA,IACA,MAAM,gBAAgB,UAAqC;AAEzD,YAAM,QAAQ,MAAM,OACjB,GAAG,QAAQ,EACX,gBAAgB,CAAC,GAAG,EAAE,UAAU,KAAK,CAAC,EACtC,QAAQ;AACX,aAAO,MAAM,IAAI,CAAC,MAAM,EAAE,IAAI;AAAA,IAChC;AAAA,EACF;AACF;AAGO,SAAS,oBACd,YACc;AACd,SAAO,kBAAkB,WAAW,UAAU,CAAC;AACjD;;;ACRA,IAAMA,OAAM;AA+DZ,SAAS,cACP,MACA,UACA,KACA,YACmD;AACnD,QAAM,UAAU,SAAS,UAAU,KAAK,MAAM;AAC9C,QAAM,MACJ,WAAW,KAAK,MAAM,MACrB,UAAU,eAAe,SAAS,GAAG,IAAI;AAE5C,MAAI,QAAQ,UAAa,QAAQ,IAAI;AAGnC,QAAI,WAAW,QAAQ,aAAa,MAAO,QAAO,EAAE,MAAM,KAAK;AAC/D,WAAO,EAAE,OAAO,GAAG,KAAK,MAAM,2CAA2C;AAAA,EAC3E;AAEA,MAAI,KAAK,WAAW,KAAK,QAAS,QAAO,EAAE,MAAM,IAAI;AAErD,QAAM,SAAS,YAAY,GAAG;AAC9B,MAAI,WAAW,MAAM;AACnB,WAAO;AAAA,MACL,OACE,GAAG,KAAK,MAAM;AAAA,IAElB;AAAA,EACF;AACA,SAAO,EAAE,MAAM,OAAO;AACxB;AAEA,eAAe,eACb,MACA,QACA,OACA,KACA,SACA,mBACoB;AACpB,QAAM,WAAsB,CAAC;AAI7B,QAAM,YAAY,iBAAiB,QAAQ,KAAK,QAAQ,KAAK,MAAM,YAAY;AAC/E,MAAI,WAAW;AACb,aAAS,KAAK;AAAA,MACZ,UAAU;AAAA,MACV,MAAM;AAAA,MACN,SAAS;AAAA,MACT,OAAO,KAAK;AAAA,MACZ,UAAU;AAAA,IACZ,CAAC;AAED,WAAO;AAAA,EACT;AAGA,MAAI,CAAC,kBAAkB,SAAS,MAAM,GAAG;AACvC,UAAM,cAAc,aAAa,QAAQ,iBAAiB;AAC1D,QAAI,YAAY,SAAS,GAAG;AAC1B,eAAS,KAAK;AAAA,QACZ,UAAU;AAAA,QACV,MAAM;AAAA,QACN,SACE,GAAG,KAAK,MAAM,KAAK,MAAM,kCACT,kBAAkB,WAAW,CAAC;AAAA,QAChD,OAAO,KAAK;AAAA,QACZ,UAAU;AAAA,QACV;AAAA,MACF,CAAC;AAAA,IACH,OAAO;AACL,eAAS,KAAK;AAAA,QACZ,UAAU;AAAA,QACV,MAAM;AAAA,QACN,SACE,GAAG,KAAK,MAAM,KAAK,MAAM;AAAA,QAE3B,OAAO,KAAK;AAAA,QACZ,UAAU;AAAA,MACZ,CAAC;AAAA,IACH;AAEA,WAAO;AAAA,EACT;AAOA,MAAI,KAAK,YAAY,WAAW,EAAG,QAAO;AAG1C,QAAM,SAAS,MAAM,QAAQ,gBAAgB,MAAM;AAEnD,aAAW,YAAY,KAAK,aAAa;AACvC,QAAI,OAAO,SAAS,QAAQ,EAAG;AAE/B,UAAM,cAAc,aAAa,UAAU,MAAM;AACjD,QAAI,YAAY,SAAS,GAAG;AAC1B,eAAS,KAAK;AAAA,QACZ,UAAU;AAAA,QACV,MAAM;AAAA,QACN,SACE,GAAG,MAAM,0BAA0B,QAAQ,kCAC3B,kBAAkB,WAAW,CAAC;AAAA,QAChD,OAAO,KAAK;AAAA,QACZ,UAAU;AAAA,QACV,YAAY;AAAA,QACZ;AAAA,MACF,CAAC;AAAA,IACH,OAAO;AACL,eAAS,KAAK;AAAA,QACZ,UAAU;AAAA,QACV,MAAM;AAAA,QACN,SACE,GAAG,MAAM,0BAA0B,QAAQ;AAAA,QAE7C,OAAO,KAAK;AAAA,QACZ,UAAU;AAAA,QACV,YAAY;AAAA,MACd,CAAC;AAAA,IACH;AAAA,EACF;AAEA,QAAM,cAAc,IAAI,IAAI,KAAK,WAAW;AAC5C,aAAW,WAAW,QAAQ;AAC5B,QAAI,YAAY,IAAI,OAAO,EAAG;AAC9B,aAAS,KAAK;AAAA,MACZ,UAAU;AAAA,MACV,MAAM;AAAA,MACN,SACE,GAAG,MAAM,iBAAiB,OAAO;AAAA,MAEnC,OAAO,KAAK;AAAA,MACZ,UAAU;AAAA,MACV,YAAY;AAAA,IACd,CAAC;AAAA,EACH;AAEA,SAAO;AACT;AAgBA,eAAsB,YACpB,iBACA,MAC4B;AAC5B,QAAM,aAAa,KAAK,cAAc,QAAQ;AAC9C,QAAM,SAAS,KAAK,UAAU;AAC9B,QAAM,OAAO,KAAK,SAAS,CAAC,SAAiB,QAAQ,KAAK,IAAI;AAC9D,QAAM,MAAM,KAAK,OAAO,WAAW,YAAY;AAE/C,QAAM,WAAW,aAAa,eAAe;AAC7C,QAAM,QAAQ,gBAAgB,SAAS,OAAO,eAAe;AAC7D,MAAI,UAAU,KAAM,QAAO,EAAE,IAAI,MAAM,UAAU,CAAC,EAAE;AAEpD,QAAM,WAAsB,CAAC;AAC7B,QAAM,WAAuD,CAAC;AAE9D,aAAW,QAAQ,MAAM,WAAW;AAClC,UAAM,EAAE,MAAM,OAAO,KAAK,IAAI,cAAc,MAAM,UAAU,KAAK,UAAU;AAC3E,QAAI,KAAM;AACV,QAAI,UAAU,UAAa,SAAS,QAAW;AAC7C,eAAS,KAAK;AAAA,QACZ,UAAU;AAAA,QACV,MAAM;AAAA,QACN,SAAS,SAAS,GAAG,KAAK,MAAM;AAAA,QAChC,OAAO,KAAK;AAAA,MACd,CAAC;AACD;AAAA,IACF;AACA,aAAS,KAAK,EAAE,MAAM,KAAK,CAAC;AAAA,EAC9B;AAGA,QAAM,oBACJ,SAAS,SAAS,IAAI,MAAM,KAAK,QAAQ,cAAc,IAAI,CAAC;AAE9D,aAAW,EAAE,MAAM,KAAK,KAAK,UAAU;AACrC,aAAS;AAAA,MACP,GAAI,MAAM;AAAA,QACR;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA,QACA,KAAK;AAAA,QACL;AAAA,MACF;AAAA,IACF;AAAA,EACF;AAEA,QAAM,SAAS,SAAS,OAAO,CAAC,MAAM,EAAE,aAAa,OAAO;AAC5D,QAAM,QAAQ,SAAS,OAAO,CAAC,MAAM,EAAE,aAAa,MAAM;AAE1D,aAAW,KAAK,MAAO,QAAO,KAAK,GAAGA,IAAG,IAAI,EAAE,OAAO,EAAE;AAExD,MAAI,OAAO,SAAS,GAAG;AACrB,UAAM,UAAU;AAAA,MACd,GAAGA,IAAG,2BAA2B,eAAe,UAAU,GAAG;AAAA,MAC7D,GAAG,OAAO,MAAM;AAAA,MAChB,GAAG,OAAO,IAAI,CAAC,MAAM,OAAO,EAAE,OAAO,EAAE;AAAA,IACzC,EAAE,KAAK,IAAI;AAEX,QAAI,KAAK,eAAgB,OAAM,IAAI,MAAM,OAAO;AAChD,WAAO,MAAM,OAAO;AACpB,SAAK,CAAC;AAAA,EACR;AAEA,SAAO,EAAE,IAAI,OAAO,WAAW,GAAG,SAAS;AAC7C;","names":["TAG"]}
|
|
1
|
+
{"version":3,"sources":["../../src/config/index.ts","../../src/mongo/contract.ts","../../src/mongo/similarity.ts","../../src/mongo/uri.ts","../../src/mongo/catalog.ts","../../src/mongo/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","/**\n * @htilabs/platform-common-models — `mongo:` contract block\n *\n * Extends the HTI Runtime Config Contract (`config/runtime/<service>.yaml`)\n * with a declaration of the databases and collections a service expects.\n *\n * The declaration is deliberately data, not code: `expansion` is Python and\n * parses the same YAML. Nothing here may depend on a TypeScript-only construct.\n *\n * ## Why declared rather than introspected\n *\n * Reading collection names off registered Mongoose models would cover only the\n * Mongoose apps (thread, leads, pave) and would report false findings: thread\n * registers `AgencyInfo` (collection `agencyinfos`), which exists in NO\n * database because nothing has ever written to it. Mongo creates collections\n * lazily. A declaration states intent; introspection only restates the code.\n */\n\n/** One database a service connects to, and the collections it uses. */\nexport interface MongoDbSpec {\n /** Contract variable holding the database NAME (e.g. `THREAD_DB`). */\n db_var: string;\n /**\n * Contract variable holding the connection URI or cluster prefix\n * (e.g. `MONGODB_CLUSTER`). When the URI already embeds a database name and\n * no `db_var` applies, set `db_var` to the same variable — the name is then\n * parsed out of the URI.\n */\n uri_var: string;\n /**\n * Collections the service reads or writes. Declare only what the service\n * USES — not everything present in the database. An undeclared collection\n * present in Mongo is reported, never fatal.\n *\n * An EMPTY list opts out of collection checking entirely: only the database\n * name is verified, and `listCollections` is never called. Use it when a\n * service reaches a database whose collections it cannot practically\n * enumerate. Declaring even one collection opts back in.\n */\n collections: string[];\n}\n\n/**\n * Per-environment database-name affinity. When the deploy environment has an\n * entry here, every resolved database name must end with the given suffix.\n *\n * This generalizes thread's `assertTestDb` (packages/db/src/connections.ts):\n * it is the only check that catches a test run pointed at a production\n * database, and it needs no connection to MongoDB.\n */\nexport type EnvAffinity = Record<string, string>;\n\nexport interface MongoContractBlock {\n /** e.g. `{ test: \"-test\", dev: \"-dev\" }`. Environments omitted are unconstrained. */\n env_affinity?: EnvAffinity;\n databases: MongoDbSpec[];\n}\n\n/** Prefix for every diagnostic this module emits. */\nconst TAG = \"[platform-common/mongo]\";\n\n/**\n * Validate and normalize the `mongo:` block of a parsed contract.\n *\n * Returns `null` when the contract declares no `mongo:` block — a service that\n * does not use MongoDB is not an error.\n *\n * Throws on a malformed block: a contract that lies about its shape is a\n * programming error, not a runtime finding.\n */\nexport function parseMongoBlock(\n raw: unknown,\n contractPath: string,\n): MongoContractBlock | null {\n if (raw === undefined || raw === null) return null;\n\n if (typeof raw !== \"object\" || Array.isArray(raw)) {\n throw new Error(`${TAG} ${contractPath}: \"mongo\" must be a mapping`);\n }\n\n const block = raw as Partial<MongoContractBlock>;\n\n if (!Array.isArray(block.databases) || block.databases.length === 0) {\n throw new Error(\n `${TAG} ${contractPath}: \"mongo.databases\" must be a non-empty list`,\n );\n }\n\n block.databases.forEach((db, i) => {\n const where = `${contractPath}: mongo.databases[${i}]`;\n if (!db || typeof db !== \"object\") {\n throw new Error(`${TAG} ${where} must be a mapping`);\n }\n if (typeof db.db_var !== \"string\" || db.db_var.length === 0) {\n throw new Error(`${TAG} ${where}.db_var must be a non-empty string`);\n }\n if (typeof db.uri_var !== \"string\" || db.uri_var.length === 0) {\n throw new Error(`${TAG} ${where}.uri_var must be a non-empty string`);\n }\n if (!Array.isArray(db.collections)) {\n throw new Error(`${TAG} ${where}.collections must be a list`);\n }\n db.collections.forEach((c, j) => {\n if (typeof c !== \"string\" || c.length === 0) {\n throw new Error(\n `${TAG} ${where}.collections[${j}] must be a non-empty string`,\n );\n }\n });\n });\n\n if (block.env_affinity !== undefined) {\n if (typeof block.env_affinity !== \"object\" || Array.isArray(block.env_affinity)) {\n throw new Error(\n `${TAG} ${contractPath}: \"mongo.env_affinity\" must be a mapping of env -> suffix`,\n );\n }\n for (const [env, suffix] of Object.entries(block.env_affinity)) {\n if (typeof suffix !== \"string\" || suffix.length === 0) {\n throw new Error(\n `${TAG} ${contractPath}: mongo.env_affinity.${env} must be a non-empty string`,\n );\n }\n }\n }\n\n return {\n env_affinity: block.env_affinity,\n databases: block.databases as MongoDbSpec[],\n };\n}\n\n/**\n * Check a resolved database name against the environment's affinity suffix.\n *\n * Returns `null` when the name is acceptable (or the environment declares no\n * affinity), otherwise a human-readable violation message.\n *\n * Requires NO MongoDB connection. This is the check that catches\n * `NODE_ENV=test` pointed at `platform-db`.\n */\nexport function checkEnvAffinity(\n dbName: string,\n dbVar: string,\n env: string,\n affinity: EnvAffinity | undefined,\n): string | null {\n const suffix = affinity?.[env];\n if (!suffix) return null;\n if (dbName.endsWith(suffix)) return null;\n\n return (\n `${dbVar}=\"${dbName}\" is not valid in environment \"${env}\": ` +\n `database names must end with \"${suffix}\". ` +\n `Refusing to run against a database outside this environment.`\n );\n}\n","/**\n * @htilabs/platform-common-models — name-similarity heuristic\n *\n * A missing database or collection is AMBIGUOUS. MongoDB creates namespaces\n * lazily, on first write, so \"absent\" means either:\n *\n * (a) a typo — the name is wrong and the real one exists nearby, or\n * (b) unseeded — the environment is new and nothing has been written yet.\n *\n * Guessing wrong in direction (b) is expensive: a fatal check would ground\n * every cold-start ephemeral deploy. So absence alone is never fatal. Only\n * absence WITH a plausible near-neighbour is treated as a typo.\n */\n\n/** Maximum edit distance at which a neighbouring name is considered a typo. */\nexport const TYPO_DISTANCE_THRESHOLD = 2;\n\n/**\n * Optimal String Alignment distance (Damerau-Levenshtein restricted to\n * adjacent transpositions), bounded: returns `max + 1` as soon as the true\n * distance is known to exceed `max`. Bounding keeps this cheap across the\n * ~90-database catalogue scanned on each lookup.\n *\n * A transposition MUST cost 1, not 2. `platform-dve` is a transposition of\n * `platform-dev`, but plain Levenshtein scores it 2 -- tying it with the\n * unrelated PRODUCTION name `platform-db` and letting iteration order pick.\n * Steering an operator toward a production database because they typo'd a dev\n * one is a worse failure than suggesting nothing at all.\n */\nexport function editDistance(a: string, b: string, max = Infinity): number {\n if (a === b) return 0;\n if (Math.abs(a.length - b.length) > max) return max + 1;\n\n // Three rows: prev2 carries i-2 so an adjacent transposition costs 1.\n let prev2 = new Array<number>(b.length + 1).fill(0);\n let prev = Array.from({ length: b.length + 1 }, (_, i) => i);\n let curr = new Array<number>(b.length + 1);\n\n for (let i = 1; i <= a.length; i++) {\n curr[0] = i;\n let rowMin = curr[0];\n for (let j = 1; j <= b.length; j++) {\n const cost = a[i - 1] === b[j - 1] ? 0 : 1;\n let d = Math.min(\n prev[j] + 1, // deletion\n curr[j - 1] + 1, // insertion\n prev[j - 1] + cost, // substitution\n );\n if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1]) {\n d = Math.min(d, prev2[j - 2] + 1); // adjacent transposition\n }\n curr[j] = d;\n if (d < rowMin) rowMin = d;\n }\n // Every remaining row can only grow: bail out early.\n if (rowMin > max) return max + 1;\n [prev2, prev, curr] = [prev, curr, prev2];\n }\n\n return prev[b.length];\n}\n\n/** Strip a trailing ordinal token: `demo2` -> `demo`, `cypress-tests-3` -> `cypress-tests`. */\nfunction stripOrdinal(name: string): string {\n return name.replace(/[-_]?\\d+$/, \"\");\n}\n\n/**\n * True when two names look like sibling environments rather than a typo of\n * each other — that is, they differ ONLY in a trailing ordinal.\n *\n * This guard is mandatory, not cosmetic. The live cluster contains\n * `leads-platform-demo` beside `leads-platform-demo2` (edit distance 1) and\n * `cypress-tests-1/2/3`. Without it, provisioning `leads-platform-demo3` would\n * find `demo2` one edit away, be branded a typo, and hard-fail a healthy new\n * environment — reintroducing exactly the cold-start breakage the severity\n * model exists to prevent.\n *\n * The guard is deliberately biased toward WARN: a genuine typo that happens to\n * differ only in a trailing digit is downgraded to a warning rather than\n * risking a false fatal.\n */\nexport function isOrdinalSibling(a: string, b: string): boolean {\n if (a === b) return false;\n const baseA = stripOrdinal(a);\n const baseB = stripOrdinal(b);\n // Both must reduce to the same base, and at least one must have carried an\n // ordinal (otherwise stripping changed nothing and this is a real edit).\n return baseA === baseB && (baseA !== a || baseB !== b);\n}\n\n/**\n * Find the existing names most likely to be what `name` was meant to be.\n *\n * Returns EVERY candidate at the minimal distance, not one arbitrary winner.\n * `thread-dv` is one edit from both `thread-dev` and `thread-db`; picking\n * between them by iteration order could point an operator at production. When\n * the evidence is ambiguous, say so.\n *\n * Returns an empty array when nothing is close enough, or when the only close\n * matches are sibling environments (see {@link isOrdinalSibling}). Empty means\n * \"absent, but no evidence of a typo\" — the caller warns rather than fails.\n *\n * Results are sorted for deterministic messages.\n */\nexport function nearestNames(name: string, candidates: readonly string[]): string[] {\n let best: string[] = [];\n let bestDistance = TYPO_DISTANCE_THRESHOLD + 1;\n\n for (const candidate of candidates) {\n if (candidate === name) return []; // exact match: not missing at all\n if (isOrdinalSibling(name, candidate)) continue;\n\n const d = editDistance(name, candidate, TYPO_DISTANCE_THRESHOLD);\n if (d > TYPO_DISTANCE_THRESHOLD) continue;\n\n if (d < bestDistance) {\n bestDistance = d;\n best = [candidate];\n } else if (d === bestDistance) {\n best.push(candidate);\n }\n }\n\n return best.sort();\n}\n\n/** Render one or more suggestions as `\"a\"`, or `\"a\" or \"b\"`, or `\"a\", \"b\" or \"c\"`. */\nexport function formatSuggestions(names: readonly string[]): string {\n const quoted = names.map((n) => `\"${n}\"`);\n if (quoted.length <= 1) return quoted[0] ?? \"\";\n return `${quoted.slice(0, -1).join(\", \")} or ${quoted[quoted.length - 1]}`;\n}\n","/**\n * @htilabs/platform-common-models — MongoDB URI parsing\n *\n * Home of the connection-string parsing shared by the seed guard\n * (`scripts/lib/confirmTargetDb.ts`) and the runtime verifier\n * (`src/mongo/index.ts`). It lives in `src/` so both can import one\n * implementation; `scripts/` cannot be imported from `src/` at build time.\n */\n\n/** Suffix that marks a database as a non-production scratch/test database. */\nexport const TEST_DB_SUFFIX = \"-test\";\n\n/**\n * Parse the target database name out of a MongoDB connection URI.\n *\n * The database name is the path segment after the host(s), before any query\n * string (`?...`). Handles both `mongodb://` and `mongodb+srv://` URIs and any\n * userinfo / multi-host / option components. Returns `null` when the URI\n * carries no database name (e.g. `mongodb://localhost:27017` or a trailing\n * slash with nothing after it) — callers must treat a `null` name as\n * prod-shaped and never silently default to a production database.\n *\n * Implemented as manual string parsing rather than `new URL()` because Node's\n * URL parser rejects multi-host `mongodb+srv` authorities and mishandles the\n * comma-separated seed-list form that real connection strings use.\n */\nexport function parseDbName(uri: string): string | null {\n // Strip the scheme.\n const schemeMatch = /^mongodb(\\+srv)?:\\/\\//i.exec(uri);\n if (!schemeMatch) return null;\n let rest = uri.slice(schemeMatch[0].length);\n\n // Drop query string and fragment — the DB name precedes both.\n const qIdx = rest.search(/[?#]/);\n if (qIdx !== -1) rest = rest.slice(0, qIdx);\n\n // The path begins at the first '/' after the authority. Everything before\n // that first slash is userinfo + host(s); everything after is the DB name.\n const slashIdx = rest.indexOf(\"/\");\n if (slashIdx === -1) return null;\n\n const dbName = rest.slice(slashIdx + 1).trim();\n return dbName.length > 0 ? dbName : null;\n}\n\n/**\n * Classify a database name. A name is a \"test\" database (no confirmation\n * required) only when it is non-null and ends in {@link TEST_DB_SUFFIX}.\n * Everything else — including a `null` name — is prod-shaped.\n */\nexport function isTestDb(dbName: string | null): boolean {\n return dbName !== null && dbName.endsWith(TEST_DB_SUFFIX);\n}\n","/**\n * @htilabs/platform-common-models — read-only MongoDB catalogue\n *\n * The verifier reaches MongoDB ONLY through this interface. It exposes two\n * read operations and nothing else: there is no method here that can create,\n * write, or drop anything. The read-only guarantee is enforced by the type,\n * not by convention.\n *\n * Injecting the catalogue also keeps the package's test suite free of a real\n * MongoDB, matching how `runCvcBootCheck` injects `exit` and `logger`.\n */\n\nexport interface MongoCatalog {\n /** Names of databases that physically exist (i.e. hold data). */\n listDatabases(): Promise<string[]>;\n /** Names of collections that physically exist in `database`. */\n listCollections(database: string): Promise<string[]>;\n}\n\n/**\n * Minimal structural view of a `mongodb` MongoClient. Declared structurally so\n * this package takes no dependency on the `mongodb` driver — apps pass their\n * own client, whatever major version they are on.\n */\nexport interface MongoClientLike {\n db(name?: string): {\n admin(): {\n listDatabases(): Promise<{ databases: Array<{ name: string }> }>;\n };\n listCollections(\n filter?: Record<string, unknown>,\n options?: Record<string, unknown>,\n ): { toArray(): Promise<Array<{ name: string }>> };\n };\n}\n\n/** Minimal structural view of a Mongoose Connection. */\nexport interface MongooseConnectionLike {\n getClient(): MongoClientLike;\n}\n\n/** Build a catalogue from a native `mongodb` client. */\nexport function catalogFromClient(client: MongoClientLike): MongoCatalog {\n return {\n async listDatabases(): Promise<string[]> {\n const { databases } = await client.db().admin().listDatabases();\n return databases.map((d) => d.name);\n },\n async listCollections(database: string): Promise<string[]> {\n // `nameOnly` keeps the server from materializing collection options.\n const infos = await client\n .db(database)\n .listCollections({}, { nameOnly: true })\n .toArray();\n return infos.map((c) => c.name);\n },\n };\n}\n\n/** Build a catalogue from an open Mongoose connection. */\nexport function catalogFromMongoose(\n connection: MongooseConnectionLike,\n): MongoCatalog {\n return catalogFromClient(connection.getClient());\n}\n","/**\n * @htilabs/platform-common-models — MongoDB connection/collection verifier\n *\n * Sibling to `./config`. Where `validateAgainstContract` proves the env vars\n * are present and well-typed, `verifyMongo` proves they point somewhere real.\n *\n * ## What this catches\n * - a database name that does not exist and looks like a typo of one that does\n * - a collection name that does not exist and looks like a typo of one that does\n * - a database name that does not belong to the current environment\n * (env-affinity; needs no connection — generalizes thread's `assertTestDb`)\n * - collections present in MongoDB but undeclared by the service (reported)\n *\n * ## What this CANNOT catch\n * A plausible-but-wrong POPULATED database. `leads-platform-prod-test` exists\n * and carries the same collection names as `leads-platform-test`; every\n * name-existence check passes. Detecting that needs an identity marker\n * written inside the database, which is outside this utility's read-only\n * remit. Do not claim otherwise in adoption docs.\n *\n * ## Read-only\n * Reaches MongoDB solely through {@link MongoCatalog}: listDatabases and\n * listCollections. It never creates, writes, or drops anything.\n *\n * ## Severity\n * MongoDB creates namespaces lazily, so ABSENCE IS AMBIGUOUS (typo vs\n * unseeded environment). Absence alone warns; absence with a plausible\n * near-neighbour is fatal. See `similarity.ts`.\n *\n * FACT (verified 2026-07-10, read-only): thread registers the Mongoose model\n * `AgencyInfo` (collection `agencyinfos`), and that collection exists in\n * neither `platform-test` (15 collections) nor `platform-dev` (41). A\n * registered model with zero documents has no collection. The warn-on-absence\n * rule exists because of this; do not \"tighten\" it to fatal.\n */\n\nimport {\n loadContract,\n resolveDefault,\n type ServiceContract,\n} from \"../config/index.js\";\nimport {\n parseMongoBlock,\n checkEnvAffinity,\n type MongoContractBlock,\n type MongoDbSpec,\n} from \"./contract.js\";\nimport { nearestNames, formatSuggestions } from \"./similarity.js\";\nimport { parseDbName } from \"./uri.js\";\nimport type { MongoCatalog } from \"./catalog.js\";\n\nexport type { MongoCatalog, MongoClientLike, MongooseConnectionLike } from \"./catalog.js\";\nexport { catalogFromClient, catalogFromMongoose } from \"./catalog.js\";\nexport type { MongoContractBlock, MongoDbSpec, EnvAffinity } from \"./contract.js\";\nexport { parseDbName, isTestDb, TEST_DB_SUFFIX } from \"./uri.js\";\n\nconst TAG = \"[platform-common/mongo]\";\n\nexport type Severity = \"fatal\" | \"warn\";\n\nexport type FindingKind =\n | \"env_var_missing\"\n | \"db_shape_violation\"\n | \"db_absent_typo\"\n | \"db_absent_unseeded\"\n | \"collection_absent_typo\"\n | \"collection_absent_unseeded\"\n | \"collection_undeclared\";\n\nexport interface Finding {\n severity: Severity;\n kind: FindingKind;\n message: string;\n dbVar?: string;\n database?: string;\n collection?: string;\n /**\n * Existing names this looks like a typo of. More than one means the evidence\n * is ambiguous — the message lists them all rather than guessing.\n */\n suggestions?: string[];\n}\n\nexport interface MongoVerifyReport {\n /** True when no fatal finding was produced. Warnings do not clear `ok`. */\n ok: boolean;\n findings: Finding[];\n}\n\nexport interface VerifyMongoOptions {\n /** Read-only catalogue. Required — this package takes no driver dependency. */\n catalog: MongoCatalog;\n /** Environment name for affinity checks. Defaults to NODE_ENV, then \"local\". */\n env?: string;\n /** Env source. Defaults to `process.env`. */\n processEnv?: NodeJS.ProcessEnv;\n /** If true, throw instead of `exit(1)`. Defaults to false (production exits). */\n throwOnFailure?: boolean;\n /** Injected for tests. Defaults to `process.exit`. */\n exit?: (code: number) => never;\n /** Injected for tests. Defaults to `console`. */\n logger?: Pick<Console, \"error\" | \"warn\">;\n}\n\n/**\n * Resolve the database name for a spec, applying the same per-environment\n * defaults that `validateAgainstContract` applies. Reading `process.env` alone\n * would miss a value the contract supplies as a default (thread declares\n * `PLATFORM_DB.default.prod: platform-prod`) and report a false fatal.\n *\n * When `db_var` and `uri_var` name the same variable, the database is embedded\n * in the connection string (auth does this for `LEADS_MONGODB_URI` and\n * friends) and must be parsed out of it.\n *\n * A variable the contract marks `required: false` and that carries no value is\n * SKIPPED, not failed: thread's `PAVE_DB` is optional and its absence simply\n * means the read-only pave connection is not configured. Required-ness comes\n * from the contract so there is no second place to declare it.\n */\nfunction resolveDbName(\n spec: MongoDbSpec,\n contract: ServiceContract,\n env: string,\n processEnv: NodeJS.ProcessEnv,\n): { name?: string; error?: string; skip?: boolean } {\n const varSpec = contract.variables[spec.db_var];\n const raw =\n processEnv[spec.db_var] ??\n (varSpec ? resolveDefault(varSpec, env) : undefined);\n\n if (raw === undefined || raw === \"\") {\n // A variable absent from `variables` is treated as required: the mongo\n // block references something the contract never declared.\n if (varSpec && varSpec.required === false) return { skip: true };\n return { error: `${spec.db_var}: required by mongo contract but not set` };\n }\n\n if (spec.db_var !== spec.uri_var) return { name: raw };\n\n const parsed = parseDbName(raw);\n if (parsed === null) {\n return {\n error:\n `${spec.db_var}: connection string carries no database name. ` +\n `Either embed one (mongodb://host/<db>) or declare a separate db_var.`,\n };\n }\n return { name: parsed };\n}\n\nasync function verifyDatabase(\n spec: MongoDbSpec,\n dbName: string,\n block: MongoContractBlock,\n env: string,\n catalog: MongoCatalog,\n existingDatabases: readonly string[],\n): Promise<Finding[]> {\n const findings: Finding[] = [];\n\n // 1. Env affinity — no connection required, and the only check that catches\n // a test run pointed at production.\n const violation = checkEnvAffinity(dbName, spec.db_var, env, block.env_affinity);\n if (violation) {\n findings.push({\n severity: \"fatal\",\n kind: \"db_shape_violation\",\n message: violation,\n dbVar: spec.db_var,\n database: dbName,\n });\n // A database in the wrong environment must not be probed further.\n return findings;\n }\n\n // 2. Existence.\n if (!existingDatabases.includes(dbName)) {\n const suggestions = nearestNames(dbName, existingDatabases);\n if (suggestions.length > 0) {\n findings.push({\n severity: \"fatal\",\n kind: \"db_absent_typo\",\n message:\n `${spec.db_var}=\"${dbName}\" does not exist. ` +\n `Did you mean ${formatSuggestions(suggestions)}?`,\n dbVar: spec.db_var,\n database: dbName,\n suggestions,\n });\n } else {\n findings.push({\n severity: \"warn\",\n kind: \"db_absent_unseeded\",\n message:\n `${spec.db_var}=\"${dbName}\" does not exist yet. Treating as an ` +\n `unseeded environment; MongoDB will create it on first write.`,\n dbVar: spec.db_var,\n database: dbName,\n });\n }\n // Nothing to compare collections against.\n return findings;\n }\n\n // 3. An empty `collections` list opts out of collection checking: verify the\n // database NAME only. This lets a service adopt incrementally — expansion\n // reaches the leads databases but enumerating their collections is not\n // tractable, and sweeping a 467MB database would emit a warning per\n // collection. Declaring even one collection opts back in.\n if (spec.collections.length === 0) return findings;\n\n // 4. Collections, both directions.\n const actual = await catalog.listCollections(dbName);\n\n for (const declared of spec.collections) {\n if (actual.includes(declared)) continue;\n\n const suggestions = nearestNames(declared, actual);\n if (suggestions.length > 0) {\n findings.push({\n severity: \"fatal\",\n kind: \"collection_absent_typo\",\n message:\n `${dbName}: declared collection \"${declared}\" does not exist. ` +\n `Did you mean ${formatSuggestions(suggestions)}?`,\n dbVar: spec.db_var,\n database: dbName,\n collection: declared,\n suggestions,\n });\n } else {\n findings.push({\n severity: \"warn\",\n kind: \"collection_absent_unseeded\",\n message:\n `${dbName}: declared collection \"${declared}\" does not exist yet ` +\n `(no documents written). MongoDB creates collections lazily.`,\n dbVar: spec.db_var,\n database: dbName,\n collection: declared,\n });\n }\n }\n\n const declaredSet = new Set(spec.collections);\n for (const present of actual) {\n if (declaredSet.has(present)) continue;\n findings.push({\n severity: \"warn\",\n kind: \"collection_undeclared\",\n message:\n `${dbName}: collection \"${present}\" exists but is not declared in the ` +\n `mongo contract.`,\n dbVar: spec.db_var,\n database: dbName,\n collection: present,\n });\n }\n\n return findings;\n}\n\n/**\n * Verify every database and collection declared in `runtimeYamlPath` against a\n * live MongoDB catalogue.\n *\n * Collects ALL findings before deciding, exactly as `validateAgainstContract`\n * does — an operator fixing a misconfiguration should see every problem at\n * once, not one per restart.\n *\n * Resolves to the report when no fatal finding is produced. On a fatal finding\n * it prints every finding and calls `exit(1)`, or throws when\n * `throwOnFailure` is set.\n *\n * A contract with no `mongo:` block is a no-op success.\n */\nexport async function verifyMongo(\n runtimeYamlPath: string,\n opts: VerifyMongoOptions,\n): Promise<MongoVerifyReport> {\n const processEnv = opts.processEnv ?? process.env;\n const logger = opts.logger ?? console;\n const exit = opts.exit ?? ((code: number) => process.exit(code));\n const env = opts.env ?? processEnv.NODE_ENV ?? \"local\";\n\n const contract = loadContract(runtimeYamlPath);\n const block = parseMongoBlock(contract.mongo, runtimeYamlPath);\n if (block === null) return { ok: true, findings: [] };\n\n const findings: Finding[] = [];\n const resolved: Array<{ spec: MongoDbSpec; name: string }> = [];\n\n for (const spec of block.databases) {\n const { name, error, skip } = resolveDbName(spec, contract, env, processEnv);\n if (skip) continue; // optional database, not configured in this environment\n if (error !== undefined || name === undefined) {\n findings.push({\n severity: \"fatal\",\n kind: \"env_var_missing\",\n message: error ?? `${spec.db_var}: unresolved`,\n dbVar: spec.db_var,\n });\n continue;\n }\n resolved.push({ spec, name });\n }\n\n // One catalogue read shared across every database in the contract.\n const existingDatabases =\n resolved.length > 0 ? await opts.catalog.listDatabases() : [];\n\n for (const { spec, name } of resolved) {\n findings.push(\n ...(await verifyDatabase(\n spec,\n name,\n block,\n env,\n opts.catalog,\n existingDatabases,\n )),\n );\n }\n\n const fatals = findings.filter((f) => f.severity === \"fatal\");\n const warns = findings.filter((f) => f.severity === \"warn\");\n\n for (const w of warns) logger.warn(`${TAG} ${w.message}`);\n\n if (fatals.length > 0) {\n const message = [\n `${TAG} verifyMongo failed for ${runtimeYamlPath} (env \"${env}\")`,\n `${fatals.length} fatal finding(s):`,\n ...fatals.map((f) => ` - ${f.message}`),\n ].join(\"\\n\");\n\n if (opts.throwOnFailure) throw new Error(message);\n logger.error(message);\n exit(1);\n }\n\n return { ok: fatals.length === 0, findings };\n}\n"],"mappings":"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","names":["TAG"]}
|