@sous-io/sous 0.2.36 → 1.0.1

package/src/lib/package-info.ts

@@ -1,25 +0,0 @@
-/**
- * Where this installation of sous lives, and what version it is.
- *
- * These two facts are needed by modules at every level, including ones that
- * `settings.ts` itself imports, so they live in their own dependency-free module
- * rather than in `settings.ts`. `settings.ts` re-exports both under their
- * long-standing names, so nothing else has to care where they moved to.
- */
-
-import fs from "node:fs";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-
-const __filename = fileURLToPath(import.meta.url);
-
-/** Resolved path to the package root (two levels up from `src/lib/`). */
-export const CLI_ROOT = path.resolve(path.dirname(__filename), "../..");
-
-/** Version string read from the package's own package.json at module load time. */
-const packageJson = JSON.parse(
-  fs.readFileSync(path.join(CLI_ROOT, "package.json"), "utf8")
-) as { version: string };
-
-/** The running sous version. */
-export const SOUS_VERSION: string = packageJson.version;

package/src/lib/pid-service.ts

@@ -1,99 +0,0 @@
-import fs from "node:fs";
-import path from "node:path";
-import type { VarScope } from "./settings.js";
-
-/**
- * Manages PID files for the Sous watcher, enforcing a single instance per config.
- * The PID file lives at <sousDir>/sous.pid by default.
- */
-export class PidService {
-  /**
-   * Returns the PID file path for a config.
-   *
-   * Precedence (mirrors StateService.getFilePath):
-   *   1. A `pidFilePath` variable in the settings scope (explicit override).
-   *   2. `<sousDir>/sous.pid`.
-   *   3. `<cwd>/sous.pid` as a last resort.
-   *
-   * @param vars - The resolved settings-scope variables.
-   */
-  getFilePath(vars?: VarScope): string {
-    if (vars?.pidFilePath) {
-      return vars.pidFilePath;
-    }
-    if (vars?.sousDir) {
-      return path.join(vars.sousDir, "sous.pid");
-    }
-    return path.join(process.cwd(), "sous.pid");
-  }
-
-  /**
-   * Checks if a watcher is already running for this config.
-   * - If a PID file exists and the process is alive, throws an Error.
-   * - If a PID file exists but the process is dead (stale), overwrites it.
-   * - If no PID file exists, creates one with the current process.pid.
-   *
-   * @param pidFilePath - Path from getFilePath().
-   * @param label - Human-readable project label used in the "already running"
-   *   error (e.g. `BaseCommand.projectLabel`). Falls back to a label derived
-   *   from the PID file path.
-   */
-  async acquire(pidFilePath: string, label?: string): Promise<void> {
-    if (fs.existsSync(pidFilePath)) {
-      const raw = fs.readFileSync(pidFilePath, "utf8").trim();
-      const existingPid = parseInt(raw, 10);
-
-      if (!isNaN(existingPid)) {
-        const alive = this._isProcessAlive(existingPid);
-        if (alive) {
-          throw new Error(
-            `A watcher is already running for project '${label ?? deriveLabel(pidFilePath)}' (PID ${existingPid}). Stop it first or delete ${pidFilePath}.`
-          );
-        }
-        // Stale PID file — fall through and overwrite
-      }
-    }
-
-    const dir = path.dirname(pidFilePath);
-    if (!fs.existsSync(dir)) {
-      fs.mkdirSync(dir, { recursive: true });
-    }
-    fs.writeFileSync(pidFilePath, String(process.pid), "utf8");
-  }
-
-  /**
-   * Removes the PID file. Called on clean exit.
-   */
-  async release(pidFilePath: string): Promise<void> {
-    if (fs.existsSync(pidFilePath)) {
-      fs.unlinkSync(pidFilePath);
-    }
-  }
-
-  /**
-   * Returns true if the given PID corresponds to a running process.
-   * Uses signal 0 to probe without sending a real signal.
-   */
-  _isProcessAlive(pid: number): boolean {
-    try {
-      process.kill(pid, 0);
-      return true;
-    } catch {
-      return false;
-    }
-  }
-}
-
-/**
- * Derives a project label from a PID file path when the caller supplied none.
- * The default PID file lives at `<project>/.sous/sous.pid`, so a plain
- * `basename(dirname(...))` would always say ".sous"; skip past that directory
- * to the project directory itself.
- */
-function deriveLabel(pidFilePath: string): string {
-  let dir = path.dirname(pidFilePath);
-  if (path.basename(dir) === ".sous") {
-    dir = path.dirname(dir);
-  }
-  return path.basename(dir);
-}

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

