@sous-io/sous 0.2.4 → 0.2.6

package/README.md

@@ -26,12 +26,19 @@ 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 says which copy ran. 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,38 @@
 #!/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;
+  const { execute, settings } = await import("@oclif/core");
 
-// 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()
-);
+  // 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;
 
-await execute({ development: debugRequested, dir: import.meta.url });
+  // 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,37 @@ 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 sentence on standard error names the copy that ran and the
+one you invoked; standard output is untouched, so a piped command prints exactly what it always
+did. Set `SOUS_DEBUG` and the sentence 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
+Running the project's own sous 0.2.4 from /work/app/node_modules/@sous-io/sous instead of the sous 0.3.0 you invoked; set SOUS_NO_DELEGATE=1 to run the one you invoked.
+@sous-io/sous/0.2.4 linux-x64 node-v22.21.0
+$ SOUS_NO_DELEGATE=1 sous --version
+@sous-io/sous/0.3.0 linux-x64 node-v22.21.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

@@ -338,7 +338,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.6",
   "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.6
 
 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,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;
+}