@sous-io/sous 0.2.2 → 0.2.4

package/src/commands/init.ts

@@ -0,0 +1,269 @@
+/**
+ * `sous init` sets a project up for sous.
+ *
+ * It writes the `.sous/` directory a project needs (a commented primary config,
+ * the starter prompt that config compiles, the two answers files and the
+ * sous-managed ignore block) and then runs the first build, which is what
+ * seeds the `core` recipe and pins it in the lockfile. A project that is
+ * already set up is left exactly as it is.
+ *
+ * This is the one command that runs BEFORE a project config exists, so it
+ * opts out of the config requirement every other command inherits. Discovery
+ * still runs, which is how `--sous-dir` and `SOUS_DIR` say where to write, and
+ * how a run inside an existing project is noticed.
+ */
+
+import path from "node:path";
+import { Args, Flags } from "@oclif/core";
+import { confirm } from "@inquirer/prompts";
+import { BaseCommand } from "../base-command.js";
+import { prepareRepositoriesForBuild } from "../lib/build-preparation.js";
+import { buildProjectOutputs } from "../lib/build-service.js";
+import {
+  CONFIG_FILE_NAMES,
+  SOUS_DIR_NAME,
+  discoverConfig,
+  expandHome,
+  resolveConfigFlag,
+} from "../lib/config-discovery.js";
+import { ConfigError } from "../lib/errors.js";
+import { nonInteractiveError } from "../lib/interactive.js";
+import { subscriptionServiceFor } from "../lib/repos/subscription-service.js";
+import {
+  PROJECT_CONFIG_FORMATS,
+  STARTER_OUTPUT_NAME,
+  STARTER_PROMPT_RELATIVE_PATH,
+  scaffoldProject,
+  sousDirFor,
+  type ProjectConfigFormat,
+} from "../lib/project-scaffold/index.js";
+import { SOUS_VERSION } from "../lib/settings.js";
+import { confirmationFlag } from "../utils/flags.js";
+import {
+  blankLine,
+  dryRunNotice,
+  footer,
+  heading,
+  log,
+  paragraph,
+  section,
+  showCommandVars,
+  showVariables,
+  warning,
+} from "../utils/formatting.js";
+
+export default class Init extends BaseCommand {
+  static description =
+    "Set a project up for sous: write its .sous/ directory, then run the first build";
+
+  /** This command creates the config; finding none is its normal case. */
+  static override requiresConfig = false;
+
+  static examples = [
+    "<%= config.bin %> init",
+    "<%= config.bin %> init ./my-project",
+    "<%= config.bin %> init --format json",
+    "<%= config.bin %> init --name 'My Project' --no-build",
+    "<%= config.bin %> init --dry-run",
+  ];
+
+  static args = {
+    directory: Args.string({
+      description: "Project directory to set up (defaults to the current one)",
+      required: false,
+    }),
+  };
+
+  static flags = {
+    ...BaseCommand.baseFlags,
+    format: Flags.string({
+      description: "Format of the primary config to write",
+      options: [...PROJECT_CONFIG_FORMATS],
+      default: PROJECT_CONFIG_FORMATS[0],
+    }),
+    name: Flags.string({
+      description: "Display name for the project (defaults to the directory's own name)",
+    }),
+    // The one question this command can ask: whether to set up a project
+    // inside another one.
+    yes: confirmationFlag(),
+    "dry-run": Flags.boolean({
+      description: "Print the files that would be written without writing them",
+      default: false,
+    }),
+    "no-build": Flags.boolean({
+      description: "Write the setup without running the first build",
+      default: false,
+    }),
+  };
+
+  async run(): Promise<void> {
+    const { args, flags } = await this.parse(Init);
+    const dryRun = flags["dry-run"];
+    const format = flags.format as ProjectConfigFormat;
+
+    const sousDir = this.targetSousDir(args.directory);
+    const projectRoot = path.dirname(sousDir);
+
+    showCommandVars({
+      Directory: projectRoot,
+      Config: path.join(sousDir, `sous.config.${format}`),
+      Name: flags.name ?? "(from the directory name)",
+      "Dry Run": dryRun,
+      Build: !dryRun && !flags["no-build"],
+    });
+
+    await this.confirmNesting(projectRoot, flags.yes);
+
+    section("Setting up the project");
+
+    const result = await scaffoldProject({
+      sousDir,
+      format,
+      name: flags.name,
+      dryRun,
+      sousVersion: SOUS_VERSION,
+    });
+
+    for (const file of result.files) {
+      if (result.dryRun) dryRunNotice(`would write ${file}`);
+      else log(`  wrote ${file}`);
+    }
+
+    if (result.dryRun) {
+      blankLine();
+      dryRunNotice("Nothing was written. Run the same command without '--dry-run' to set the project up.");
+      footer();
+      return;
+    }
+
+    if (!flags["no-build"]) {
+      await this.buildProject(result.configPath);
+    }
+
+    section("What was set up");
+    showVariables([
+      { label: "Config", value: result.configPath },
+      { label: "Prompt source", value: path.join(sousDir, STARTER_PROMPT_RELATIVE_PATH) },
+      { label: "Compiled to", value: path.join(projectRoot, STARTER_OUTPUT_NAME) },
+      { label: "Skills", value: path.join(projectRoot, ".claude", "skills") },
+      { label: "Shared answers", value: path.join(sousDir, ".env"), detail: "committed" },
+      {
+        label: "Local answers",
+        value: path.join(sousDir, ".env.local"),
+        detail: "gitignored; .env.local.example shows the layout",
+      },
+    ]);
+
+    blankLine();
+    paragraph(
+      `  ${STARTER_OUTPUT_NAME} and the skills directory are build output, compiled from the ` +
+        `prompt source and from the recipes this project subscribes to; a build recompiles ` +
+        `them. The config explains each of its blocks in its own comments.`
+    );
+
+    footer();
+  }
+
+  /**
+   * Where the `.sous/` directory goes. A directory argument wins; otherwise the
+   * config-locating flags say where the project is, and otherwise it is the
+   * working directory. A path that already names a `.sous/` directory, or a
+   * config file inside one, is honored as such.
+   */
+  private targetSousDir(directory: string | undefined): string {
+    if (directory !== undefined) {
+      return sousDirFor(path.resolve(this.configLocator.cwd, expandHome(directory)));
+    }
+
+    const primary = this.configLocator.primary;
+    if (primary === undefined) return sousDirFor(this.configLocator.cwd);
+
+    const value = primary.value;
+    if (path.basename(value) === SOUS_DIR_NAME) return value;
+    if ((CONFIG_FILE_NAMES as readonly string[]).includes(path.basename(value))) {
+      return path.dirname(value);
+    }
+    return sousDirFor(value);
+  }
+
+  /**
+   * A project set up inside another one is a real choice, not a mistake sous
+   * should prevent: a subproject may want its own instructions. So when a walk
+   * up from the target finds a config in a parent directory, the facts are
+   * stated and the question is asked once; `--yes` answers it ahead of time,
+   * and a run with no terminal fails naming that flag.
+   *
+   * The target's own `.sous/` holding a config is a different case, refused
+   * outright by the scaffold.
+   */
+  private async confirmNesting(projectRoot: string, confirmed: boolean): Promise<void> {
+    const enclosing = discoverConfig(projectRoot);
+    if (enclosing === null || path.dirname(enclosing.sousDir) === projectRoot) return;
+
+    const enclosingRoot = path.dirname(enclosing.sousDir);
+
+    warning(
+      `${projectRoot} is inside a project that is already set up for sous.\n` +
+        `  The enclosing project's config is ${enclosing.configPath}.\n` +
+        `  Setting this directory up too gives it a config of its own: commands run ` +
+        `here will find this one, and commands run from ${enclosingRoot} will keep ` +
+        `finding the other.`
+    );
+
+    if (confirmed) return;
+
+    if (!this.interactive) {
+      throw nonInteractiveError({
+        prompt: `whether to set up ${projectRoot} inside the project at ${enclosingRoot}`,
+        remedy: "pass --yes (also -y, --force) to set it up anyway",
+      });
+    }
+
+    blankLine();
+    const proceed = await confirm({
+      message: `Set up ${projectRoot} as a project of its own?`,
+      default: false,
+    });
+    if (!proceed) {
+      throw new ConfigError(
+        `Nothing was written. Run 'sous init' from a directory outside ${enclosingRoot}, ` +
+          `or pass --yes to set this one up anyway.`
+      );
+    }
+  }
+
+  /**
+   * Adopts the config just written and builds the project with it, in the
+   * same two steps `sous build` takes: the repositories are prepared (which
+   * seeds the core recipe into the store and pins it in the lockfile), then
+   * the outputs are compiled.
+   *
+   * @param configPath - The primary config the scaffold wrote.
+   */
+  private async buildProject(configPath: string): Promise<void> {
+    await this.adoptConfig(
+      resolveConfigFlag(configPath, this.configLocator.cwd, this.configLocator.confDirOverride)
+    );
+
+    await prepareRepositoriesForBuild(
+      subscriptionServiceFor({
+        configContext: this.configContext,
+        settings: this.settings,
+        shellEnv: this.shellEnv,
+      })
+    );
+
+    heading("Building the project");
+
+    const succeeded = await buildProjectOutputs(this.settings, this.configContext);
+
+    if (!succeeded) {
+      throw new ConfigError(
+        `The project is set up, but the first build failed, so its outputs may be ` +
+          `incomplete. Everything 'sous init' wrote is in place; fix what the build ` +
+          `reported above and run 'sous build' again.`
+      );
+    }
+  }
+}

