@sous-io/sous 0.2.4 → 0.2.7

package/README.md

@@ -26,12 +26,20 @@ formats agents actually read: `.claude/` plus `CLAUDE.md` for Claude Code, `.cod
 
 ## Quickstart
 
-Install the CLI:
+Install the CLI globally, or add it to a project, or both:
 
 ```bash
-npm install -g @sous-io/sous
+npm install -g @sous-io/sous     # one sous for every project on the machine
+npm install -D @sous-io/sous     # the version this project's templates were written against
 ```
 
+A project install pins the sous version a project builds with, and it always does the
+building: a global `sous` run anywhere inside a project that holds `node_modules/@sous-io/sous`
+hands the command to that copy, so `sous`, `npx sous` and a package script all produce the same
+output. When the two versions differ, one line on standard error names the version handed off
+to (`--verbose` adds where both installs are). Set `SOUS_NO_DELEGATE=1` to run the copy you
+invoked instead.
+
 Or run it from a clone (useful when developing sous itself):
 
 ```bash

package/bin/run.js

@@ -1,26 +1,51 @@
 #!/usr/bin/env node
-import { register } from "tsx/esm/api";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { handOffToProjectInstall, isEnvFlagOn } from "../src/lib/project-install.mjs";
 
-// The CLI runs from TypeScript source; register tsx before oclif dynamically
-// imports any command module. Resolving "tsx" from this file (rather than a
-// $PKG_ROOT/node_modules path) works in every install layout: repo clone,
-// global install (nested deps), and local/npx installs (hoisted deps).
-register();
+// A project that installs @sous-io/sous itself has pinned the version its
+// templates and lockfile were written against, so that copy does the work.
+// This runs before anything else is loaded: when a project copy is found, its
+// own bin is imported into this process and this one loads nothing further
+// (see src/lib/project-install.mjs for the rules, and SOUS_NO_DELEGATE to
+// keep the invoked copy running).
+const ownRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const handedOff = await handOffToProjectInstall({ ownRoot });
 
-const { execute, settings } = await import("@oclif/core");
+if (!handedOff) {
+  // The CLI runs from TypeScript source; register tsx before oclif dynamically
+  // imports any command module. Resolving "tsx" from this file (rather than a
+  // $PKG_ROOT/node_modules path) works in every install layout: repo clone,
+  // global install (nested deps), and local/npx installs (hoisted deps).
+  const { register } = await import("tsx/esm/api");
+  register();
 
-// tsx (above) already makes .ts imports work, so oclif's own auto-transpile
-// machinery is redundant; leaving it on makes every downstream run warn that
-// the (unshipped) typescript devDependency is missing.
-settings.enableAutoTranspile = false;
+  // `sous --version` is answered here rather than by oclif, whose answer is
+  // its user agent string. Plain, it is the version alone; `--verbose` adds
+  // the package, where it is installed, the platform and the Node build.
+  const argv = process.argv.slice(2);
+  const { isVersionRequest, printVersion } = await import("../src/lib/version-report.ts");
+  if (isVersionRequest(argv)) {
+    printVersion(argv, ownRoot);
+  } else {
+    await runCommand();
+  }
+}
 
-// oclif's development mode turns on its debug setting, which makes every error
-// it prints a raw stack trace. Sous reports its own errors as sentences (see
-// src/utils/command-errors.ts), so development mode is switched on only when
-// SOUS_DEBUG asks for the traces; anything that gets past a command's own
-// reporting then prints its stack too.
-const debugRequested = !["", "0", "false", "no", "off"].includes(
-  (process.env.SOUS_DEBUG ?? "").trim().toLowerCase()
-);
+async function runCommand() {
+  const { execute, settings } = await import("@oclif/core");
 
-await execute({ development: debugRequested, dir: import.meta.url });
+  // tsx (above) already makes .ts imports work, so oclif's own auto-transpile
+  // machinery is redundant; leaving it on makes every downstream run warn that
+  // the (unshipped) typescript devDependency is missing.
+  settings.enableAutoTranspile = false;
+
+  // oclif's development mode turns on its debug setting, which makes every error
+  // it prints a raw stack trace. Sous reports its own errors as sentences (see
+  // src/utils/command-errors.ts), so development mode is switched on only when
+  // SOUS_DEBUG asks for the traces; anything that gets past a command's own
+  // reporting then prints its stack too.
+  const debugRequested = isEnvFlagOn(process.env.SOUS_DEBUG);
+
+  await execute({ development: debugRequested, dir: import.meta.url });
+}

