@sous-io/sous 0.1.1 → 0.2.0

package/src/lib/env-local.ts

@@ -83,6 +83,23 @@ function findClosingQuote(value: string, quote: string): number {
   return -1;
 }
 
+/**
+ * Reads one env file and returns its variables as a flat map, WITHOUT touching
+ * `process.env`. Returns an empty map when the file does not exist.
+ *
+ * The variables layer needs each env file on its own: by the time a command
+ * runs, `loadEnvFiles` has already merged both files into the process
+ * environment, so reading them separately is the only way to say which layer
+ * supplied an answer.
+ *
+ * @param filePath - Absolute path to the env file.
+ * @returns The parsed variables, or an empty map when there is no such file.
+ */
+export function readEnvFileMap(filePath: string): Record<string, string> {
+  if (!fs.existsSync(filePath)) return {};
+  return parseEnvLocal(fs.readFileSync(filePath, "utf8"));
+}
+
 /** The outcome of an attempted env file load. */
 export type EnvLocalLoadResult = {
   /** Absolute path checked. */
@@ -155,7 +172,7 @@ export function loadEnvDefaults(
  * `process.env`, if it exists.
  *
  * Existing environment values always win: a variable already set in the real
- * environment is never overwritten, so `FOO=bar xcv build` behaves as expected.
+ * environment is never overwritten, so `FOO=bar sous build` behaves as expected.
  *
  * @param sousDir - The discovered `.sous/` directory.
  * @param env - The environment object to mutate (injectable for tests).

package/src/lib/errors.ts

@@ -0,0 +1,32 @@
+/**
+ * Shared error types for sous.
+ *
+ * ConfigError lives in its own module (rather than settings.ts) so that
+ * config-discovery.ts can throw it without importing settings.ts — settings.ts
+ * imports discovery constants, and a back-import would create a cycle.
+ * settings.ts re-exports both names for backwards compatibility.
+ */
+
+/**
+ * A user-facing configuration error: the config file (or environment) is wrong,
+ * not the CLI. Commands render these as a plain message with no stack trace,
+ * since the stack points at Sous internals and tells the user nothing.
+ */
+export class ConfigError extends Error {
+  readonly isConfigError = true;
+
+  constructor(message: string) {
+    super(message);
+    this.name = "ConfigError";
+  }
+}
+
+/** True when the value is a ConfigError (safe across module instances). */
+export function isConfigError(error: unknown): boolean {
+  return (
+    error instanceof ConfigError ||
+    (typeof error === "object" &&
+      error !== null &&
+      (error as { isConfigError?: boolean }).isConfigError === true)
+  );
+}

package/src/lib/include-resolver.ts

@@ -1,8 +1,9 @@
 import path from "node:path";
+import type { NamespaceResolution, NamespaceResolver } from "./repos/namespace-resolver.js";
 
 /**
- * @include path resolution: aliases, variable substitution, and the ordered
- * candidate search.
+ * @include path resolution: aliases, recipe namespaces, variable substitution,
+ * and the ordered candidate search.
  *
  * An include path (the part after `@`) is resolved to an ordered list of
  * candidate absolute paths. The caller tries each in order and uses the first
@@ -14,11 +15,19 @@ import path from "node:path";
  *   2. Split the first segment (up to the first `/` or `:`) as the alias key,
  *      the remainder as `rest`. If the key is a registered alias, push
  *      join(base, rest) for EACH base in the alias's ordered array.
- *   3. Always push the relative candidate: join(baseDir, P) — the FULL path
+ *   3. If the key begins with `~` and a namespace resolver was supplied, ask it
+ *      for the recipe namespace named by the key (minus the `~`) and push its
+ *      candidates. Aliases are consulted first, so `~project` keeps meaning
+ *      the built-in alias even if a namespace of that name exists.
+ *   4. Always push the relative candidate: join(baseDir, P) — the FULL path
  *      including the alias segment. This lets an alias augment a real relative
  *      directory of the same name (e.g. `@stuff/x` tries the alias bases, then
  *      `./stuff/x`).
  *
+ * A key WITHOUT the `~` sigil never reaches the namespace resolver: a bare
+ * `@path` is always a relative path or a declared alias, so include lines never
+ * masquerade as filesystem paths.
+ *
  * Aliases whose names begin with `~` are reserved for built-ins; user aliases
  * may not use that prefix. The primary separator is `/` (TS-style,
  * `@alias/path`); `:` is accepted as an equivalent (`@alias:path`).
@@ -52,29 +61,69 @@ export function splitAliasKey(p: string): { key: string; rest: string } {
   return { key: m[1], rest: m[2] };
 }
 
+/** Options shared by {@link resolveInclude} and {@link resolveIncludeCandidates}. */
+export type IncludeResolveOptions = {
+  /** The resolved alias map (name → ordered base dirs). */
+  aliases?: AliasMap;
+  /** Variable scope for ${var} substitution. */
+  scope?: Record<string, string>;
+  /** Directory of the including file (for the relative candidate). */
+  baseDir: string;
+  /** Resolver consulted for a `~namespace` first segment; omitted means namespaces are unavailable. */
+  namespaceResolver?: NamespaceResolver;
+  /**
+   * Absolute path of the including file, handed to the namespace resolver so it
+   * can tell whether the include comes from inside a recipe. Defaults to
+   * `baseDir` for callers that only know the directory.
+   */
+  fromFile?: string;
+};
+
+/** A namespace lookup that produced no usable candidates, kept for error reporting. */
+export type NamespaceIssue = {
+  /** The namespace that was asked for, without its `~` sigil. */
+  namespace: string;
+  /** The remainder of the reference (recipe name plus the path inside it). */
+  rest: string;
+  /** The file (or directory) that performed the include. */
+  fromFile: string;
+  /** What the resolver returned. */
+  resolution: NamespaceResolution;
+};
+
+/** The full result of resolving one include path. */
+export type IncludeResolution = {
+  /** Ordered, de-duplicated absolute candidate paths. */
+  candidates: string[];
+  /**
+   * Present when the first segment named a `~namespace` that the resolver could
+   * not satisfy. The candidate list is still usable (it holds the alias and
+   * relative fallbacks); this only explains what went wrong with the namespace.
+   */
+  namespaceIssue?: NamespaceIssue;
+};
+
 /**
- * Compute the ordered list of candidate absolute paths for an include.
+ * Resolve an include path to its ordered candidates plus any namespace
+ * diagnostic. Use this when the caller wants to report WHY a `~namespace`
+ * reference failed; {@link resolveIncludeCandidates} is the plain-list form.
  *
  * @param rawPath - The include path with the leading `@` already stripped.
- * @param opts.aliases - The resolved alias map (name → ordered base dirs).
- * @param opts.scope - Variable scope for ${var} substitution.
- * @param opts.baseDir - Directory of the including file (for the relative candidate).
- * @returns Ordered, de-duplicated absolute candidate paths.
+ * @param opts - Aliases, variable scope, including directory and optional namespace resolver.
+ * @returns The candidate list and, when a namespace lookup failed, the reason.
  */
-export function resolveIncludeCandidates(
-  rawPath: string,
-  opts: { aliases?: AliasMap; scope?: Record<string, string>; baseDir: string }
-): string[] {
+export function resolveInclude(rawPath: string, opts: IncludeResolveOptions): IncludeResolution {
   const aliases = opts.aliases ?? {};
   const scope = opts.scope ?? {};
   const substituted = substituteVars(rawPath, scope);
 
   // 1. Substituted to an absolute path → that is the only candidate.
   if (path.isAbsolute(substituted)) {
-    return [path.normalize(substituted)];
+    return { candidates: [path.normalize(substituted)] };
   }
 
   const candidates: string[] = [];
+  let namespaceIssue: NamespaceIssue | undefined;
 
   // 2. Alias bases (ordered), if the first segment is a registered alias.
   const { key, rest } = splitAliasKey(substituted);
@@ -84,11 +133,55 @@ export function resolveIncludeCandidates(
     }
   }
 
-  // 3. Relative fallback: the FULL substituted path under the including dir.
+  // 3. Recipe namespace, only for a `~`-sigil key naming something after it.
+  //    Aliases above already had their turn, so a built-in or user alias of the
+  //    same name is always preferred.
+  if (opts.namespaceResolver && key.startsWith("~") && key.length > 1 && rest.length > 0) {
+    const namespace = key.slice(1);
+    const fromFile = opts.fromFile ?? opts.baseDir;
+    const resolution = opts.namespaceResolver.resolve({ namespace, rest, fromFile });
+
+    if (resolution.kind === "candidates" && resolution.candidates.length > 0) {
+      candidates.push(...resolution.candidates.map((c) => path.normalize(c)));
+    } else {
+      namespaceIssue = { namespace, rest, fromFile, resolution };
+    }
+  }
+
+  // 4. Relative fallback: the FULL substituted path under the including dir.
   candidates.push(path.resolve(opts.baseDir, substituted));
 
   // De-dupe, preserving order.
-  return [...new Set(candidates)];
+  return { candidates: [...new Set(candidates)], namespaceIssue };
+}
+
+/**
+ * Compute the ordered list of candidate absolute paths for an include.
+ *
+ * @param rawPath - The include path with the leading `@` already stripped.
+ * @param opts - Aliases, variable scope, including directory and optional namespace resolver.
+ * @returns Ordered, de-duplicated absolute candidate paths.
+ */
+export function resolveIncludeCandidates(rawPath: string, opts: IncludeResolveOptions): string[] {
+  return resolveInclude(rawPath, opts).candidates;
+}
+
+/**
+ * Expand a leading alias segment in a path or glob pattern to one candidate
+ * per alias base, in the alias's base order. Used for config entry paths
+ * (`entryGlob`/watch patterns), where — unlike @include resolution — there is
+ * no including file to supply a relative fallback, so a non-alias path is
+ * returned unchanged as the sole candidate.
+ *
+ * @param p - The path or glob pattern (already ${var}-substituted).
+ * @param aliases - The resolved alias map (name → ordered base dirs).
+ * @returns Ordered candidate paths/patterns; `[p]` when no alias applies.
+ */
+export function resolveAliasPrefix(p: string, aliases: AliasMap): string[] {
+  if (path.isAbsolute(p)) return [p];
+  const { key, rest } = splitAliasKey(p);
+  if (!key || !Object.prototype.hasOwnProperty.call(aliases, key)) return [p];
+  return aliases[key].map((base) => path.resolve(base, rest));
 }
 
 /**

package/src/lib/interactive.ts

@@ -0,0 +1,165 @@
+/**
+ * The one rule for "may sous ask a question right now?".
+ *
+ * Every prompt in sous (the trust question, the subscribe confirmation, the
+ * choice between candidate refs, a variable question) is gated by this single
+ * predicate, so a run either can ask all of them or none of them. Three things
+ * can take the terminal away:
+ *
+ *   - the global `--non-interactive` flag, which says so outright;
+ *   - a truthy `CI` environment variable, which every continuous integration
+ *     runner sets and which means no human is watching;
+ *   - stdin or stdout not being a terminal, which is what piping or scripting
+ *     a command looks like from in here.
+ *
+ * When a prompt cannot be shown, the run fails rather than guessing, and the
+ * failure names both the question that could not be asked and the flag (or the
+ * environment variables) that would have answered it ahead of time. Every
+ * confirmation in sous is answered by one shared flag, `--yes` (also `-y`,
+ * `--force`, and `--trust` on the commands that trust a repository), so a
+ * remedy names that flag and lists its other spellings once. The command layer
+ * prints the command's own help underneath that error, so the caller can see
+ * every flag without going looking; `sous help <command>` prints the same
+ * screen on demand.
+ *
+ * Every input is injectable, so a test can describe a terminal, a pipe or a CI
+ * runner without touching the real process.
+ */
+
+import { ConfigError } from "./errors.js";
+
+/** Everything the rule reads. Each field defaults to the real process. */
+export type InteractiveInputs = {
+  /** The command line, scanned for `--non-interactive`. Defaults to `process.argv`. */
+  argv?: string[];
+  /** The environment, read for `CI`. Defaults to `process.env`. */
+  env?: NodeJS.ProcessEnv;
+  /** Whether stdin is a terminal. Defaults to the real stdin. */
+  stdinIsTTY?: boolean;
+  /** Whether stdout is a terminal. Defaults to the real stdout. */
+  stdoutIsTTY?: boolean;
+};
+
+/** The global flag that turns every prompt into an error. */
+export const NON_INTERACTIVE_FLAG = "--non-interactive";
+
+/**
+ * Values of `CI` that mean "not set". Everything else counts as set, because
+ * runners spell it `1`, `true` and `yes` in roughly equal measure and a run
+ * that guesses wrong hangs forever waiting on a question nobody can see.
+ */
+const FALSY_CI_VALUES = new Set(["", "0", "false", "no", "off"]);
+
+/**
+ * True when sous is attached to a terminal in both directions, was not told to
+ * stay quiet, and is not running inside a continuous integration runner.
+ *
+ * @param inputs - Overrides for the command line, environment and streams.
+ */
+export function isInteractive(inputs: InteractiveInputs = {}): boolean {
+  return nonInteractiveReason(inputs) === undefined;
+}
+
+/**
+ * Why this run cannot ask a question, as a plain sentence, or undefined when it
+ * can. The reason is quoted in the error a blocked prompt raises, because "sous
+ * is not running where it can ask" is baffling on its own when the caller is
+ * sitting at a terminal and only `CI=1` in their shell made it true.
+ *
+ * @param inputs - Overrides for the command line, environment and streams.
+ */
+export function nonInteractiveReason(inputs: InteractiveInputs = {}): string | undefined {
+  const argv = inputs.argv ?? process.argv;
+  const env = inputs.env ?? process.env;
+  const stdinIsTTY = inputs.stdinIsTTY ?? process.stdin.isTTY === true;
+  const stdoutIsTTY = inputs.stdoutIsTTY ?? process.stdout.isTTY === true;
+
+  if (hasNonInteractiveFlag(argv)) {
+    return `the '${NON_INTERACTIVE_FLAG}' flag was passed`;
+  }
+
+  const ci = env.CI;
+  if (ci !== undefined && !FALSY_CI_VALUES.has(ci.trim().toLowerCase())) {
+    return `the 'CI' environment variable is set to '${ci}'`;
+  }
+
+  if (!stdinIsTTY && !stdoutIsTTY) return "neither input nor output is a terminal";
+  if (!stdinIsTTY) return "input is not a terminal";
+  if (!stdoutIsTTY) return "output is not a terminal";
+
+  return undefined;
+}
+
+/**
+ * True when the command line carries `--non-interactive`. Scanning stops at a
+ * bare `--`, exactly as the config-flag readers do: anything after it belongs to
+ * a launched tool, never to sous.
+ *
+ * @param argv - The raw command line.
+ */
+function hasNonInteractiveFlag(argv: string[]): boolean {
+  for (const arg of argv) {
+    if (arg === "--") return false;
+    if (arg === NON_INTERACTIVE_FLAG) return true;
+  }
+  return false;
+}
+
+/**
+ * A ConfigError raised because a question could not be asked. It carries a flag
+ * telling the command layer to print the command's own help underneath it, so
+ * the caller sees every flag that could have answered the question.
+ */
+export class NonInteractiveError extends ConfigError {
+  /** Tells `BaseCommand` to print the command's help after this error. */
+  readonly showHelp = true;
+
+  constructor(message: string) {
+    super(message);
+    this.name = "NonInteractiveError";
+  }
+}
+
+/** True when an error asked for the command's help to be printed with it. */
+export function wantsHelp(error: unknown): boolean {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    (error as { showHelp?: boolean }).showHelp === true
+  );
+}
+
+/** What a blocked prompt needs to describe itself. */
+export type BlockedPrompt = {
+  /** The question that could not be asked, named as a person would name it. */
+  prompt: string;
+  /**
+   * How to answer it ahead of time: a flag, or the environment variables. A
+   * remedy names the flag's primary spelling, and lists its alternate spellings
+   * once, in one parenthetical; the alternates are defined in
+   * `utils/flags.ts` and the command's own help (printed underneath this error)
+   * lists them too.
+   */
+  remedy: string;
+  /** Extra lines of context, such as the candidates that could not be chosen between. */
+  details?: string[];
+  /** Overrides for the command line, environment and streams. */
+  inputs?: InteractiveInputs;
+};
+
+/**
+ * Builds the error a blocked prompt raises: what could not be asked, why sous
+ * could not ask it, and what would have answered it without a terminal.
+ *
+ * @param blocked - The prompt, the remedy and any extra context.
+ */
+export function nonInteractiveError(blocked: BlockedPrompt): NonInteractiveError {
+  const reason = nonInteractiveReason(blocked.inputs ?? {}) ?? "there is no terminal to ask on";
+  const lines = [
+    `Sous has to ask ${blocked.prompt}, and it is not running where it can ask.`,
+    `  Why: ${reason}.`,
+  ];
+  for (const detail of blocked.details ?? []) lines.push(`  ${detail}`);
+  lines.push(`  Answer it ahead of time: ${blocked.remedy}`);
+  return new NonInteractiveError(lines.join("\n"));
+}

package/src/lib/markdown-compiler.ts

@@ -2,7 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { execFileSync } from "node:child_process";
 import { get_encoding, type Tiktoken } from "tiktoken";
-import { displayError, log, showVar, subheading, warning } from "../utils/formatting.js";
+import { displayError, log, showVariable, subheading, warning } from "../utils/formatting.js";
 import { createLiquidEngine } from "../templating/init-liquid-engine.js";
 import {
   StateService,
@@ -11,7 +11,11 @@ import {
   hashContent,
   recordDirCreation,
 } from "./state.js";
-import { resolveIncludeCandidates, type AliasMap } from "./include-resolver.js";
+import { resolveInclude, type AliasMap } from "./include-resolver.js";
+import {
+  formatNamespaceProblem,
+  type NamespaceResolver,
+} from "./repos/namespace-resolver.js";
 
 export type ResolvedOutput = {
   destinationFile?: string;
@@ -62,6 +66,13 @@ export type CompilationServiceOptions = {
   strict?: boolean;
   rebuild?: boolean;
   dryRun?: boolean;
+  /**
+   * Resolves `@~<namespace>/<recipe>/<path>` includes and the matching
+   * `{% render %}` paths against recipe namespaces. Omit it and the `~` sigil
+   * only ever means an alias, which is the behavior for projects that use no
+   * repositories.
+   */
+  namespaceResolver?: NamespaceResolver;
 };
 
 /**
@@ -73,6 +84,36 @@ export type CompilationServiceOptions = {
  *   "/foo/bar/*\/baz.md" → "/foo/bar"
  *   "/**\/*"             → "/"
  */
+/**
+ * The file one output of one target writes, or undefined when the output names
+ * neither a destination file nor a destination directory.
+ *
+ * A `destinationFile` is used as it stands. A `destinationDir` mirrors the
+ * source tree underneath it, relative to the target's `globBase`, with `.tpl.`
+ * stripped from the name.
+ *
+ * Exported because prune needs the same answer without compiling: a group of
+ * targets that share one destination directory (every subscribed recipe writing
+ * into `.claude/skills`, say) can only be pruned precisely if the exact set of
+ * files they write is known.
+ *
+ * @param target - The compilation target.
+ * @param output - One of its outputs.
+ */
+export function resolveOutputPath(
+  target: Pick<CompilationTarget, "rootInputPath" | "globBase">,
+  output: ResolvedOutput
+): string | undefined {
+  if (output.destinationFile) return output.destinationFile;
+  if (!output.destinationDir) return undefined;
+
+  const sourceRelative = target.globBase
+    ? path.relative(target.globBase, target.rootInputPath)
+    : path.basename(target.rootInputPath);
+
+  return path.join(output.destinationDir, sourceRelative.replace(/\.tpl\./, "."));
+}
+
 export function inferGlobBase(pattern: string): string {
   const parts = pattern.split("/");
   const staticParts: string[] = [];
@@ -101,6 +142,7 @@ export class CompilationService {
   private numberFormatter: Intl.NumberFormat;
   private aliases: AliasMap;
   private includeScope: Record<string, string>;
+  private namespaceResolver?: NamespaceResolver;
   /**
    * `.tpl.` outputs that were written without a variable scope, so LiquidJS never
    * ran and the template shipped with its tags intact. Reported at the end of the
@@ -121,6 +163,7 @@ export class CompilationService {
     this.numberFormatter = new Intl.NumberFormat("en-US");
     this.aliases = {};
     this.includeScope = {};
+    this.namespaceResolver = options.namespaceResolver;
     this.unrenderedTemplates = [];
   }
 
@@ -146,19 +189,35 @@ export class CompilationService {
    * Matches an `@`-prefixed `.md` path on its own line. The path may be:
    *   - relative to the including file (`@sections/intro.md`),
    *   - a `${var}`-substituted path (`@${sousRootPath}/x.md`),
-   *   - or an alias path (`@~sous-shared/memories/x.md`, `@docs/x.md`), where the
-   *     first segment (up to `/` or `:`) names a registered alias.
+   *   - an alias path (`@~project/memories/x.md`, `@docs/x.md`), where the
+   *     first segment (up to `/` or `:`) names a registered alias,
+   *   - or a recipe namespace path (`@~workflow/task-files/_partials/x.md`),
+   *     where the `~` sigil names a namespace and the rest names a recipe and a
+   *     file inside it. Namespaces are only consulted when a namespace resolver
+   *     was supplied, and always after aliases.
    *
    * Lines inside fenced code blocks (``` or ~~~, per CommonMark) are left
    * verbatim, so include syntax can be documented without being executed.
    *
    * Resolution produces an ordered candidate list (see include-resolver); the
    * first candidate that exists on disk is used. If none exist, it errors,
-   * listing every path tried.
+   * naming the including file and listing every path tried, plus what went
+   * wrong with the namespace lookup when one was attempted.
+   *
+   * @param content - The file's raw text.
+   * @param baseDir - Directory the relative candidate resolves against.
+   * @param projectRoot - Root used to render source comments as relative paths.
+   * @param fromFile - Absolute path of the file being processed; defaults to `baseDir`.
    */
-  private processIncludes(content: string, baseDir: string, projectRoot: string): string {
-    // First segment allows ~, then path chars; separators / and :; allows ${...}.
-    const includePattern = /^@([~a-zA-Z0-9_${}][a-zA-Z0-9_\-/.:${}]*\.md)$/;
+  private processIncludes(
+    content: string,
+    baseDir: string,
+    projectRoot: string,
+    fromFile?: string
+  ): string {
+    // First segment allows ~ and . (so ./ and ../ work), then path chars;
+    // separators / and :; allows ${...}.
+    const includePattern = /^@([~a-zA-Z0-9_.${}][a-zA-Z0-9_\-/.:${}]*\.md)$/;
     const fenceOpenPattern = /^ {0,3}(`{3,}|~{3,})/;
     const fenceClosePattern = /^ {0,3}(`{3,}|~{3,})[ \t]*$/;
 
@@ -192,16 +251,23 @@ export class CompilationService {
       }
 
       const includePath = match[1].trim();
-      const candidates = resolveIncludeCandidates(includePath, {
+      const { candidates, namespaceIssue } = resolveInclude(includePath, {
         aliases: this.aliases,
         scope: this.includeScope,
         baseDir,
+        namespaceResolver: this.namespaceResolver,
+        fromFile: fromFile ?? baseDir,
       });
       const fullPath = candidates.find((c) => fs.existsSync(c));
 
       if (!fullPath) {
+        const explanation = namespaceIssue
+          ? `\n${formatNamespaceProblem(namespaceIssue)}`
+          : `\n  in file: ${fromFile ?? baseDir}`;
         this.handleError(
-          `Include not found: @${includePath}\n  tried:\n${candidates.map((c) => `    - ${c}`).join("\n")}`
+          `Include not found: @${includePath}${explanation}\n  tried:\n${candidates
+            .map((c) => `    - ${c}`)
+            .join("\n")}`
         );
         out.push("");
         continue;
@@ -246,7 +312,7 @@ export class CompilationService {
     try {
       const content = fs.readFileSync(filePath, "utf8");
       const baseDir = path.dirname(filePath);
-      const processedContent = this.processIncludes(content, baseDir, projectRoot);
+      const processedContent = this.processIncludes(content, baseDir, projectRoot, filePath);
       this.visited.add(filePath);
       return processedContent;
     } catch (error) {
@@ -258,11 +324,25 @@ export class CompilationService {
     }
   }
 
-  /** Render template content using LiquidJS with the given variable scope. */
-  private async renderContent(content: string, vars: Record<string, string>, roots: string[]): Promise<string> {
+  /**
+   * Render template content using LiquidJS with the given variable scope.
+   *
+   * @param content - The template text.
+   * @param vars - Variable scope handed to LiquidJS and to `${var}` path substitution.
+   * @param roots - Filesystem roots searched by `{% render %}`.
+   * @param fromFile - Absolute path of the template, so `~namespace` render paths are scoped correctly.
+   */
+  private async renderContent(
+    content: string,
+    vars: Record<string, string>,
+    roots: string[],
+    fromFile?: string
+  ): Promise<string> {
     const engine = createLiquidEngine(roots, {
       aliases: this.aliases,
       scope: { ...this.includeScope, ...vars },
+      namespaceResolver: this.namespaceResolver,
+      fromFile,
     });
     try {
       return await engine.parseAndRender(content, vars);
@@ -343,7 +423,7 @@ ${taskFileContents}
     stateFileEntries: StateFileEntry[]
   ): Promise<boolean> {
     subheading(path.basename(target.rootInputPath), "▷");
-    showVar("Entry Point", target.rootInputPath);
+    showVariable("Entry Point", target.rootInputPath);
 
     this.initializeEncoder();
 
@@ -377,22 +457,10 @@ ${taskFileContents}
       // Resolve destination path: prefer destinationFile, fall back to destinationDir mirroring
       let destFile: string;
 
-      if (output.destinationFile) {
-        destFile = output.destinationFile;
-      } else if (output.destinationDir) {
-        // Mirror source path structure under destinationDir
-        const sourceRelative = target.globBase
-          ? path.relative(target.globBase, target.rootInputPath)
-          : path.basename(target.rootInputPath);
-
-        // Strip .tpl. from the output filename (e.g. foo.tpl.md -> foo.md)
-        const outputRelative = sourceRelative.replace(/\.tpl\./, ".");
-
-        destFile = path.join(output.destinationDir, outputRelative);
-      } else {
-        // Neither set — skip
-        continue;
-      }
+      const resolvedDest = resolveOutputPath(target, output);
+      // Neither destinationFile nor destinationDir set — skip
+      if (resolvedDest === undefined) continue;
+      destFile = resolvedDest;
 
       // Skip if content is unchanged and file already exists (unless --rebuild)
       const existingEntry = state.files.find(f => f.dest === destFile);
@@ -424,11 +492,16 @@ ${taskFileContents}
       }
 
       const resolvedContent = (isTpl && output.vars)
-        ? await this.renderContent(content, {
-            ...output.vars,
-            sousTemplatePath: target.rootInputPath,
-            sousTemplateDir: promptsRoot,
-          }, [promptsRoot])
+        ? await this.renderContent(
+            content,
+            {
+              ...output.vars,
+              sousTemplatePath: target.rootInputPath,
+              sousTemplateDir: promptsRoot,
+            },
+            [promptsRoot],
+            target.rootInputPath
+          )
         : content;
       const fileContent = resolvedContent;
       const outputDir = path.dirname(destFile);
@@ -557,8 +630,16 @@ ${taskFileContents}
         subheading("Done.", "✓");
       }
 
-      // Update state with fresh entries
-      state.files = stateFileEntries;
+      // Update state: fresh entries for everything compiled this pass, plus
+      // carried-forward entries for outputs this pass did not touch — other
+      // targets' outputs during a partial rebuild, and outputs dropped from the
+      // config, which must stay tracked so prune/clear can still find them.
+      // Entries whose files are gone from disk are released.
+      const writtenDests = new Set(stateFileEntries.map((e) => e.dest));
+      state.files = [
+        ...stateFileEntries,
+        ...state.files.filter((f) => !writtenDests.has(f.dest) && fs.existsSync(f.dest)),
+      ];
       state.lastBuild = new Date().toISOString();
 
       if (stateFilePath && !this.dryRun) {