@sous-io/sous 0.1.0 → 0.2.0

package/src/lib/config-discovery.ts

@@ -1,5 +1,10 @@
 import fs from "node:fs";
 import path from "node:path";
+import { ConfigError } from "./errors.js";
+import {
+  listRecipeConfigLayers,
+  type RecipeConfigLayer,
+} from "./repos/recipe-config-layers.js";
 
 /**
  * The directory name sous looks for when walking up from the working directory.
@@ -7,15 +12,33 @@ import path from "node:path";
 export const SOUS_DIR_NAME = ".sous";
 
 /**
- * Config file names searched inside a `.sous/` directory, in priority order.
- * The first one that exists wins.
+ * Primary config file names searched inside a `.sous/` directory. Exactly ONE of
+ * these may exist per `.sous/`; more than one is a hard error (no silent
+ * first-match-wins).
  */
 export const CONFIG_FILE_NAMES = [
   "sous.config.js",
   "sous.config.mjs",
   "sous.config.json",
+  "sous.config.jsonc",
+  "sous.config.yaml",
 ] as const;
 
+/**
+ * The drop-in config layer directory inside `.sous/`. Every
+ * `conf.d/*.{js,mjs,json,jsonc,yaml}` file (non-recursive) is loaded after the
+ * primary config and deep-merged in bytewise filename order.
+ */
+export const CONFD_DIR_NAME = "conf.d";
+
+/**
+ * File extensions recognised as config layers inside `conf.d/`. A `.jsonc`
+ * layer is JSON with comments: line comments, block comments and trailing
+ * commas are all allowed in it, which is why the layers sous manages for a
+ * project are written that way.
+ */
+export const LAYER_EXTENSIONS = [".js", ".mjs", ".json", ".jsonc", ".yaml"] as const;
+
 /**
  * The name of the optional shared-defaults env file inside `.sous/`. This file
  * is meant to be committed: it holds values a whole team shares, never secrets.
@@ -27,7 +50,7 @@ export const ENV_LOCAL_NAME = ".env.local";
 
 /** A located sous configuration. */
 export type DiscoveredConfig = {
-  /** Absolute path to the config file itself. */
+  /** Absolute path to the primary config file itself. */
   configPath: string;
   /**
    * Absolute path to the `.sous/` directory holding the config, when the config
@@ -35,6 +58,30 @@ export type DiscoveredConfig = {
    * file's parent directory, whatever it is called.
    */
   sousDir: string;
+  /** Absolute path to the `conf.d/` drop-in directory (may not exist). */
+  confDir: string;
+  /**
+   * Ordered absolute paths of every config layer: the primary config first,
+   * then any config layers subscribed recipes contribute, then the `conf.d/`
+   * layers in bytewise filename order. Recipes sit in the middle so a recipe can
+   * supply defaults and the project always wins over them.
+   */
+  layerPaths: string[];
+  /** The subset of `layerPaths` that came from subscribed recipes. */
+  recipeLayerPaths: string[];
+  /**
+   * The recipe layers themselves, already read and already filtered down to the
+   * keys a recipe is allowed to set. Sous reads these instead of handing their
+   * paths to the config kernel, so a recipe cannot set a key that would change
+   * what sous trusts or what sous runs. See `repos/recipe-config-layers.ts`.
+   */
+  recipeLayers: RecipeConfigLayer[];
+  /**
+   * Complete, plain-language sentences about anything a recipe contributed that
+   * sous declined to load. Printed by the command, since discovery runs before
+   * there is anywhere good to print.
+   */
+  recipeLayerWarnings: string[];
   /** How the config was located. */
   source: "flag" | "walk-up";
 };