package/src/lib/build-preparation.ts

@@ -0,0 +1,86 @@
+/**
+ * The step that runs before a project's outputs are compiled, and what it says
+ * while it runs. `sous build` runs it on every build, and `sous init` runs it
+ * for the first build of a project it has just set up; both must say the same
+ * things about the same events, so the reporting lives here rather than in
+ * either command.
+ */
+
+import type { SubscriptionService } from "./repos/subscription-service.js";
+import { blankLine, footer, heading, paragraph, warning } from "../utils/formatting.js";
+
+/**
+ * Gets this project's recipes ready to compile: restores whatever the store is
+ * missing (a fresh clone, or a collected store) and then asks upstream for the
+ * repositories that prefer a newer in-range version.
+ *
+ * Restoring asks nothing and decides nothing; it fetches exactly what the
+ * lockfile pins. An upstream check that fails is reported and then ignored,
+ * because a build must not depend on the network being up.
+ *
+ * @param repositories - The subscription service for this project.
+ */
+export async function prepareRepositoriesForBuild(
+  repositories: SubscriptionService
+): Promise<void> {
+  const needsRestore = repositories.needsRestore();
+  if (needsRestore) {
+    heading("Restoring recipes");
+    blankLine();
+    paragraph(
+      "This project's lockfile pins recipes that are not in the store on this " +
+        "machine, so they are being fetched at exactly the versions it records."
+    );
+  }
+
+  const { seed, subscriptions, restored, upstream } =
+    await repositories.prepareForBuild();
+
+  // Seeding the packaged core recipe is silent when it works, which is almost
+  // always; it is only worth a word when it could not be done at all.
+  if (seed.skippedBecause !== undefined) warning(seed.skippedBecause);
+
+  // A subscription the lockfile did not pin yet has just been pinned. That is
+  // a change to a committed file, so it is always announced.
+  if (subscriptions.added.length > 0 || subscriptions.moved.length > 0) {
+    heading("Locking subscribed recipes");
+    blankLine();
+    for (const entry of subscriptions.added) {
+      paragraph(`  pinned: ${entry.key} at version ${entry.version}.`);
+    }
+    for (const change of subscriptions.moved) {
+      paragraph(`  ${change.key} moved from version ${change.from} to version ${change.to}.`);
+    }
+    blankLine();
+    paragraph(
+      "The lockfile has been updated. Commit it, so everyone building this project " +
+        "gets exactly these versions."
+    );
+    footer();
+  }
+
+  for (const failure of subscriptions.failed) {
+    warning(
+      `Sous could not work out which version of '${failure.key}' to use, so nothing ` +
+        `from it was compiled.\n${failure.reason}`
+    );
+  }
+
+  if (restored !== undefined && restored.restored.length > 0) {
+    blankLine();
+    for (const key of restored.restored) paragraph(`  restored: ${key}`);
+  }
+
+  for (const change of upstream.updated) {
+    paragraph(`  ${change.key} moved from ${change.from} to ${change.to}.`);
+  }
+
+  for (const failure of upstream.failed) {
+    warning(
+      `Sous could not check the repository '${failure.repo}' for a newer version, so ` +
+        `this build uses the versions it already had.\n${failure.reason}`
+    );
+  }
+
+  if (needsRestore) footer();
+}

