@sous-io/sous 0.2.3 → 0.2.6

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/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/project-install.d.mts

@@ -0,0 +1,31 @@
+/**
+ * Types for project-install.mjs, which is plain JavaScript because it runs
+ * before tsx is registered. Keep the two in step by hand.
+ */
+
+export const PACKAGE_NAME: "@sous-io/sous";
+export const NO_DELEGATE_ENV: "SOUS_NO_DELEGATE";
+export const DEBUG_ENV: "SOUS_DEBUG";
+
+export type ProjectInstall =
+  | { same: true; root: string }
+  | { same: false; root: string; version: string; bin: string };
+
+export type HandoffPlan =
+  | { kind: "run-self" }
+  | { kind: "hand-off"; install: Extract<ProjectInstall, { same: false }>; notice: string | undefined };
+
+export function isEnvFlagOn(value: string | undefined): boolean;
+export function binEntryOf(pkg: unknown): string | undefined;
+export function findProjectInstall(startDir: string, ownRoot: string): ProjectInstall | undefined;
+export function planHandoff(input: {
+  cwd: string;
+  ownRoot: string;
+  env: Record<string, string | undefined>;
+}): HandoffPlan;
+export function handOffToProjectInstall(input: {
+  ownRoot: string;
+  cwd?: string;
+  env?: Record<string, string | undefined>;
+  stderr?: { write(chunk: string): unknown };
+}): Promise<boolean>;

package/src/lib/project-install.mjs

