@sous-io/sous 0.2.6 → 0.2.7

package/README.md

@@ -36,8 +36,9 @@ npm install -D @sous-io/sous     # the version this project's templates were wri
 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.
+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):
 

package/bin/run.js

@@ -20,6 +20,19 @@ if (!handedOff) {
   const { register } = await import("tsx/esm/api");
   register();
 
+  // `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();
+  }
+}
+
+async function runCommand() {
   const { execute, settings } = await import("@oclif/core");
 
   // tsx (above) already makes .ts imports work, so oclif's own auto-transpile

package/docs/markdown/README.md

@@ -34,18 +34,29 @@ Sous installs three ways, and they work together:
   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:
+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
-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
+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
-@sous-io/sous/0.3.0 linux-x64 node-v22.21.0
+v0.3.0
 ```
 
 ## Where to look

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sous-io/sous",
-  "version": "0.2.6",
+  "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.6
+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

@@ -6,6 +6,7 @@
 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 }
@@ -13,19 +14,27 @@ export type ProjectInstall =
 
 export type HandoffPlan =
   | { kind: "run-self" }
-  | { kind: "hand-off"; install: Extract<ProjectInstall, { same: false }>; notice: string | undefined };
+  | { 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

@@ -28,7 +28,10 @@
  *     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.
+ *     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";
@@ -44,6 +47,9 @@ 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).
@@ -129,29 +135,48 @@ function describeInstall(candidate, ownRoot) {
   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 sentence to print on stderr first (undefined when nothing is said).
+ * and the lines to print on stderr first (an empty list when nothing is said).
  */
-export function planHandoff({ cwd, ownRoot, env }) {
+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 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}.`;
-  }
+  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 };
 }
 
@@ -165,11 +190,12 @@ 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 });
+  const plan = planHandoff({ cwd, ownRoot, env, argv });
   if (plan.kind !== "hand-off") return false;
-  if (plan.notice) stderr.write(`${plan.notice}\n`);
+  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));
+}