@sous-io/sous 0.2.36 → 1.0.1

package/src/lib/vars/validate.ts

@@ -1,312 +0,0 @@
-/**
- * Validating an answer against the definition that asked for it.
- *
- * A recipe declares a small, deliberately boring constraint vocabulary (a type,
- * plus `pattern`, `minLength`, `maxLength`, `min`, `max` and `enum`), all of it
- * expressible in plain JSON so a manifest never has to carry code. This module
- * turns that vocabulary into a zod schema and reports a failure in the same
- * plain language the question was asked in, naming the constraint that was
- * violated rather than dumping a schema error.
- *
- * Answers are stored as text in env files, so validation always starts from a
- * string and hands back the coerced value.
- *
- * A `pattern` comes from a recipe, which is code from somewhere else, so it is
- * never run on this thread without a limit; see `safe-regex.ts`. A pattern that
- * exceeds its budget fails validation, and the failure says so plainly rather
- * than telling the person that their answer is wrong.
- */
-
-import { z } from "zod";
-import type { VariableDefinition } from "../repos/formats/recipe-manifest.js";
-import { DEFAULT_PATTERN_BUDGET_MS, matchWithBudget } from "./safe-regex.js";
-
-/** The value an answer coerces to, once it has been validated. */
-export type AnswerValue = string | number | boolean;
-
-/** What the caller knows about where a definition came from, for messages. */
-export interface ValidationContext {
-  /**
-   * The recipe that published the definition, named the way it should read in a
-   * message (for example 'acme/web-app'). Omitted when the caller does not know
-   * it, in which case messages describe it in words instead.
-   */
-  recipe?: string;
-  /** How long a declared pattern may run, in milliseconds. */
-  patternBudgetMs?: number;
-}
-
-/** A validated answer, or the reason it was refused. */
-export type AnswerValidation =
-  | { ok: true; value: AnswerValue }
-  | { ok: false; message: string };
-
-/** The strings accepted as a true answer for a boolean variable. */
-const TRUE_WORDS = new Set(["true", "yes", "y", "on", "1"]);
-
-/** The strings accepted as a false answer for a boolean variable. */
-const FALSE_WORDS = new Set(["false", "no", "n", "off", "0"]);
-
-/**
- * Builds the zod schema for one definition. The schema's input is the trimmed
- * answer text and its output is the coerced value, so callers get the number or
- * boolean a `number` or `boolean` variable promised.
- *
- * @param definition - The variable definition to build a schema for.
- * @param context - What is known about the recipe, for the pattern message.
- */
-export function validationSchemaFor(
-  definition: VariableDefinition,
-  context: ValidationContext = {}
-): z.ZodType<AnswerValue> {
-  const rules = definition.validate;
-
-  switch (definition.type) {
-    case "number": {
-      const schema = z
-        .string()
-        .refine((value) => value.length > 0 && Number.isFinite(Number(value)), {
-          message: "must be a number",
-        })
-        .transform((value) => Number(value))
-        .pipe(numberRules());
-      return schema as unknown as z.ZodType<AnswerValue>;
-    }
-
-    case "boolean": {
-      const schema = z
-        .string()
-        .refine((value) => TRUE_WORDS.has(value.toLowerCase()) || FALSE_WORDS.has(value.toLowerCase()), {
-          message: "must be 'true' or 'false'",
-        })
-        .transform((value) => TRUE_WORDS.has(value.toLowerCase()));
-      return schema as unknown as z.ZodType<AnswerValue>;
-    }
-
-    case "enum": {
-      const options = rules?.enum ?? [];
-      const schema = z.string().refine((value) => options.includes(value), {
-        message: `must be one of: ${options.join(", ")}`,
-      });
-      return stringRules(schema) as unknown as z.ZodType<AnswerValue>;
-    }
-
-    case "url": {
-      const schema = z.string().refine(
-        (value) => {
-          try {
-            const parsed = new URL(value);
-            return parsed.protocol.length > 1;
-          } catch {
-            return false;
-          }
-        },
-        { message: "must be a URL, including its scheme (for example 'https://example.com')" }
-      );
-      return stringRules(schema) as unknown as z.ZodType<AnswerValue>;
-    }
-
-    case "path": {
-      const schema = z.string().refine((value) => !value.includes("\0"), {
-        message: "must be a filesystem path, with no null characters in it",
-      });
-      return stringRules(schema) as unknown as z.ZodType<AnswerValue>;
-    }
-
-    case "string":
-    default:
-      return stringRules(z.string()) as unknown as z.ZodType<AnswerValue>;
-  }
-
-  /** Applies the numeric constraints to a number schema. */
-  function numberRules(): z.ZodType<number, number> {
-    let schema = z.number();
-    if (rules?.min !== undefined) schema = schema.min(rules.min, `must be at least ${rules.min}`);
-    if (rules?.max !== undefined) schema = schema.max(rules.max, `must be at most ${rules.max}`);
-    return schema;
-  }
-
-  /** Applies the string constraints, including the required-means-non-empty rule. */
-  function stringRules(base: z.ZodType<string>): z.ZodType<string> {
-    let schema: z.ZodType<string> = base;
-
-    if (definition.required) {
-      schema = schema.refine((value) => value.length > 0, { message: "must not be empty" });
-    }
-    if (rules?.minLength !== undefined) {
-      schema = schema.refine((value) => value.length >= rules.minLength!, {
-        message: `must be at least ${rules.minLength} characters long`,
-      });
-    }
-    if (rules?.maxLength !== undefined) {
-      schema = schema.refine((value) => value.length <= rules.maxLength!, {
-        message: `must be at most ${rules.maxLength} characters long`,
-      });
-    }
-    if (rules?.pattern !== undefined) {
-      const pattern = rules.pattern;
-      const budget = context.patternBudgetMs ?? DEFAULT_PATTERN_BUDGET_MS;
-      schema = schema.superRefine((value, ctx) => {
-        const outcome = matchWithBudget(pattern, value, budget);
-        if (outcome === "match") return;
-        ctx.addIssue({
-          code: "custom",
-          message:
-            outcome === "timeout"
-              ? patternTooSlowMessage(pattern, budget, context.recipe)
-              : `must match the pattern ${pattern}`,
-        });
-      });
-    }
-
-    return schema;
-  }
-}
-
-/**
- * The failure for a pattern that ran out of time. It names the pattern and the
- * recipe that published it, and says plainly that the pattern is the problem;
- * the person answering has no way to write an answer that a runaway pattern
- * would finish on.
- *
- * @param pattern - The regular expression source the recipe declared.
- * @param budgetMs - The budget it exceeded, in milliseconds.
- * @param recipe - The recipe that published it, when the caller knows it.
- */
-function patternTooSlowMessage(
-  pattern: string,
-  budgetMs: number,
-  recipe?: string
-): string {
-  const publisher = recipe === undefined ? "the recipe that defines it" : `the recipe ${recipe}`;
-  return (
-    `could not be checked: the pattern ${pattern}, published by ${publisher}, ` +
-    `took longer than ${budgetMs} milliseconds to run, so sous stopped waiting ` +
-    "for it. The pattern is too slow to run, and the answer was not the problem; " +
-    "this needs to be reported to whoever publishes the recipe"
-  );
-}
-
-/**
- * Validates one answer against its definition.
- *
- * @param definition - The variable definition the answer is for.
- * @param raw - The answer as text, as typed or as read from an env file.
- * @param context - What is known about the recipe, for the pattern message.
- * @returns The coerced value, or a plain-language message naming what is wrong.
- */
-export function validateAnswer(
-  definition: VariableDefinition,
-  raw: string,
-  context: ValidationContext = {}
-): AnswerValidation {
-  const trimmed = typeof raw === "string" ? raw.trim() : "";
-
-  if (trimmed.length === 0 && !definition.required) {
-    return { ok: true, value: "" };
-  }
-
-  const result = validationSchemaFor(definition, context).safeParse(trimmed);
-  if (result.success) return { ok: true, value: result.data };
-
-  const first = result.error.issues[0];
-  const reason = first?.message ?? "is not valid";
-  return { ok: false, message: `${definition.name} ${reason}.` };
-}
-
-/**
- * The form an answer is STORED in. Env files hold text, so a coerced number or
- * boolean goes back to its canonical string.
- *
- * @param value - The coerced answer.
- */
-export function storedForm(value: AnswerValue): string {
-  return typeof value === "boolean" ? String(value) : String(value);
-}
-
-/**
- * A short, plain-language summary of a definition's constraints, shown beside
- * the question and by `sous vars <name>`. Returns an empty array when the
- * definition constrains nothing beyond its type.
- *
- * @param definition - The variable definition.
- */
-export function constraintHints(definition: VariableDefinition): string[] {
-  const hints: string[] = [];
-  const rules = definition.validate;
-
-  hints.push(`type: ${definition.type}`);
-  if (definition.type === "enum" && rules?.enum !== undefined) {
-    hints.push(`one of: ${rules.enum.join(", ")}`);
-  }
-  if (rules?.minLength !== undefined) hints.push(`at least ${rules.minLength} characters`);
-  if (rules?.maxLength !== undefined) hints.push(`at most ${rules.maxLength} characters`);
-  if (rules?.min !== undefined) hints.push(`no less than ${rules.min}`);
-  if (rules?.max !== undefined) hints.push(`no more than ${rules.max}`);
-  if (rules?.pattern !== undefined) hints.push(`matching ${rules.pattern}`);
-  if (!definition.required) hints.push("optional");
-
-  return hints;
-}
-
-/**
- * A character count with the noun in the right number.
- *
- * @param count - How many characters.
- */
-function characters(count: number): string {
-  return count === 1 ? "1 character" : `${count} characters`;
-}
-
-/**
- * One sentence per constraint, in plain words with the raw form the manifest
- * declared in parentheses, so a reader can both understand the rule and find it
- * in the recipe that published it. This is what the advanced view and
- * `sous vars show` list under `@constraints`.
- *
- * @param definition - The variable definition.
- * @returns One sentence per constraint, type first.
- *
- * @example
- * constraintBullets(definition);
- * // -> ["must be a value of the type url (type: url)", "must match the pattern /^https/ (pattern: ^https)"]
- */
-export function constraintBullets(definition: VariableDefinition): string[] {
-  const rules = definition.validate;
-  const options = rules?.enum;
-
-  // The type sentence never puts an article in front of the type name, because
-  // the article would have to change with the name ('a path', but 'an enum').
-  // An enum is described by the options it allows, which says more than the
-  // word 'enum' does and reads as one sentence rather than two.
-  const bullets: string[] =
-    definition.type === "enum" && options !== undefined
-      ? [`must be one of: ${options.join(", ")} (type: enum)`]
-      : [`must be a value of the type ${definition.type} (type: ${definition.type})`];
-
-  if (options !== undefined && definition.type !== "enum") {
-    bullets.push(`must be one of: ${options.join(", ")} (enum: ${options.join(", ")})`);
-  }
-  if (rules?.minLength !== undefined) {
-    bullets.push(
-      `must be at least ${characters(rules.minLength)} long (minLength: ${rules.minLength})`
-    );
-  }
-  if (rules?.maxLength !== undefined) {
-    bullets.push(
-      `must be at most ${characters(rules.maxLength)} long (maxLength: ${rules.maxLength})`
-    );
-  }
-  if (rules?.min !== undefined) {
-    bullets.push(`must be no less than ${rules.min} (min: ${rules.min})`);
-  }
-  if (rules?.max !== undefined) {
-    bullets.push(`must be no more than ${rules.max} (max: ${rules.max})`);
-  }
-  if (rules?.pattern !== undefined) {
-    bullets.push(`must match the pattern /${rules.pattern}/ (pattern: ${rules.pattern})`);
-  }
-  if (!definition.required) bullets.push("an answer is optional");
-
-  return bullets;
-}