package/src/lib/build-service.ts

@@ -11,6 +11,12 @@ import type { CompilationConfig, CompilationTarget } from "./markdown-compiler.j
 import { StateService } from "./state.js";
 import { isProtectedPath } from "./state.js";
 import { protectedRepoPaths } from "./repos/links.js";
+import {
+  noRecipeAnswers,
+  resolveRecipeAnswers,
+  unansweredWarning,
+  type RecipeAnswers,
+} from "./vars/answers.js";
 import { log, warning } from "../utils/formatting.js";
 
 export type BuildOptions = {
@@ -50,26 +56,65 @@ const NO_RECIPE_TARGETS: RecipeTargets = {
   warnings: [],
 };
 
+/**
+ * The answers to every recipe variable in play for the project the context
+ * describes, resolved once so a build can render with them, hand them to every
+ * scope it builds, and report what is still unanswered. Empty when the caller
+ * gave no config context.
+ *
+ * @param settings - The merged project config.
+ * @param configContext - Where the active config was discovered.
+ */
+export function resolveProjectAnswers(
+  settings: Settings,
+  configContext?: ConfigContext
+): RecipeAnswers {
+  if (configContext === undefined) return noRecipeAnswers();
+  return resolveRecipeAnswers({ settings, sousDir: configContext.sousDir });
+}
+
 /**
  * The compile targets a project's subscribed recipes contribute, for the project
  * the options describe. Empty when the caller gave no config context, which is
  * the case only in tests that build a settings object by hand.
  *
+ * Each recipe's files render with that recipe's own view of the answers, and a
+ * required variable nothing answered is reported through `warnings`, so every
+ * caller that prints those tells the user what the build could not fill in.
+ *
  * @param settings - The merged project config.
  * @param rootScope - The resolved settings scope, for `${var}` in destinations.
  * @param configContext - Where the active config was discovered.
+ * @param answers - The project's recipe answers, when the caller resolved them
+ *   already; resolved here otherwise.
  */
 export function resolveRecipeTargets(
   settings: Settings,
   rootScope: Record<string, string>,
-  configContext?: ConfigContext
+  configContext?: ConfigContext,
+  answers?: RecipeAnswers
 ): RecipeTargets {
   if (configContext === undefined) return NO_RECIPE_TARGETS;
-  return buildRecipeTargets({
+  const resolved = answers ?? resolveProjectAnswers(settings, configContext);
+  const scopes = new Map<string, Record<string, string>>();
+
+  const recipes = buildRecipeTargets({
     sousDir: configContext.sousDir,
     settings,
     scope: rootScope,
+    scopeFor: (recipe) => {
+      let scope = scopes.get(recipe.key);
+      if (scope === undefined) {
+        scope = resolveRootScope(settings, configContext, { answers: resolved, recipe: recipe.key });
+        scopes.set(recipe.key, scope);
+      }
+      return scope;
+    },
   });
+
+  const missing = unansweredWarning(resolved, rootScope);
+  if (missing !== undefined) recipes.warnings.push(missing);
+  return recipes;
 }
 
 /**
@@ -232,7 +277,10 @@ export class BuildService {
    * Returns true if all steps succeeded.
    */
   async build(settings: Settings, options: BuildOptions = {}): Promise<boolean> {
-    const rootScope = resolveRootScope(settings, options.configContext);
+    // The recipe answers are resolved once here and handed to every scope the
+    // build assembles, so the lockfile and the manifests are read one time.
+    const answers = resolveProjectAnswers(settings, options.configContext);
+    const rootScope = resolveRootScope(settings, options.configContext, { answers });
     const namespaceResolver = resolveNamespaceResolver(settings, options);
     const protectedPaths = protectedPathsFor(options);
 
@@ -260,7 +308,7 @@ export class BuildService {
     // targets alongside its own, so a recipe's files are compiled by exactly the
     // same machinery as everything else, and are pruned and cleared by it too.
     if (!options.noCompile) {
-      const recipes = resolveRecipeTargets(settings, rootScope, options.configContext);
+      const recipes = resolveRecipeTargets(settings, rootScope, options.configContext, answers);
       for (const notice of recipes.warnings) warning(notice);
 
       const config = withRecipeTargets(

package/src/lib/config-discovery.ts

@@ -371,22 +371,8 @@ export function formatNotFoundMessage(startDir: string = process.cwd()): string
     checked + more,
     "",
     "  To fix this, either:",
-    `    1. Create ${SOUS_DIR_NAME}/${CONFIG_FILE_NAMES[0]} in your project root, or`,
+    `    1. Set the project up: run 'sous init' in its root directory, which writes`,
+    `       ${SOUS_DIR_NAME}/${CONFIG_FILE_NAMES[0]} and everything else a first build needs, or`,
     "    2. Pass the config explicitly: sous <command> --config <path>",
-    "",
-    `  A minimal ${CONFIG_FILE_NAMES[0]}:`,
-    "",
-    "    export const config = {",
-    '      name: "My Project",',
-    '      _vars: { projectRoot: "${sousDir}/.." },',
-    "      compilation: {",
-    "        targets: [",
-    "          {",
-    '            entryPoint: "${sousDir}/AGENTS.md",',
-    '            outputs: [{ destinationFile: "${projectRoot}/AGENTS.md" }],',
-    "          },",
-    "        ],",
-    "      },",
-    "    };",
   ].join("\n");
 }

package/src/lib/markdown-compiler.ts

@@ -129,6 +129,17 @@ export function inferGlobBase(pattern: string): string {
   return joined || "/";
 }
 
+/**
+ * A stable text form of an output's variable scope, for the source hash of a
+ * rendered output. Keys are sorted so two scopes holding the same values hash
+ * the same whatever order they were assembled in.
+ *
+ * @param vars - The variable scope an output renders with.
+ */
+export function stableVarsFingerprint(vars: Record<string, string>): string {
+  return JSON.stringify(Object.keys(vars).sort().map((key) => [key, vars[key]]));
+}
+
 export class CompilationService {
   private strict: boolean;
   private rebuild: boolean;
@@ -447,7 +458,7 @@ ${taskFileContents}
     }
 
     // Compute source hash once per target from the assembled content
-    const srcHash = hashContent(content);
+    const contentHash = hashContent(content);
 
     let allSucceeded = true;
 
@@ -462,6 +473,14 @@ ${taskFileContents}
       if (resolvedDest === undefined) continue;
       destFile = resolvedDest;
 
+      // A rendered output depends on its variables as much as on its source: a
+      // changed answer or `_vars` value with the same template must re-render,
+      // so the variable scope is part of a `.tpl.` output's source hash. A
+      // verbatim copy hashes its content alone.
+      const srcHash = isTpl && output.vars
+        ? hashContent(`${content}\n${stableVarsFingerprint(output.vars)}`)
+        : contentHash;
+
       // Skip if content is unchanged and file already exists (unless --rebuild)
       const existingEntry = state.files.find(f => f.dest === destFile);
       if (