@untangle-code/config 0.0.0-stage → 0.1.1

package/src/discovery.ts

@@ -0,0 +1,95 @@
+/**
+ * Config file discovery (spec.md §4.1, §4.3 mention `.untangle.json` /
+ * `.untangle.local.json` without specifying how they are found;
+ * architecture.md §6.3 assigns "Config Discovery" to this package).
+ *
+ * Upward search from a start path, checking one directory at a time, until
+ * either the file is found, the repository root is reached (a directory
+ * containing `.git`, checked AFTER that directory's own candidate file so the
+ * repo root itself is still searched), or the filesystem root is reached.
+ */
+import { existsSync, statSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+
+export const PROJECT_CONFIG_FILE_NAME = ".untangle.json";
+export const LOCAL_CONFIG_FILE_NAME = ".untangle.local.json";
+/** Folder-contained project configuration; legacy root files retain priority. */
+export const PROJECT_FOLDER_CONFIG_FILE_NAME = join(".untangle", "config.json");
+/**
+ * `untangle.toml`, the file `untangle init` writes (WP-125).
+ *
+ * WP-222: it used to be invisible here. `init` wrote `untangle.toml`,
+ * discovery looked only for `.untangle.json`, and so `untangle doctor`
+ * reported "no configuration found" about a configuration that had just been
+ * written — and advised running `untangle init`, which had just run. A user
+ * following that advice loops forever. One file name known in one place ends
+ * that: whatever `init` writes is exactly what discovery finds.
+ */
+export const PROJECT_TOML_CONFIG_FILE_NAME = "untangle.toml";
+
+function isRepoRoot(dir: string): boolean {
+  return existsSync(join(dir, ".git"));
+}
+
+/**
+ * Searches `startPath` and its ancestors for `fileName`, stopping after the
+ * first directory that is a repository root (has `.git`) or after the
+ * filesystem root. Returns the absolute path of the first match, or
+ * `undefined` if none is found.
+ */
+export function discoverConfigFile(startPath: string, fileName: string): string | undefined {
+  let dir = resolve(startPath);
+  // If startPath is a file (e.g. process.cwd() equivalent passed by mistake),
+  // callers are expected to pass a directory; we do not stat startPath itself.
+  for (;;) {
+    const candidate = join(dir, fileName);
+    if (existsSync(candidate)) {
+      try {
+        if (statSync(candidate).isFile()) {
+          return candidate;
+        }
+      } catch {
+        // Unreadable candidate (race, permissions): treat as not found here.
+      }
+    }
+    const atRepoRoot = isRepoRoot(dir);
+    const parent = dirname(dir);
+    const atFilesystemRoot = parent === dir;
+    if (atRepoRoot || atFilesystemRoot) {
+      return undefined;
+    }
+    dir = parent;
+  }
+}
+
+/** Result of discovering the project-level config files (spec.md §4.1, layers 3–4). */
+export interface DiscoveredConfigFiles {
+  /** `.untangle.json`, or `.untangle/config.json` when no legacy project file exists. */
+  projectConfigPath: string | undefined;
+  /**
+   * `untangle.toml`, layer 4b — the file `untangle init` writes. It sits
+   * directly BENEATH `.untangle.json`: where both exist, the JSON file wins,
+   * and `loadConfig` warns rather than picking a winner in silence.
+   */
+  tomlConfigPath: string | undefined;
+  /** `.untangle.local.json`, layer 3 — SHOULD be gitignored (spec.md §4.1). */
+  localConfigPath: string | undefined;
+  /** Logical project directory for the folder layout, distinct from the config directory. */
+  projectRoot?: string;
+}
+
+/** Discovers project configuration upward, without crossing a repository boundary. */
+export function discoverConfigFiles(startPath: string): DiscoveredConfigFiles {
+  const projectConfigPath = discoverConfigFile(startPath, PROJECT_CONFIG_FILE_NAME);
+  const tomlConfigPath = discoverConfigFile(startPath, PROJECT_TOML_CONFIG_FILE_NAME);
+  const folderConfigPath =
+    projectConfigPath === undefined && tomlConfigPath === undefined
+      ? discoverConfigFile(startPath, PROJECT_FOLDER_CONFIG_FILE_NAME)
+      : undefined;
+  return {
+    projectConfigPath: projectConfigPath ?? folderConfigPath,
+    tomlConfigPath,
+    localConfigPath: discoverConfigFile(startPath, LOCAL_CONFIG_FILE_NAME),
+    ...(folderConfigPath === undefined ? {} : { projectRoot: dirname(dirname(folderConfigPath)) }),
+  };
+}

package/src/env.ts

@@ -0,0 +1,141 @@
+/**
+ * Environment variable layer (spec.md §4.1 layer 2, prefix `UNTANGLE_`).
+ *
+ * spec.md does not enumerate the mapping, so this table is an explicit
+ * Untangle decision: it covers the fields most likely to be overridden
+ * outside a checked-in config file (endpoints, modes, secrets-by-reference,
+ * gate strictness, telemetry opt-in), not every leaf field of
+ * `UntangleConfigV1`. New mappings MAY be added additively; removing or
+ * renaming one is a breaking change to this package's public contract.
+ *
+ * `UNTANGLE_QDRANT_API_KEY_ENV` / `UNTANGLE_EMBEDDINGS_API_KEY_ENV` set the
+ * NAME of a further environment variable holding a secret; they never carry
+ * the secret value itself (architecture.md §23.2).
+ */
+import type { RawConfigLayer } from "./types.js";
+
+type Parser = (raw: string) => unknown;
+
+const parseString: Parser = (raw) => raw;
+const parseNumber: Parser = (raw) => {
+  const value = Number(raw);
+  if (!Number.isFinite(value)) {
+    throw new Error(`expected a finite number, got "${raw}"`);
+  }
+  return value;
+};
+const parseBoolean: Parser = (raw) => {
+  const normalized = raw.trim().toLowerCase();
+  if (normalized === "true" || normalized === "1") {
+    return true;
+  }
+  if (normalized === "false" || normalized === "0") {
+    return false;
+  }
+  throw new Error(`expected a boolean ("true"/"false"/"1"/"0"), got "${raw}"`);
+};
+const parseCsv: Parser = (raw) =>
+  raw
+    .split(",")
+    .map((entry) => entry.trim())
+    .filter((entry) => entry.length > 0);
+
+export interface EnvMappingEntry {
+  /** Environment variable name, e.g. `UNTANGLE_QDRANT_URL`. */
+  env: string;
+  /** Dotted path into `UntangleConfigV1`, e.g. `["qdrant", "url"]`. */
+  path: readonly string[];
+  parse: Parser;
+}
+
+/** The complete, documented `UNTANGLE_*` → config-path mapping table. */
+export const ENV_MAPPING: readonly EnvMappingEntry[] = [
+  { env: "UNTANGLE_WORKSPACE_ID", path: ["workspaceId"], parse: parseString },
+  { env: "UNTANGLE_PROJECT_ID", path: ["projectId"], parse: parseString },
+
+  { env: "UNTANGLE_STORAGE_BACKEND", path: ["storage", "backend"], parse: parseString },
+  { env: "UNTANGLE_LANCEDB_PATH", path: ["storage", "path"], parse: parseString },
+
+  { env: "UNTANGLE_QDRANT_MODE", path: ["qdrant", "mode"], parse: parseString },
+  { env: "UNTANGLE_QDRANT_URL", path: ["qdrant", "url"], parse: parseString },
+  { env: "UNTANGLE_QDRANT_API_KEY_ENV", path: ["qdrant", "apiKeyEnv"], parse: parseString },
+  {
+    env: "UNTANGLE_QDRANT_COLLECTION_PREFIX",
+    path: ["qdrant", "collectionPrefix"],
+    parse: parseString,
+  },
+  {
+    env: "UNTANGLE_QDRANT_REQUEST_TIMEOUT_MS",
+    path: ["qdrant", "requestTimeoutMs"],
+    parse: parseNumber,
+  },
+  { env: "UNTANGLE_QDRANT_MAX_RETRIES", path: ["qdrant", "maxRetries"], parse: parseNumber },
+
+  { env: "UNTANGLE_EMBEDDINGS_MODE", path: ["embeddings", "mode"], parse: parseString },
+  { env: "UNTANGLE_EMBEDDINGS_URL", path: ["embeddings", "url"], parse: parseString },
+  { env: "UNTANGLE_EMBEDDINGS_API_KEY_ENV", path: ["embeddings", "apiKeyEnv"], parse: parseString },
+  { env: "UNTANGLE_EMBEDDINGS_MODEL", path: ["embeddings", "model"], parse: parseString },
+  { env: "UNTANGLE_EMBEDDINGS_DIMENSIONS", path: ["embeddings", "dimensions"], parse: parseNumber },
+  {
+    env: "UNTANGLE_EMBEDDINGS_REQUEST_TIMEOUT_MS",
+    path: ["embeddings", "requestTimeoutMs"],
+    parse: parseNumber,
+  },
+
+  { env: "UNTANGLE_INDEX_WATCH", path: ["index", "watch"], parse: parseBoolean },
+  { env: "UNTANGLE_INDEX_MAX_FILE_SIZE_MB", path: ["index", "maxFileSizeMb"], parse: parseNumber },
+  { env: "UNTANGLE_INDEX_EXTRA_EXTENSIONS", path: ["index", "extraExtensions"], parse: parseCsv },
+
+  { env: "UNTANGLE_QUALITY_GATE_MODE", path: ["qualityGate", "mode"], parse: parseString },
+  {
+    env: "UNTANGLE_QUALITY_GATE_MINIMUM_PARSE_QUALITY",
+    path: ["qualityGate", "minimumParseQuality"],
+    parse: parseString,
+  },
+
+  { env: "UNTANGLE_TELEMETRY_ENABLED", path: ["telemetry", "enabled"], parse: parseBoolean },
+  { env: "UNTANGLE_TELEMETRY_LOG_LEVEL", path: ["telemetry", "logLevel"], parse: parseString },
+
+  { env: "UNTANGLE_PORTFOLIO_ENABLED", path: ["portfolio", "enabled"], parse: parseBoolean },
+] as const;
+
+function setAtPath(target: Record<string, unknown>, path: readonly string[], value: unknown): void {
+  let cursor: Record<string, unknown> = target;
+  for (let i = 0; i < path.length - 1; i += 1) {
+    const key = path[i] as string;
+    const next = cursor[key];
+    if (typeof next !== "object" || next === null || Array.isArray(next)) {
+      cursor[key] = {};
+    }
+    cursor = cursor[key] as Record<string, unknown>;
+  }
+  const lastKey = path[path.length - 1] as string;
+  cursor[lastKey] = value;
+}
+
+export interface EnvLayerResult {
+  layer: RawConfigLayer;
+  /** Env vars that were present but failed to parse (e.g. non-numeric `UNTANGLE_EMBEDDINGS_DIMENSIONS`). */
+  parseErrors: { env: string; message: string }[];
+}
+
+/** Builds a `RawConfigLayer` from `env` using {@link ENV_MAPPING}. Unset variables are skipped. */
+export function buildEnvConfigLayer(env: NodeJS.ProcessEnv = process.env): EnvLayerResult {
+  const layer: Record<string, unknown> = {};
+  const parseErrors: { env: string; message: string }[] = [];
+  for (const entry of ENV_MAPPING) {
+    const raw = env[entry.env];
+    if (raw === undefined) {
+      continue;
+    }
+    try {
+      setAtPath(layer, entry.path, entry.parse(raw));
+    } catch (error) {
+      parseErrors.push({
+        env: entry.env,
+        message: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+  return { layer: layer as RawConfigLayer, parseErrors };
+}

package/src/hash.ts

@@ -0,0 +1,71 @@
+/**
+ * Canonical effective config and embedding profile derivation
+ * (architecture.md §6.3: "kanonische Effective Config", "Embedding- und
+ * Indexprofil-Hashing"; spec.md §5.1 `workspace_id` fallback derivation;
+ * spec.md §5.7 `embedding_profile_id`).
+ */
+import type { EmbeddingProfile } from "@untangle-code/domain";
+import { buildEmbeddingProfileId, canonicalJson, sha256Hex } from "@untangle-code/domain";
+
+import { DEFAULT_EMBEDDING_NORMALIZATION, PREPARED_TEXT_VERSION } from "./defaults.js";
+import type { EffectiveUntangleConfigV1 } from "./types.js";
+
+/**
+ * SHA-256 of the canonical JSON of `config`. The additive storage section
+ * is excluded for Qdrant to preserve existing workspace identities; its
+ * connection remains represented by the unchanged qdrant section. Used as `buildWorkspaceId`'s
+ * `configHash` input (spec.md §5.1) when no explicit `workspaceId` is
+ * configured, and to detect effective-config drift between index runs
+ * (architecture.md §6.3, §13.4 "Generation-Commit").
+ */
+export function computeConfigHash(config: unknown): string {
+  if (typeof config === "object" && config !== null && !Array.isArray(config)) {
+    const record = config as Record<string, unknown>;
+    const storage = record["storage"];
+    if (
+      typeof storage === "object" &&
+      storage !== null &&
+      "backend" in storage &&
+      storage.backend === "qdrant"
+    ) {
+      const legacyConfig = { ...record };
+      delete legacyConfig["storage"];
+      return sha256Hex(canonicalJson(legacyConfig));
+    }
+  }
+  return sha256Hex(canonicalJson(config));
+}
+
+/**
+ * Assembles the `EmbeddingProfile` (domain, spec.md §5.7's eight mandatory
+ * fields) from an effective config's `embeddings` section and derives
+ * `embedding_profile_id` via `buildEmbeddingProfileId`.
+ *
+ * `normalization` and `preparedTextVersion` are not part of `EmbeddingConfig`
+ * (spec.md §4.5 does not list them); they default to this package's fixed
+ * constants (`defaults.ts`) unless overridden here — e.g. a future config
+ * revision that exposes them per-project.
+ */
+export function deriveEmbeddingProfile(
+  config: Pick<EffectiveUntangleConfigV1, "embeddings">,
+  overrides: { normalization?: string; preparedTextVersion?: string } = {},
+): EmbeddingProfile {
+  return {
+    provider: config.embeddings.provider,
+    model: config.embeddings.model,
+    dimensions: config.embeddings.dimensions,
+    queryPrefix: config.embeddings.queryPrefix,
+    documentPrefix: config.embeddings.documentPrefix,
+    includePath: config.embeddings.includePath,
+    normalization: overrides.normalization ?? DEFAULT_EMBEDDING_NORMALIZATION,
+    preparedTextVersion: overrides.preparedTextVersion ?? PREPARED_TEXT_VERSION,
+  };
+}
+
+/** Convenience: `buildEmbeddingProfileId(deriveEmbeddingProfile(config, overrides))`. */
+export function deriveEmbeddingProfileId(
+  config: Pick<EffectiveUntangleConfigV1, "embeddings">,
+  overrides?: { normalization?: string; preparedTextVersion?: string },
+): string {
+  return buildEmbeddingProfileId(deriveEmbeddingProfile(config, overrides));
+}

package/src/index.ts

@@ -0,0 +1,51 @@
+/**
+ * @untangle-code/config — Untangle configuration: types, discovery,
+ * layering, JSON Schema, secret redaction, canonical hashing and migration.
+ *
+ * This module is the ONLY public export of the package.
+ */
+
+// Configuration types (spec.md §4.2-4.8; portfolio.md §14.4)
+export * from "./types.js";
+
+// Product defaults (spec.md §4.5; product.md §11)
+export * from "./defaults.js";
+
+// JSON Schema (Draft 2020-12)
+export * from "./schema.js";
+
+// Config file discovery (spec.md §4.1)
+export * from "./discovery.js";
+
+// OS user config directory (spec.md §4.1 layer 5)
+export * from "./user-config.js";
+
+// Environment variable layer (spec.md §4.1 layer 2)
+export * from "./env.js";
+
+// Deep merge with array-replace semantics (spec.md §4.1)
+export * from "./merge.js";
+
+// Path resolution relative to the config file (spec.md §4.3)
+export * from "./paths.js";
+
+// Secret references and redaction (spec.md §4.4/§4.5, §24; architecture.md §23.2)
+export * from "./secrets.js";
+
+// Canonical effective config hash and embedding profile derivation (architecture.md §6.3)
+export * from "./hash.js";
+
+// Validation (spec.md §4.8)
+export * from "./validate.js";
+
+// Migration scaffold for future schemaVersion jumps (architecture.md §6.3)
+export * from "./migrations.js";
+
+// Top-level orchestration
+export * from "./load.js";
+
+// Parse an existing document without loading defaults or environment layers.
+export * from "./parse.js";
+
+// IndexConfig -> chunker token-budget wiring (spec.md §4.6)
+export * from "./chunker-budget.js";