@sous-io/sous 0.1.0 → 0.2.0

package/src/lib/sous-home.ts

@@ -0,0 +1,104 @@
+/**
+ * The user-level sous directory: where machine-wide, project-independent state
+ * lives. Today that is the recipe store, globally linked checkouts and the
+ * machine-wide links map; the user-level config LAYER is a separate effort and
+ * is deliberately NOT read from here.
+ *
+ * The location is `~/.sous`, overridable with the `SOUS_HOME` environment
+ * variable.
+ *
+ * IMPORTANT: `SOUS_HOME` is file-settable. Unlike `SOUS_CONFIG`, `SOUS_DIR` and
+ * `SOUS_CONFD`, which decide which project is active and therefore must come
+ * from the real environment only, `SOUS_HOME` may be set in `.sous/.env.local`
+ * or `.sous/.env`. Every function here reads `process.env` at CALL time for
+ * exactly that reason; never capture the value at import time, because the env
+ * files are loaded after this module is first imported (see `loadEnvFiles` in
+ * `base-command.ts`).
+ */
+
+import os from "node:os";
+import path from "node:path";
+
+/** The directory name used under the user's home directory. */
+export const SOUS_HOME_DIR_NAME = ".sous";
+
+/** The environment variable that overrides the user-level sous directory. */
+export const SOUS_HOME_ENV_VAR = "SOUS_HOME";
+
+/** Subdirectory of the user-level directory holding the recipe store. */
+export const STORE_DIR_NAME = "cache";
+
+/** Subdirectory of the user-level directory holding globally linked checkouts. */
+export const GLOBAL_REPOS_DIR_NAME = "repos";
+
+/** File name of the machine-wide links map. */
+export const GLOBAL_LINKS_FILENAME = "sous.links.json";
+
+/** A read-only view of an environment, so callers can pass a test fixture. */
+export type EnvLike = Record<string, string | undefined>;
+
+/**
+ * Expands a leading `~` in a path, so `SOUS_HOME=~/sous-home` behaves the way a
+ * user typing it into an env file expects. A bare `~` and `~/...` expand; a
+ * `~user/...` form does not (sous has no way to resolve another account's home
+ * directory portably) and is left alone.
+ *
+ * @param value - The raw path, as written by the user.
+ */
+function expandHome(value: string): string {
+  if (value === "~") return os.homedir();
+  if (value.startsWith("~/") || value.startsWith("~\\")) {
+    return path.join(os.homedir(), value.slice(2));
+  }
+  return value;
+}
+
+/**
+ * Resolves the user-level sous directory: `$SOUS_HOME` when it is set to a
+ * non-blank value, otherwise `<home>/.sous`. The result is normalized but is
+ * NOT created; each consumer creates the subdirectory it needs.
+ *
+ * A blank or whitespace-only `SOUS_HOME` is treated as unset rather than as the
+ * current directory, matching how `base-command.ts` treats the other `SOUS_*`
+ * variables.
+ *
+ * @param env - The environment to read; defaults to the live `process.env`.
+ */
+export function resolveSousHome(env: EnvLike = process.env): string {
+  const raw = env[SOUS_HOME_ENV_VAR];
+  if (typeof raw === "string" && raw.trim().length > 0) {
+    return path.normalize(path.resolve(expandHome(raw.trim())));
+  }
+  return path.join(os.homedir(), SOUS_HOME_DIR_NAME);
+}
+
+/**
+ * Resolves the root of the machine-wide recipe store, `$SOUS_HOME/cache`.
+ *
+ * @param env - The environment to read; defaults to the live `process.env`.
+ */
+export function resolveStoreRoot(env: EnvLike = process.env): string {
+  return path.join(resolveSousHome(env), STORE_DIR_NAME);
+}
+
+/**
+ * Resolves the directory holding globally linked checkouts,
+ * `$SOUS_HOME/repos`. A `sous repo link --global` clones into
+ * `<this dir>/<owner>/<repo>`.
+ *
+ * @param env - The environment to read; defaults to the live `process.env`.
+ */
+export function resolveGlobalReposDir(env: EnvLike = process.env): string {
+  return path.join(resolveSousHome(env), GLOBAL_REPOS_DIR_NAME);
+}
+
+/**
+ * Resolves the machine-wide links map, `$SOUS_HOME/sous.links.json`. A
+ * project's own `.sous/sous.links.json` is read alongside it and wins on
+ * conflict.
+ *
+ * @param env - The environment to read; defaults to the live `process.env`.
+ */
+export function resolveGlobalLinksPath(env: EnvLike = process.env): string {
+  return path.join(resolveSousHome(env), GLOBAL_LINKS_FILENAME);
+}