@@ -58,16 +105,152 @@ export function candidateDirs(startDir: string): string[] {
 }
 
 /**
- * Returns the first config file that exists inside `sousDir`, or null.
+ * Returns the primary config file inside `sousDir`, or null when none exists.
+ *
+ * @throws ConfigError when MORE THAN ONE primary candidate exists — sous never
+ *   silently picks one of several `sous.config.*` files.
  */
 export function findConfigInSousDir(sousDir: string): string | null {
+  const found: string[] = [];
   for (const name of CONFIG_FILE_NAMES) {
     const candidate = path.join(sousDir, name);
     if (fs.existsSync(candidate) && fs.statSync(candidate).isFile()) {
-      return candidate;
+      found.push(candidate);
     }
   }
-  return null;
+
+  if (found.length > 1) {
+    throw new ConfigError(
+      `Multiple primary sous config files found in ${sousDir}:\n` +
+        found.map((f) => `    ${f}`).join("\n") +
+        `\n  A .sous/ directory may hold exactly one of: ${CONFIG_FILE_NAMES.join(", ")}.\n` +
+        `  Keep one primary config and move the rest into ${CONFD_DIR_NAME}/ (with unique names) or delete them.`
+    );
+  }
+
+  return found[0] ?? null;
+}
+
+/**
+ * Compares two strings bytewise (plain `<` on the string), locale-independent
+ * so layer order is identical on every machine. Note this is NOT numeric:
+ * `10-` sorts before `2-` (zero-pad layer prefixes if that matters).
+ */
+function bytewiseCompare(a: string, b: string): number {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+
+/**
+ * Lists the config layer files inside a `conf.d/` directory: every
+ * `*.{js,mjs,json,jsonc,yaml}` file directly inside it (non-recursive), sorted
+ * bytewise by filename. A missing directory yields an empty list.
+ */
+export function listConfDirLayers(confDir: string): string[] {
+  if (!fs.existsSync(confDir) || !fs.statSync(confDir).isDirectory()) return [];
+
+  return fs
+    .readdirSync(confDir)
+    .filter((name) => {
+      const ext = path.extname(name).toLowerCase();
+      if (!(LAYER_EXTENSIONS as readonly string[]).includes(ext)) return false;
+      const full = path.join(confDir, name);
+      return fs.statSync(full).isFile();
+    })
+    .sort(bytewiseCompare)
+    .map((name) => path.join(confDir, name));
+}
+
+/**
+ * Asserts that every loaded config file (primary + conf.d layers) has a unique
+ * baseName; the filename minus its FINAL extension. Two layers named
+ * `500-repos.json` and `500-repos.jsonc` would otherwise merge in an order that
+ * depends on their extensions, which is never what the author meant. It is also
+ * what stops a managed layer from existing under both its old `.json` name and
+ * its `.jsonc` one.
+ *
+ * @throws ConfigError naming both conflicting files.
+ */
+export function assertUniqueLayerBaseNames(layerPaths: string[]): void {
+  const seen = new Map<string, string>();
+  for (const layerPath of layerPaths) {
+    const base = path.basename(layerPath, path.extname(layerPath));
+    const existing = seen.get(base);
+    if (existing !== undefined) {
+      throw new ConfigError(
+        `Duplicate config layer baseName '${base}':\n` +
+          `    ${existing}\n` +
+          `    ${layerPath}\n` +
+          `  Every loaded config file (the primary config and all ${CONFD_DIR_NAME}/ layers) must have a\n` +
+          `  unique filename once its final extension is removed. Rename one of them.`
+      );
+    }
+    seen.set(base, layerPath);
+  }
+}
+
+/**
+ * Builds a full DiscoveredConfig from a located primary config: computes the
+ * conf.d directory, enumerates its layers and the layers subscribed recipes
+ * contribute, and runs the duplicate-baseName check.
+ *
+ * Recipe layers load after the primary config and before the `conf.d/` layers,
+ * so a recipe supplies defaults and the project always wins over them. They are
+ * left out of the duplicate-baseName check deliberately: that check exists so a
+ * person never has to guess which of two files they wrote merges last, and a
+ * recipe's file names are not theirs to rename.
+ *
+ * @param confDirOverride - Absolute path to use as the conf.d directory instead
+ *   of `<sousDir>/conf.d`. Set from the `--sous-confd` flag or `SOUS_CONFD` env
+ *   var; discovery then builds its layers from the overridden directory.
+ */
+function buildDiscoveredConfig(
+  configPath: string,
+  sousDir: string,
+  source: DiscoveredConfig["source"],
+  confDirOverride?: string
+): DiscoveredConfig {
+  const confDir = confDirOverride ?? path.join(sousDir, CONFD_DIR_NAME);
+  const projectLayers = [configPath, ...listConfDirLayers(confDir)];
+  assertUniqueLayerBaseNames(projectLayers);
+
+  const recipes = listRecipeConfigLayers(sousDir);
+  const layerPaths = [
+    configPath,
+    ...recipes.paths,
+    ...projectLayers.slice(1),
+  ];
+
+  return {
+    configPath,
+    sousDir,
+    confDir,
+    layerPaths,
+    recipeLayerPaths: recipes.paths,
+    recipeLayers: recipes.layers,
+    recipeLayerWarnings: recipes.warnings,
+    source,
+  };
+}
+
+/**
+ * Re-runs the conf.d enumeration, the recipe layer enumeration and the
+ * duplicate-baseName check for an existing discovery.
+ *
+ * Two callers need it. Watch mode calls it because layer files can appear or
+ * disappear while watching. `BaseCommand.init()` calls it once after the
+ * `.sous/` env files are loaded, because `SOUS_HOME` is file-settable and it
+ * decides where the store holding the recipe layers is.
+ *
+ * The existing `confDir` is preserved (not recomputed from `sousDir`), so a
+ * `SOUS_CONFD` / `--sous-confd` override survives across watch reloads.
+ */
+export function refreshDiscoveredConfig(discovered: DiscoveredConfig): DiscoveredConfig {
+  return buildDiscoveredConfig(
+    discovered.configPath,
+    discovered.sousDir,
+    discovered.source,
+    discovered.confDir
+  );
 }
 
 /**
@@ -76,15 +259,22 @@ export function findConfigInSousDir(sousDir: string): string | null {
  * without a config file does not stop the walk.
  *
  * @param startDir - Directory to start from (normally `process.cwd()`).
+ * @param confDirOverride - Absolute conf.d directory to use instead of
+ *   `<sousDir>/conf.d` (from `--sous-confd` / `SOUS_CONFD`).
  * @returns The discovered config, or null when nothing was found.
+ * @throws ConfigError when a `.sous/` holds several primary configs, or when
+ *   loaded layer baseNames collide.
  */
-export function discoverConfig(startDir: string = process.cwd()): DiscoveredConfig | null {
+export function discoverConfig(
+  startDir: string = process.cwd(),
+  confDirOverride?: string
+): DiscoveredConfig | null {
   for (const dir of candidateDirs(startDir)) {
     const sousDir = path.join(dir, SOUS_DIR_NAME);
     if (!fs.existsSync(sousDir) || !fs.statSync(sousDir).isDirectory()) continue;
 
     const configPath = findConfigInSousDir(sousDir);
-    if (configPath) return { configPath, sousDir, source: "walk-up" };
+    if (configPath) return buildDiscoveredConfig(configPath, sousDir, "walk-up", confDirOverride);
   }
 
   return null;
@@ -99,40 +289,47 @@ export function discoverConfig(startDir: string = process.cwd()): DiscoveredConf
  *
  * @param configFlag - The raw `--config` value (relative paths resolve against cwd).
  * @param cwd - Base directory for relative paths.
+ * @param confDirOverride - Absolute conf.d directory to use instead of
+ *   `<sousDir>/conf.d` (from `--sous-confd` / `SOUS_CONFD`).
+ * @param sourceLabel - How the caller supplied the value (`--config`,
+ *   `--sous-config`, `SOUS_CONFIG`, `--sous-dir`, `SOUS_DIR`). Used only in error
+ *   messages so a user who set `SOUS_DIR` is not told to fix `--config`.
  * @returns The resolved config.
  * @throws When the path does not exist or holds no recognised config file.
  */
 export function resolveConfigFlag(
   configFlag: string,
-  cwd: string = process.cwd()
+  cwd: string = process.cwd(),
+  confDirOverride?: string,
+  sourceLabel = "--config"
 ): DiscoveredConfig {
   const resolved = path.resolve(cwd, expandHome(configFlag));
 
   if (!fs.existsSync(resolved)) {
-    throw new Error(`--config path not found: ${resolved}`);
+    throw new Error(`${sourceLabel} path not found: ${resolved}`);
   }
 
   if (fs.statSync(resolved).isDirectory()) {
     const direct = findConfigInSousDir(resolved);
     if (direct) {
-      return { configPath: direct, sousDir: resolved, source: "flag" };
+      return buildDiscoveredConfig(direct, resolved, "flag", confDirOverride);
     }
 
     const nested = path.join(resolved, SOUS_DIR_NAME);
     if (fs.existsSync(nested) && fs.statSync(nested).isDirectory()) {
       const nestedConfig = findConfigInSousDir(nested);
       if (nestedConfig) {
-        return { configPath: nestedConfig, sousDir: nested, source: "flag" };
+        return buildDiscoveredConfig(nestedConfig, nested, "flag", confDirOverride);
       }
     }
 
     throw new Error(
-      `--config points at a directory with no sous config file: ${resolved}\n` +
+      `${sourceLabel} points at a directory with no sous config file: ${resolved}\n` +
         `Looked for: ${CONFIG_FILE_NAMES.join(", ")}`
     );
   }
 
-  return { configPath: resolved, sousDir: path.dirname(resolved), source: "flag" };
+  return buildDiscoveredConfig(resolved, path.dirname(resolved), "flag", confDirOverride);
 }
 
 /**
@@ -175,24 +372,20 @@ export function formatNotFoundMessage(startDir: string = process.cwd()): string
     "",
     "  To fix this, either:",
     `    1. Create ${SOUS_DIR_NAME}/${CONFIG_FILE_NAMES[0]} in your project root, or`,
-    "    2. Pass the config explicitly: xcv <command> --config <path>",
+    "    2. Pass the config explicitly: sous <command> --config <path>",
     "",
     `  A minimal ${CONFIG_FILE_NAMES[0]}:`,
     "",
     "    export const config = {",
-    '      defaultProject: "myproject",',
-    "      projects: {",
-    "        myproject: {",
-    '          name: "My Project",',
-    "          compilation: {",
-    "            targets: [",
-    "              {",
-    '                entryPoint: "${sousDir}/AGENTS.md",',
-    '                outputs: [{ destinationFile: "${projectRoot}/AGENTS.md" }],',
-    "              },",
-    "            ],",
+    '      name: "My Project",',
+    '      _vars: { projectRoot: "${sousDir}/.." },',
+    "      compilation: {",
+    "        targets: [",
+    "          {",
+    '            entryPoint: "${sousDir}/AGENTS.md",',
+    '            outputs: [{ destinationFile: "${projectRoot}/AGENTS.md" }],',
     "          },",
-    "        },",
+    "        ],",
     "      },",
     "    };",
   ].join("\n");

package/src/lib/config-inspect.ts

@@ -0,0 +1,145 @@
+import { styleText } from "node:util";
+import { ConfigError } from "./errors.js";
+
+/**
+ * Shared helpers for the `sous config *` inspection commands: dot-path lookup
+ * with `[n]` array indexing, colorized pretty-JSON rendering, and value
+ * truncation for the `--layers` provenance view.
+ */
+
+/** Sentinel returned by lookupPath when a path segment does not exist. */
+export const NOT_FOUND = Symbol("sous.config.path.not-found");
+
+/**
+ * Splits a dot-path with optional `[n]` array indices into ordered segments.
+ * `compilation.targets[0].entryPoint` → `["compilation", "targets", 0, "entryPoint"]`.
+ * Numeric-looking bracket segments become numbers; everything else is a string key.
+ *
+ * @throws ConfigError on a malformed path (empty, unbalanced brackets, etc.).
+ */
+export function parsePath(path: string): (string | number)[] {
+  const trimmed = path.trim();
+  if (trimmed === "") {
+    throw new ConfigError("Empty config path. Provide a dot-path like 'compilation.targets[0].entryPoint'.");
+  }
+
+  const segments: (string | number)[] = [];
+  // Consume, in order: bare keys, `[n]` array indices, and `.` separators
+  // between them. Any character that fits none of these (e.g. `a..b`, `a[]`,
+  // `a[x]`) leaves a gap the scanner reports as malformed.
+  const tokenRe = /([^.[\]]+)|\[(\d+)\]|(\.)/g;
+  let lastIndex = 0;
+  let expectKey = false; // a `.` was just consumed, so a key must follow
+  let match: RegExpExecArray | null;
+
+  while ((match = tokenRe.exec(trimmed)) !== null) {
+    if (match.index !== lastIndex) {
+      throw new ConfigError(`Malformed config path near '${trimmed.slice(lastIndex)}' in '${path}'.`);
+    }
+    if (match[1] !== undefined) {
+      segments.push(match[1]);
+      expectKey = false;
+    } else if (match[2] !== undefined) {
+      if (expectKey) {
+        throw new ConfigError(`Malformed config path near '${trimmed.slice(match.index)}' in '${path}'.`);
+      }
+      segments.push(Number(match[2]));
+    } else {
+      // A `.` separator: a key must follow it, and one may not lead the path or
+      // directly follow another `.` (i.e. `.a`, `a..b` are malformed).
+      if (expectKey || segments.length === 0) {
+        throw new ConfigError(`Malformed config path near '${trimmed.slice(match.index)}' in '${path}'.`);
+      }
+      expectKey = true;
+    }
+    lastIndex = tokenRe.lastIndex;
+  }
+
+  if (lastIndex !== trimmed.length || expectKey) {
+    throw new ConfigError(`Malformed config path near '${trimmed.slice(lastIndex) || "end of path"}' in '${path}'.`);
+  }
+
+  return segments;
+}
+
+/**
+ * Walks `root` following `segments`, returning the value found or NOT_FOUND when
+ * any segment is missing (or the path descends into a non-indexable value).
+ */
+export function lookupPath(root: unknown, segments: (string | number)[]): unknown {
+  let current: unknown = root;
+  for (const segment of segments) {
+    if (current === null || current === undefined || typeof current !== "object") {
+      return NOT_FOUND;
+    }
+    if (typeof segment === "number") {
+      if (!Array.isArray(current) || segment < 0 || segment >= current.length) {
+        return NOT_FOUND;
+      }
+      current = current[segment];
+    } else {
+      // Use hasOwnProperty, NOT the `in` operator: `in` walks the prototype
+      // chain, so inherited Object.prototype members (`constructor`, `toString`,
+      // `hasOwnProperty`, `__proto__`, …) would falsely "resolve" and print
+      // garbage instead of NOT_FOUND.
+      if (!Object.prototype.hasOwnProperty.call(current, segment)) {
+        return NOT_FOUND;
+      }
+      current = (current as Record<string, unknown>)[segment];
+    }
+  }
+  return current;
+}
+
+/** True for JSON scalar values (string, finite/any number, boolean, null). */
+export function isScalar(value: unknown): value is string | number | boolean | null {
+  return (
+    value === null ||
+    typeof value === "string" ||
+    typeof value === "number" ||
+    typeof value === "boolean"
+  );
+}
+
+/**
+ * Colorizes an already-serialized pretty-JSON string using node:util styleText:
+ * object keys cyan, string values green, numbers yellow, booleans/null magenta.
+ * Operates purely on JSON token syntax, so it never mangles structure.
+ *
+ * Callers should only invoke this when writing to a TTY; piped output must stay
+ * plain so it parses as JSON.
+ */
+export function colorizeJson(json: string): string {
+  const tokenRe = /"(?:\\.|[^"\\])*"|-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?|\b(?:true|false|null)\b/g;
+  return json.replace(tokenRe, (match, offset: number, whole: string) => {
+    if (match[0] === '"') {
+      const rest = whole.slice(offset + match.length);
+      // A string immediately followed by a colon is an object key.
+      return /^\s*:/.test(rest)
+        ? styleText("cyan", match)
+        : styleText("green", match);
+    }
+    if (match === "true" || match === "false" || match === "null") {
+      return styleText("magenta", match);
+    }
+    return styleText("yellow", match);
+  });
+}
+
+/**
+ * Renders a value as pretty JSON (2-space), colorized when `useColor` is true.
+ */
+export function renderJson(value: unknown, useColor: boolean): string {
+  const json = JSON.stringify(value, null, 2);
+  return useColor ? colorizeJson(json) : json;
+}
+
+/**
+ * JSON-encodes a value on a single line and truncates it to `max` characters
+ * (with an ellipsis) for the compact `--layers` provenance lines.
+ */
+export function truncateJson(value: unknown, max = 80): string {
+  const encoded = JSON.stringify(value);
+  if (encoded === undefined) return "undefined";
+  return encoded.length > max ? `${encoded.slice(0, max - 1)}…` : encoded;
+}