@@ -0,0 +1,175 @@
+/**
+ * The hand-off from the sous that was invoked to the sous a project installs.
+ *
+ * A global install is a convenience launcher; a project's own `@sous-io/sous`
+ * dependency is the version its templates and its lockfile were written
+ * against, and it is the one that has to do the work (the implicit `core`
+ * subscription asks for exactly the running version, so two versions taking
+ * turns in one project rewrite the committed lockfile back and forth). The
+ * published bin (bin/run.js) calls `handOffToProjectInstall` before it loads
+ * anything else, and when a project copy is found, imports that copy's own bin
+ * in this same process and lets it run the command.
+ *
+ * Plain JavaScript ESM, no TypeScript syntax: this runs BEFORE tsx is
+ * registered, under bare Node, because the whole point is to load none of the
+ * invoked install's code when another copy should run. It ships to npm via the
+ * package.json "files": "src" allowlist, like the config kernel next to it.
+ *
+ * The rules, all of them here and nowhere else:
+ *   - The lookup walks up from the working directory looking for
+ *     `node_modules/@sous-io/sous`, the way Node resolves a package, so a copy
+ *     hoisted to a monorepo root is found from any package inside it.
+ *   - A copy whose real path is the invoked install's own root is "self", and
+ *     self never hands off; that is what stops the project's copy from
+ *     handing off to itself after the global copy handed off to it.
+ *   - The copy's bin is read from its package.json `bin` field, never assumed,
+ *     so an older layout (the bin was once called `xcv`) still works.
+ *   - Anything unreadable or ambiguous means "run the copy that was invoked".
+ *     A hand-off is a convenience; a refusal to run is not.
+ *   - `SOUS_NO_DELEGATE` (anything but 0/false/no/off) runs the invoked copy.
+ *   - The notice goes to stderr, so piped stdout stays clean, and only when
+ *     the two versions differ; `SOUS_DEBUG` prints it on every hand-off.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+/** The npm package name a project copy is looked up under. */
+export const PACKAGE_NAME = "@sous-io/sous";
+
+/** The environment variable that keeps the invoked copy running. */
+export const NO_DELEGATE_ENV = "SOUS_NO_DELEGATE";
+
+/** The environment variable that makes every hand-off announce itself. */
+export const DEBUG_ENV = "SOUS_DEBUG";
+
+/**
+ * Whether an on/off environment variable is on: set to anything but an empty
+ * string, `0`, `false`, `no` or `off` (case-insensitive, whitespace trimmed).
+ * The same reading `SOUS_DEBUG` has always had.
+ */
+export function isEnvFlagOn(value) {
+  return !["", "0", "false", "no", "off"].includes((value ?? "").trim().toLowerCase());
+}
+
+/**
+ * Reads a package.json, returning the parsed object or undefined for a file
+ * that is missing, unreadable or not JSON.
+ */
+function readPackageJson(dir) {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(dir, "package.json"), "utf8"));
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Works out which file a package's `bin` field names for the `sous` command,
+ * relative to the package root, or undefined when it cannot be told: no field,
+ * an object naming neither `sous` nor `xcv` with more than one entry, or a
+ * value that is not a string.
+ */
+export function binEntryOf(pkg) {
+  const bin = pkg?.bin;
+  if (typeof bin === "string") return bin;
+  if (!bin || typeof bin !== "object") return undefined;
+  const named = bin.sous ?? bin.xcv;
+  if (typeof named === "string") return named;
+  const entries = Object.values(bin);
+  if (entries.length === 1 && typeof entries[0] === "string") return entries[0];
+  return undefined;
+}
+
+/**
+ * Looks up from `startDir` for a project install of the package.
+ *
+ * Returns undefined when no ancestor holds `node_modules/@sous-io/sous`, or
+ * when the first one found is not usable (its package.json does not name the
+ * package, or its bin cannot be determined or does not exist). Returns
+ * `{ same: true, root }` when the first copy found IS the invoked install
+ * (`ownRoot`), compared by real path, and otherwise `{ same: false, root,
+ * version, bin }` with `bin` as an absolute path.
+ *
+ * The walk stops at the first copy, usable or not: a broken copy nearer the
+ * working directory is what `npx` would run too, and skipping past it to an
+ * older one further up would be a guess.
+ */
+export function findProjectInstall(startDir, ownRoot) {
+  let dir = path.resolve(startDir);
+  for (;;) {
+    const candidate = path.join(dir, "node_modules", ...PACKAGE_NAME.split("/"));
+    if (fs.existsSync(path.join(candidate, "package.json"))) {
+      return describeInstall(candidate, ownRoot);
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) return undefined;
+    dir = parent;
+  }
+}
+
+function realpathOr(p) {
+  try {
+    return fs.realpathSync(p);
+  } catch {
+    return path.resolve(p);
+  }
+}
+
+function describeInstall(candidate, ownRoot) {
+  const root = realpathOr(candidate);
+  if (root === realpathOr(ownRoot)) return { same: true, root };
+  const pkg = readPackageJson(root);
+  if (!pkg || pkg.name !== PACKAGE_NAME) return undefined;
+  const entry = binEntryOf(pkg);
+  if (!entry) return undefined;
+  const bin = path.resolve(root, entry);
+  if (!fs.existsSync(bin)) return undefined;
+  return { same: false, root, version: typeof pkg.version === "string" ? pkg.version : "unknown", bin };
+}
+
+/**
+ * Decides what the invoked install should do, without doing it.
+ *
+ * Returns `{ kind: "run-self" }` when the invoked copy runs the command, or
+ * `{ kind: "hand-off", install, notice }` naming the project copy to import
+ * and the sentence to print on stderr first (undefined when nothing is said).
+ */
+export function planHandoff({ cwd, ownRoot, env }) {
+  if (isEnvFlagOn(env[NO_DELEGATE_ENV])) return { kind: "run-self" };
+  const install = findProjectInstall(cwd, ownRoot);
+  if (!install || install.same) return { kind: "run-self" };
+
+  const ownPkg = readPackageJson(ownRoot);
+  const ownVersion = typeof ownPkg?.version === "string" ? ownPkg.version : "unknown";
+  const differ = ownVersion !== install.version;
+  let notice;
+  if (differ) {
+    notice =
+      `Running the project's own sous ${install.version} from ${install.root} instead of the ` +
+      `sous ${ownVersion} you invoked; set ${NO_DELEGATE_ENV}=1 to run the one you invoked.`;
+  } else if (isEnvFlagOn(env[DEBUG_ENV])) {
+    notice = `Running the project's own sous ${install.version} from ${install.root}.`;
+  }
+  return { kind: "hand-off", install, notice };
+}
+
+/**
+ * Hands the current invocation to the project's copy when there is one to hand
+ * it to. Resolves true after that copy's bin has run (it reads the same
+ * process.argv and sets the same exit code), and false, having loaded nothing,
+ * when the invoked copy should run the command itself.
+ */
+export async function handOffToProjectInstall({
+  ownRoot,
+  cwd = process.cwd(),
+  env = process.env,
+  stderr = process.stderr,
+}) {
+  const plan = planHandoff({ cwd, ownRoot, env });
+  if (plan.kind !== "hand-off") return false;
+  if (plan.notice) stderr.write(`${plan.notice}\n`);
+  await import(pathToFileURL(plan.install.bin).href);
+  return true;
+}