package/src/lib/version-report.ts

@@ -1,90 +0,0 @@
-/**
- * What `sous --version` prints.
- *
- * oclif answers `--version` with its user agent string (package, version,
- * platform and Node build on one line). Sous answers it itself, in bin/run.js,
- * before oclif is loaded: the version alone, or with `--verbose` the same facts
- * as a key and value list, so a person asking "which sous is this?" gets one
- * short line and a person asking "where is it?" gets the rest.
- */
-
-import fs from "node:fs";
-import os from "node:os";
-import { log, showVariables } from "../utils/formatting.js";
-
-/** The one flag oclif treats as a version request, and so does sous. */
-export const VERSION_FLAG = "--version";
-
-/** The flag that adds where the install is, the platform and the Node build. */
-export const VERBOSE_FLAG = "--verbose";
-
-/** The facts a version report is made of. */
-export type VersionFacts = {
-  /** The npm package name. */
-  name: string;
-  /** The package version. */
-  version: string;
-  /** The absolute path of the install answering. */
-  root: string;
-  /** The platform and architecture, the way oclif spells them. */
-  platform: string;
-  /** The Node build, with its leading `v`. */
-  node: string;
-};
-
-/** Whether the command line is a version request: `--version` as its first word. */
-export function isVersionRequest(argv: readonly string[]): boolean {
-  return argv[0] === VERSION_FLAG;
-}
-
-/** Reads the facts about the install rooted at `packageRoot`. */
-export function readVersionFacts(packageRoot: string): VersionFacts {
-  const pkg = JSON.parse(fs.readFileSync(`${packageRoot}/package.json`, "utf8")) as {
-    name?: unknown;
-    version?: unknown;
-  };
-  return {
-    name: typeof pkg.name === "string" ? pkg.name : "unknown",
-    version: typeof pkg.version === "string" ? pkg.version : "unknown",
-    root: packageRoot,
-    platform: `${os.platform()}-${os.arch()}`,
-    node: process.version,
-  };
-}
-
-/**
- * Prints the report: the version on its own line, and with `verbose` the
- * facts under it as a key and value list.
- *
- * @param facts - What to report.
- * @param verbose - Whether to print the facts under the version.
- * @param write - Where each line goes; standard output by default.
- */
-export function printVersionReport(
-  facts: VersionFacts,
-  verbose: boolean,
-  write: (line: string) => void = log
-): void {
-  write(`v${facts.version}`);
-  if (!verbose) return;
-  showVariables(
-    {
-      Package: facts.name,
-      Install: facts.root,
-      Platform: facts.platform,
-      Node: facts.node,
-    },
-    { write }
-  );
-}
-
-/**
- * Answers a version request from the command line: `sous --version`, or
- * `sous --version --verbose`.
- *
- * @param argv - The command line after the program name.
- * @param packageRoot - The root of the install answering.
- */
-export function printVersion(argv: readonly string[], packageRoot: string): void {
-  printVersionReport(readVersionFacts(packageRoot), argv.includes(VERBOSE_FLAG));
-}