@@ -1,44 +0,0 @@
-/**
- * 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 readPackageJson(dir: string): Record<string, unknown> | undefined;
-export function findProjectInstall(startDir: string, ownRoot: string): ProjectInstall | undefined;
-export function findProjectCopy(startDir: string): string | undefined;
-export function realpathOr(p: string): string;
-export function describeInstall(candidate: 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

@@ -1,234 +0,0 @@
-/**
- * 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.
- *   - `sous update` runs the invoked copy: updating the copy that was invoked
- *     is its job, and a project copy may be too old to have the command. The
- *     command word is the first entry on the command line that is not a flag,
- *     so `sous subscription update` still hands off.
- *   - The notice goes to stderr, so piped stdout stays clean. It prints when
- *     the two versions differ, and on every hand-off under `SOUS_DEBUG` or
- *     with `--verbose` anywhere on the command line. Plain, it is one line
- *     naming the version handed off to; verbose (`--verbose` or `SOUS_DEBUG`)
- *     it 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";
-
-/** The command that always runs in the copy that was invoked. */
-export const SELF_UPDATE_COMMAND = "update";
-
-/**
- * The command word on a command line: its first entry that does not start
- * with `-`, or undefined when every entry is a flag.
- *
- * commandWordOf(["--verbose", "update", "--yes"]) -> "update"
- * commandWordOf(["subscription", "update"]) -> "subscription"
- */
-export function commandWordOf(argv) {
-  return argv.find((arg) => !arg.startsWith("-"));
-}
-
-/**
- * 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 the package.json in `dir`, returning the parsed object or undefined
- * for a file that is missing, unreadable or not JSON.
- */
-export 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) {
-  const candidate = findProjectCopy(startDir);
-  return candidate === undefined ? undefined : describeInstall(candidate, ownRoot);
-}
-
-/**
- * Looks up from `startDir` for the nearest `node_modules/@sous-io/sous` that
- * holds a package.json, and returns that path as found, WITHOUT resolving
- * symlinks (pnpm links it into its own store, so only the unresolved path says
- * which project holds it). Undefined when no ancestor holds one.
- */
-export function findProjectCopy(startDir) {
-  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 candidate;
-    const parent = path.dirname(dir);
-    if (parent === dir) return undefined;
-    dir = parent;
-  }
-}
-
-/**
- * The real path of `p`, or `p` resolved when it cannot be read (it does not
- * exist, or a link in it is broken).
- */
-export function realpathOr(p) {
-  try {
-    return fs.realpathSync(p);
-  } catch {
-    return path.resolve(p);
-  }
-}
-
-/**
- * Describes the copy of the package at `candidate` the way `findProjectInstall`
- * does: `{ same: true, root }` when it is `ownRoot`, compared by real path,
- * `{ same: false, root, version, bin }` for a usable other copy, and undefined
- * for one that is not usable.
- */
-export 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" };
-  if (commandWordOf(argv) === SELF_UPDATE_COMMAND) 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 verbose = isEnvFlagOn(env[DEBUG_ENV]) || argv.includes(VERBOSE_FLAG);
-  const announce = ownVersion !== install.version || verbose;
-  const notice = announce
-    ? formatHandoffNotice({ install, ownVersion, ownRoot: realpathOr(ownRoot), verbose })
-    : [];
-  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;
-}