@sous-io/sous 0.1.0 → 0.2.0

package/src/lib/vars/validate.ts

@@ -0,0 +1,312 @@
+/**
+ * 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/watch-loop.ts

@@ -0,0 +1,148 @@
+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/templating/init-liquid-engine.ts

@@ -3,7 +3,11 @@ import path from "node:path";
 import { Liquid, type FS } from "liquidjs";
 import filterRegistrars from "./filters/index.js";
 import tagRegistrars from "./tags/index.js";
-import { resolveIncludeCandidates, type AliasMap } from "../lib/include-resolver.js";
+import { resolveInclude, type AliasMap } from "../lib/include-resolver.js";
+import {
+  formatNamespaceProblem,
+  type NamespaceResolver,
+} from "../lib/repos/namespace-resolver.js";
 
 /** Options for alias-aware `{% render %}` path resolution. */
 export type EngineAliasOptions = {
@@ -11,33 +15,70 @@ export type EngineAliasOptions = {
   aliases?: AliasMap;
   /** Variable scope for `${var}` substitution in render paths. */
   scope?: Record<string, string>;
+  /** Resolver consulted for a `~namespace` first segment in a render path. */
+  namespaceResolver?: NamespaceResolver;
+  /**
+   * Absolute path of the template being rendered, handed to the namespace
+   * resolver for scoping. Nested partials fall back to the directory LiquidJS
+   * resolves them against, which is enough to locate the owning recipe.
+   */
+  fromFile?: string;
 };
 
 /**
- * A node-backed LiquidJS FS that additionally understands `@`-prefixed render
- * paths — `{% render "@~sous-shared/x.md" %}`, `{% render "@docs/y.md" %}`, or
- * `{% render "@${var}/z.md" %}` — resolving them through the same alias/var/
- * relative candidate logic as `@include`. Non-`@` paths use standard root-based
- * resolution.
+ * A node-backed LiquidJS FS that additionally understands alias and namespace
+ * render paths — `{% render "@~project/x.md" %}`, `{% render "@docs/y.md" %}`,
+ * `{% render "@${var}/z.md" %}` and `{% render "~workflow/task-files/x.md" %}` —
+ * resolving them through the same alias/namespace/var/relative candidate logic
+ * as `@include`. The leading `@` is optional for a `~`-sigil path, since `~`
+ * already marks the path as symbolic rather than relative. Every other path
+ * uses standard root-based resolution.
  *
- * @param opts - Alias map and variable scope.
+ * @param opts - Alias map, variable scope, namespace resolver and including file.
  * @returns A LiquidJS FS implementation.
  */
 function createAliasFS(opts: EngineAliasOptions): FS {
   const aliases = opts.aliases ?? {};
   const scope = opts.scope ?? {};
 
-  /** Resolve an `@`-path to its first existing candidate, or the first candidate. */
-  const resolveAt = (file: string, dir: string): string | null => {
-    if (!file.startsWith("@")) return null;
-    const candidates = resolveIncludeCandidates(file.slice(1), { aliases, scope, baseDir: dir });
-    return candidates.find((c) => fs.existsSync(c)) ?? candidates[0] ?? null;
+  /**
+   * Resolve an `@`-path or `~`-path to its first existing candidate, or the
+   * first candidate. Returns null for ordinary paths so the caller falls back
+   * to root-based resolution. Throws when a `~namespace` reference resolved to
+   * nothing and the resolver explained why, so the reason reaches the user
+   * instead of a bare "file not found".
+   */
+  const resolveSymbolic = (file: string, dir: string): string | null => {
+    const isAt = file.startsWith("@");
+    if (!isAt && !file.startsWith("~")) return null;
+
+    const rawPath = isAt ? file.slice(1) : file;
+    const { candidates, namespaceIssue } = resolveInclude(rawPath, {
+      aliases,
+      scope,
+      baseDir: dir,
+      namespaceResolver: opts.namespaceResolver,
+      fromFile: opts.fromFile ?? dir,
+    });
+
+    const existing = candidates.find((c) => fs.existsSync(c));
+    if (existing) return existing;
+
+    if (namespaceIssue) {
+      throw new Error(
+        `Cannot render "${file}"\n${formatNamespaceProblem(namespaceIssue)}\n  tried:\n${candidates
+          .map((c) => `    - ${c}`)
+          .join("\n")}`
+      );
+    }
+
+    return candidates[0] ?? null;
   };
 
   return {
     resolve(dir: string, file: string, ext: string): string {
-      const at = resolveAt(file, dir);
-      if (at) return at;
+      const symbolic = resolveSymbolic(file, dir);
+      if (symbolic) return symbolic;
       // Standard resolution: join against the root dir, applying ext if missing.
       const joined = path.resolve(dir, file);
       if (ext && !path.extname(joined)) return joined + ext;
@@ -58,8 +99,9 @@ function createAliasFS(opts: EngineAliasOptions): FS {
  *
  * @param roots - Filesystem root paths searched (in order) when resolving
  *   `{% render %}` partials (relative paths resolve against these).
- * @param aliasOpts - Optional alias map + scope enabling `@alias/...` and
- *   `@${var}/...` paths in `{% render %}` (parity with `@include`).
+ * @param aliasOpts - Optional alias map, variable scope and namespace resolver,
+ *   enabling `@alias/...`, `@${var}/...` and `~namespace/...` paths in
+ *   `{% render %}` (parity with `@include`).
  */
 export function createLiquidEngine(roots: string[], aliasOpts: EngineAliasOptions = {}): Liquid {
   const engine = new Liquid({