package/src/lib/watch-loop.ts

@@ -1,148 +0,0 @@
-import path from "node:path";
-import {
-  CLI_ROOT,
-  resolveRootScope,
-  resolveWatchConfig,
-  type ConfigContext,
-  type Settings,
-  type WatchConfig,
-} from "./settings.js";
-import type { WatchHandle, WatchService } from "./watch-service.js";
-import { readEffectiveLinks } from "./repos/links.js";
-import { log } from "../utils/formatting.js";
-
-/**
- * Builds a WatchConfig from current settings, injecting the primary config
- * file, the conf.d/ drop-in DIRECTORY, the templating directory and every linked
- * repository's working copy into fullRebuildPaths. Watching a directory (not
- * each file inside it) covers files appearing, changing, or disappearing at
- * runtime, since full-rebuild matching is exact-or-directory-prefix.
- *
- * A linked repository is watched because that is the whole point of a link: the
- * recipes are being edited right now, in that checkout, and a watch that ignored
- * them would make the link useless.
- *
- * Shared by `build --watch` and `compile --watch` so both react to config,
- * template and linked-recipe edits identically.
- */
-export function buildReloadWatchConfig(
-  settings: Settings,
-  configContext: ConfigContext
-): WatchConfig {
-  const rootScope = resolveRootScope(settings, configContext);
-  const config = resolveWatchConfig(settings, rootScope);
-  const links = readEffectiveLinks(configContext.sousDir);
-  const reloadPaths = [
-    configContext.configPath,
-    configContext.confDir,
-    path.join(CLI_ROOT, "src", "templating"),
-    ...Object.values(links).map((link) => link.path),
-  ].filter((p): p is string => typeof p === "string");
-  config.fullRebuildPaths = [...(config.fullRebuildPaths ?? []), ...reloadPaths];
-  return config;
-}
-
-/** Options for {@link startConfigReloadWatch}. */
-export type ConfigReloadWatchOptions = {
-  /** The watcher factory used to (re)start chokidar. */
-  watchService: WatchService;
-  /**
-   * Produces a fresh WatchConfig from the CURRENT settings each time a watcher
-   * is (re)started; typically `() => buildReloadWatchConfig(this.settings, this.configContext)`.
-   */
-  buildWatchConfig: () => WatchConfig;
-  /**
-   * Performs the actual work (build/compile) using the command's CURRENT
-   * settings. Called for partial rebuilds (with the changed file) and, after a
-   * successful reload, for full rebuilds (no argument). Owns its own
-   * heading/footer output.
-   */
-  rebuild: (changedFile?: string) => Promise<void>;
-  /**
-   * Re-runs discovery + settings load and commits the result onto the command,
-   * but only if it loads cleanly (last-good semantics). Throws on failure.
-   */
-  reloadConfig: () => Promise<void>;
-};
-
-/** The running watch loop; exposes the live handle and a manual full-rebuild trigger. */
-export type ConfigReloadWatchController = {
-  /** Mutable reference to the live watcher handle (swapped on every restart). */
-  handle: { current: WatchHandle | null };
-  /** Triggers a full rebuild immediately, bypassing the debounce (e.g. a keypress). */
-  triggerFullRebuild: (reason: string) => Promise<void>;
-};
-
-/**
- * Runs the shared watch loop used by `build --watch` and `compile --watch`.
- *
- * - Partial events (a watched source file changed) call `rebuild(filePath)`.
- * - Full events (config file, conf.d directory, or templating dir changed) stop
- *   the watcher, reload settings via `reloadConfig`, rebuild, and restart the
- *   watcher. A failed reload is reported without wedging the session: the
- *   last-good config stays in place and the watcher restarts so the next edit
- *   can recover.
- *
- * A single `isRebuilding` guard serialises overlapping triggers.
- */
-export function startConfigReloadWatch(
-  options: ConfigReloadWatchOptions
-): ConfigReloadWatchController {
-  const { watchService, buildWatchConfig, rebuild, reloadConfig } = options;
-
-  let isRebuilding = false;
-  const handle: { current: WatchHandle | null } = { current: null };
-
-  const startWatcher = () => {
-    const watchConfig = buildWatchConfig();
-    handle.current = watchService.watch(watchConfig, async (event) => {
-      if (event.type === "partial") {
-        if (isRebuilding) return;
-        isRebuilding = true;
-        log(`\nChange detected: ${event.filePath}`);
-        await rebuild(event.filePath);
-        isRebuilding = false;
-      } else {
-        // Full rebuild: stop current watcher, reload settings, restart
-        if (isRebuilding) return;
-        isRebuilding = true;
-        log(`\nConfig changed (${event.filePath}), reloading settings and restarting watcher...`);
-        await handle.current!.stop();
-
-        try {
-          // Re-run discovery: conf.d layer files can appear or disappear while
-          // watching, so the ordered layer list must be rebuilt (and the
-          // duplicate-baseName check re-run) before reloading settings. Only
-          // committed by reloadConfig once it loads cleanly.
-          await reloadConfig();
-          await rebuild();
-        } catch (error) {
-          // A broken config edit (bad JSON/JS, colliding conf.d baseNames,
-          // configure() throw, etc.) must not wedge the session: report it,
-          // keep the last-good config, and fall through to restart the watcher
-          // so the next edit can recover.
-          log(
-            `\nConfig reload failed; keeping the last-good config. Fix the config and save again to retry.\n  ${
-              error instanceof Error ? error.message : String(error)
-            }`
-          );
-        } finally {
-          isRebuilding = false;
-          startWatcher();
-        }
-      }
-    });
-  };
-
-  startWatcher();
-
-  const triggerFullRebuild = async (reason: string) => {
-    if (isRebuilding) return;
-    isRebuilding = true;
-    log(`\n${reason}`);
-    await rebuild();
-    isRebuilding = false;
-  };
-
-  return { handle, triggerFullRebuild };
-}