package/docs/markdown/README.md

@@ -17,6 +17,48 @@ compiled 4 targets, pruned 1 stale file
 ?> These docs are young. **Configuration** and **Repositories** are the reference material so
 far; more will follow.
 
+## Installing
+
+Sous installs three ways, and they work together:
+
+- **Globally** (`npm install -g @sous-io/sous`): one `sous` on the path for every project on the
+  machine, and the one to reach for first.
+- **In a project** (`npm install -D @sous-io/sous`): the project pins the version its templates
+  and its lockfile were written against, and `npx sous` or a package script runs it. This is the
+  right choice for a team, because the implicit `core` subscription asks for exactly the running
+  version and a project built by two versions in turn rewrites its committed lockfile back and
+  forth.
+- **Both**: a global `sous` run anywhere inside a project that holds `node_modules/@sous-io/sous`
+  hands the whole command to that copy before loading any of its own code, so the project's
+  version always does the building however it was invoked. The lookup walks up from the working
+  directory the way Node resolves a package, so a copy hoisted to a monorepo root is found from
+  any package inside it.
+
+When the two versions differ, one line on standard error names the version handed off to;
+standard output is untouched, so a piped command prints exactly what it always did. Add
+`--verbose` to any command and the notice also says where both installs are and how to keep
+the invoked one running; set `SOUS_DEBUG` and the notice prints on every hand-off. Set
+`SOUS_NO_DELEGATE` to anything but `0`, `false`, `no` or `off` to run the copy you invoked
+instead, for debugging a broken project install or for deliberately using the global one:
+
+```term
+$ sous --version
+Handing off to the project-level Sous install: v0.2.4
+v0.2.4
+$ sous --version --verbose
+Handing off to the project-level Sous install: v0.2.4
+    Project install: /work/app/node_modules/@sous-io/sous
+    Invoked install: v0.3.0 at /usr/lib/node_modules/@sous-io/sous
+Set SOUS_NO_DELEGATE=1 to run the invoked install instead.
+v0.2.4
+    Package : @sous-io/sous
+    Install : /work/app/node_modules/@sous-io/sous
+    Platform: linux-x64
+    Node    : v22.21.0
+$ SOUS_NO_DELEGATE=1 sous --version
+v0.3.0
+```
+
 ## Where to look
 
 - Watch the [animated introduction](../) for the full pitch

package/docs/markdown/_sidebar.md

@@ -21,3 +21,4 @@
   - [0001: Repositories](adrs/0001-repositories.md)
   - [0002: Recipe answers in the template scope](adrs/0002-recipe-answers-in-templates.md)
   - [0003: Project setup with sous init](adrs/0003-project-init.md)