package/src/lib/state.ts

@@ -31,39 +31,56 @@ export type StateFile = {
   files: StateFileEntry[];
 };
 
+// --- Protected paths -----------------------------------------------------------------------------
+
+/**
+ * True when a path is one of the protected roots, or sits underneath one.
+ *
+ * Both sides are normalized and resolved first, so a state file written with a
+ * different spelling of the same directory is still recognised.
+ *
+ * isProtectedPath("/home/me/.sous/cache/r/n/x/1.0.0/a.md", ["/home/me/.sous/cache"]);
+ * // -> true
+ *
+ * @param target - The path something is about to delete.
+ * @param protectedRoots - The directories that must never be reached into.
+ */
+export function isProtectedPath(target: string, protectedRoots: string[]): boolean {
+  if (protectedRoots.length === 0) return false;
+  const candidate = path.resolve(target);
+  return protectedRoots.some((root) => {
+    const resolved = path.resolve(root);
+    return candidate === resolved || candidate.startsWith(resolved + path.sep);
+  });
+}
+
 // --- StateService --------------------------------------------------------------------------------
 
 /**
  * Manages reading and writing the project state file.
  * The state file tracks all files and directories Sous has written,
- * enabling xcv prune and xcv clear to clean up precisely.
+ * enabling sous prune and sous clear to clean up precisely.
  */
 export class StateService {
   /**
-   * Derives the state file path for a project.
+   * Derives the state file path for a config.
    *
    * Precedence:
-   *   1. A `stateFilePath` variable in the PROJECT scope (explicit override).
-   *   2. `<sousDir>/sous.state.json` for a single-project config, or
-   *      `<sousDir>/<key>.sous.state.json` when the config defines several
-   *      projects (they must not share one state file).
-   *   3. `<cwd>/<key>.sous.state.json` as a last resort.
+   *   1. A `stateFilePath` variable in the settings scope (explicit override).
+   *   2. `<sousDir>/sous.state.json`.
+   *   3. `<cwd>/sous.state.json` as a last resort.
    *
-   * @param projectKey - The project's key in the config's `projects` map.
-   * @param projectVars - The resolved PROJECT-scope variables. `sousDir` is
+   * @param vars - The resolved settings-scope variables. `sousDir` is
    *   auto-injected by buildAutoVars when a config has been discovered.
-   * @param projectCount - How many projects the active config defines. Defaults
-   *   to 1 (the expected case: one `.sous/` per project).
    */
-  getFilePath(projectKey: string, projectVars?: VarScope, projectCount = 1): string {
-    if (projectVars?.stateFilePath) {
-      return projectVars.stateFilePath;
+  getFilePath(vars?: VarScope): string {
+    if (vars?.stateFilePath) {
+      return vars.stateFilePath;
     }
-    if (projectVars?.sousDir) {
-      const fileName = projectCount > 1 ? `${projectKey}.sous.state.json` : "sous.state.json";
-      return path.join(projectVars.sousDir, fileName);
+    if (vars?.sousDir) {
+      return path.join(vars.sousDir, "sous.state.json");
     }
-    return path.join(process.cwd(), `${projectKey}.sous.state.json`);
+    return path.join(process.cwd(), "sous.state.json");
   }
 
   /** Loads the state file for a project. Returns null if it does not exist. */
@@ -77,15 +94,30 @@ export class StateService {
     }
   }
 
-  /** Deletes all tracked files and removes any now-empty tracked directories. */
-  deleteTrackedFiles(files: StateFileEntry[], dirs: string[]): void {
+  /**
+   * Deletes all tracked files and removes any now-empty tracked directories.
+   *
+   * @param files - The tracked output files to delete.
+   * @param dirs - The directories Sous created, removed when they end up empty.
+   * @param protectedRoots - Directories nothing here may reach into, whatever the
+   *   state file says. Pass `protectedRepoPaths(sousDir)` so a stale entry can
+   *   never make prune or clear delete a linked checkout or the shared recipe
+   *   store.
+   */
+  deleteTrackedFiles(
+    files: StateFileEntry[],
+    dirs: string[],
+    protectedRoots: string[] = []
+  ): void {
     for (const entry of files) {
+      if (isProtectedPath(entry.dest, protectedRoots)) continue;
       if (fs.existsSync(entry.dest)) fs.rmSync(entry.dest);
     }
     const sortedDirs = [...dirs].sort(
       (a, b) => b.split(path.sep).length - a.split(path.sep).length
     );
     for (const dir of sortedDirs) {
+      if (isProtectedPath(dir, protectedRoots)) continue;
       if (fs.existsSync(dir) && fs.readdirSync(dir).length === 0) {
         fs.rmdirSync(dir);
       }