package/src/lib/watch-service.ts

@@ -1,116 +0,0 @@
-import chokidar from "chokidar";
-import { minimatch } from "minimatch";
-import path from "node:path";
-import type { WatchConfig } from "./settings.js";
-import { toGlobPattern } from "./glob-pattern.js";
-import { log } from "../utils/formatting.js";
-
-/** Milliseconds to wait after a change before triggering a rebuild. */
-const DEBOUNCE_MS = 300;
-
-/** A partial rebuild triggered by a change to a specific source file. */
-export type PartialRebuildEvent = {
-  type: "partial";
-  filePath: string;
-};
-
-/** A full rebuild triggered by a change to a high-impact path (config, templating, etc.). */
-export type FullRebuildEvent = {
-  type: "full";
-  reason: string;
-  filePath: string;
-};
-
-export type WatchEvent = PartialRebuildEvent | FullRebuildEvent;
-
-/** A handle returned by WatchService.watch() that allows the caller to stop the watcher. */
-export type WatchHandle = {
-  stop(): Promise<void>;
-};
-
-/**
- * Extracts the longest leading non-glob segment of a pattern as a watchable
- * directory path. Chokidar v5 does not accept glob patterns directly.
- *
- * Examples:
- *   "/foo/bar/**\/*"   → "/foo/bar"
- *   "/foo/bar/*.md"   → "/foo/bar"
- */
-function globBaseDir(pattern: string): string {
-  const starIndex = pattern.indexOf("*");
-  if (starIndex === -1) return path.dirname(pattern);
-  const prefix = pattern.slice(0, starIndex);
-  return prefix.endsWith("/") || prefix.endsWith(path.sep)
-    ? prefix.slice(0, -1)
-    : path.dirname(prefix);
-}
-
-/**
- * Watches exact files, glob-backed directories, and full-rebuild paths,
- * calling the provided callback (debounced) when a relevant change is detected.
- *
- * - Changes to `files` or `globs` entries fire a partial rebuild event.
- * - Changes to `fullRebuildPaths` entries fire a full rebuild event.
- *
- * Returns a WatchHandle with a `stop()` method to close the watcher.
- */
-export class WatchService {
-  watch(config: WatchConfig, onChange: (event: WatchEvent) => Promise<void>): WatchHandle {
-    const { files, globs, fullRebuildPaths = [] } = config;
-    const globBaseDirs = globs.map(globBaseDir);
-    const watchPaths = [...new Set([...files, ...globBaseDirs, ...fullRebuildPaths])];
-
-    const watcher = chokidar.watch(watchPaths, {
-      ignoreInitial: true,
-      persistent: true,
-      ignored: /sous\.state\.json$/,
-    });
-
-    let debounceTimer: NodeJS.Timeout | null = null;
-    let pendingEvent: WatchEvent | null = null;
-
-    const schedule = (event: WatchEvent) => {
-      pendingEvent = event;
-      if (debounceTimer) clearTimeout(debounceTimer);
-      debounceTimer = setTimeout(async () => {
-        debounceTimer = null;
-        const evt = pendingEvent!;
-        pendingEvent = null;
-        try {
-          await onChange(evt);
-        } catch (err) {
-          const message = err instanceof Error ? err.message : String(err);
-          log(`  Watch error: ${message}`);
-        }
-      }, DEBOUNCE_MS);
-    };
-
-    watcher.on("all", (event, filePath) => {
-      if (!["add", "change", "unlink"].includes(event)) return;
-
-      // Full-rebuild paths take priority
-      const isFullRebuildPath = fullRebuildPaths.some(p =>
-        filePath === p || filePath.startsWith(p + path.sep) || filePath.startsWith(p + "/")
-      );
-
-      if (isFullRebuildPath) {
-        schedule({ type: "full", reason: filePath, filePath });
-        return;
-      }
-
-      const isExactFile = files.includes(filePath);
-      const matchesGlob = globs.some(g => minimatch(filePath, toGlobPattern(g)));
-
-      if (isExactFile || matchesGlob) {
-        schedule({ type: "partial", filePath });
-      }
-    });
-
-    const totalPatterns = files.length + globs.length + fullRebuildPaths.length;
-    log(`\nWatching ${totalPatterns} pattern(s) for changes...\n`);
-
-    return {
-      stop: () => watcher.close(),
-    };
-  }
-}