+  - [0004: A global sous defers to the project's install](adrs/0004-project-install-handoff.md)

package/docs/markdown/commands.md

@@ -38,7 +38,8 @@ under [When sous cannot ask](repositories-consuming.md#when-sous-cannot-ask).
 
 Help has four spellings. `sous --help` prints the root screen; `sous repo add --help`, `sous repo add -h` and
 `sous help repo add` all print that one command's. `sous help` alone lists the topics and commands, and
-`sous --version` prints the version, platform and Node build.
+`sous --version` prints the version alone, as `v1.2.3`; `sous --version --verbose` adds the package name, where
+it is installed, the platform and the Node build under it.
 
 Every topic answers to both spellings of its name: `repo` and `repos`, `subscription` and `subscriptions`,
 `namespace` and `namespaces`, `recipe` and `recipes`, `lock` and `locks`, `vars` and `var`, `config` and
@@ -338,7 +339,12 @@ $ sous subscription add workflow --non-interactive
 No expected failure prints a stack trace. A failure sous did not expect prints the message and one more sentence
 asking you to set `SOUS_DEBUG=1` and run the command again. Set `SOUS_DEBUG` to anything but `0`, `false`, `no`
 or `off` and every reported failure prints its stack to standard error underneath the message:
-`SOUS_DEBUG=1 sous build`. Nothing else changes when it is set.
+`SOUS_DEBUG=1 sous build`. The one other thing it changes is that every hand-off to a project's own install
+announces itself, not only one between different versions.
+
+`SOUS_NO_DELEGATE` is the other environment variable every command reads. Set it the same way and the copy of
+sous you invoked runs the command, even inside a project that installs its own `@sous-io/sous`; see
+[Installing](README.md#installing) for the hand-off it switches off.
 
 Every listing fits itself to the terminal it runs in: columns shrink, descriptions wrap, and a path or URL is
 cut in the middle so the host and the last segment both survive. On a terminal too narrow, the least important

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sous-io/sous",
-  "version": "0.2.4",
+  "version": "0.2.7",
   "description": "Compiles AI coding agent configuration (CLAUDE.md, skills, memories) from LiquidJS templates",
   "type": "module",
   "license": "Apache-2.0",

package/recipes/core/sous-skills/sous.recipe.yaml

@@ -11,7 +11,7 @@ formatVersion: 1
 
 namespace: core
 name: sous-skills
-version: 0.2.4
+version: 0.2.7
 
 description: >-
   The skills that teach an agent what sous is and how it works: which files sous

package/src/lib/project-install.d.mts

@@ -0,0 +1,40 @@
+/**
+ * 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 const VERBOSE_FLAG: "--verbose";
+
+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[] };
+
+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 formatHandoffNotice(input: {
+  install: Extract<ProjectInstall, { same: false }>;
+  ownVersion: string;
+  ownRoot: string;
+  verbose: boolean;
+}): string[];
+export function planHandoff(input: {
+  cwd: string;
+  ownRoot: string;
+  env: Record<string, string | undefined>;
+  argv?: readonly string[];
+}): HandoffPlan;
+export function handOffToProjectInstall(input: {
+  ownRoot: string;
+  cwd?: string;
+  env?: Record<string, string | undefined>;
+  argv?: readonly string[];
+  stderr?: { write(chunk: string): unknown };
+}): Promise<boolean>;

package/src/lib/project-install.mjs

@@ -0,0 +1,201 @@
+/**
+ * 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. It is
+ *     one line naming the version handed off to; `--verbose` anywhere on the
+ *     command line (or `SOUS_DEBUG`) adds where both installs are and how to
+ *     keep the invoked one running.
+ */
+
+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";
+
+/** The flag that makes the notice say where both installs are. */
+export const VERBOSE_FLAG = "--verbose";
+
+/**
+ * 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 };
+}
+
+/**
+ * The lines the notice is made of: one line naming the version handed off to,
+ * and, when verbose, where both installs are and how to keep the invoked one
+ * running. Plain text, because this prints before tsx exists; the block
+ * mirrors the shape `showVariables` gives a key and value list.
+ */
+export function formatHandoffNotice({ install, ownVersion, ownRoot, verbose }) {
+  const lines = [`Handing off to the project-level Sous install: v${install.version}`];
+  if (verbose) {
+    lines.push(
+      `    Project install: ${install.root}`,
+      `    Invoked install: v${ownVersion} at ${ownRoot}`,
+      `Set ${NO_DELEGATE_ENV}=1 to run the invoked install instead.`
+    );
+  }
+  return lines;
+}
+
+/**
+ * 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 lines to print on stderr first (an empty list when nothing is said).
+ */
+export function planHandoff({ cwd, ownRoot, env, argv = [] }) {
+  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 debug = isEnvFlagOn(env[DEBUG_ENV]);
+  const announce = ownVersion !== install.version || debug;
+  const notice = announce
+    ? formatHandoffNotice({
+        install,
+        ownVersion,
+        ownRoot: realpathOr(ownRoot),
+        verbose: debug || argv.includes(VERBOSE_FLAG),
+      })
+    : [];
+  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,
+  argv = process.argv.slice(2),
+  stderr = process.stderr,
+}) {
+  const plan = planHandoff({ cwd, ownRoot, env, argv });
+  if (plan.kind !== "hand-off") return false;
+  for (const line of plan.notice) stderr.write(`${line}\n`);
+  await import(pathToFileURL(plan.install.bin).href);
+  return true;
+}

package/src/lib/version-report.ts

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