@sous-io/sous 0.2.37 → 1.0.2

package/src/utils/prompts.ts

@@ -1,53 +0,0 @@
-import { confirm as inquire, select } from "@inquirer/prompts";
-import { color } from "@oclif/color";
-
-import { blankLine, blankLines, log } from "./formatting.js";
-
-/**
- * Ask a yes or no question and hand back the answer, leaving the decision about
- * what to do with a "no" to the caller. `areYouSure` is the variant that ends
- * the process; use this one where a refusal has to be reported rather than
- * simply obeyed.
- *
- * @param prompt - The question to ask.
- * @param defaultAnswer - What Enter alone means. Defaults to no.
- */
-export async function askYesNo(prompt: string, defaultAnswer = false): Promise<boolean> {
-  blankLine();
-  return inquire({ message: prompt, default: defaultAnswer });
-}
-
-/**
- * Ask the user to pick one of several choices, handing back the value behind
- * the one they picked. The caller decides the order the choices are shown in;
- * this only draws them.
- *
- * Whether a question may be asked at all is not decided here: that is
- * `isInteractive` in `src/lib/interactive.ts`, the one rule every prompt in
- * sous is gated by.
- *
- * @param prompt - The question to ask.
- * @param choices - The options, in the order they should be listed.
- */
-export async function askChoice<T>(
-  prompt: string,
-  choices: Array<{ name: string; value: T }>
-): Promise<T> {
-  blankLine();
-  return select({ message: prompt, choices });
-}
-
-/**
- * Ask the user if they're sure they want to proceed.
- * @param prompt - An optional, custom, prompt to display to the user.
- */
-export async function areYouSure(prompt = "Are you SURE you want to proceed?"): Promise<void> {
-  blankLine();
-  const confirm = await inquire({ message: prompt });
-  if (!confirm) {
-    blankLine();
-    log(color.redBright("Aborting."));
-    blankLines();
-    process.exit(0);
-  }
-}

package/src/utils/sous-directory.ts

@@ -1,245 +0,0 @@
-/**
- * Self-describing directories.
- *
- * Sous creates a handful of directories for its own bookkeeping: the managed
- * config layers, linked checkouts, the machine-wide recipe cache, the user-level
- * sous directory itself. Somebody who finds one of them months later, or an
- * agent reading the repository for the first time, should be able to learn what
- * it is without leaving the directory.
- *
- * So every directory sous creates for itself gets three small files the first
- * time it is created:
- *
- * - `README.md`, a short plain-language explanation of what the directory is,
- *   who writes to it, whether it may be edited or deleted, and whether it is
- *   committed.
- * - `AGENTS.md` and `CLAUDE.md`, each a single line pointing at the README.
- *
- * None of the three is ever overwritten. A user who rewrites the README, or who
- * puts real instructions in `AGENTS.md`, keeps what they wrote forever.
- *
- * Rendered OUTPUT directories are deliberately NOT covered by this: what lands
- * in `.claude/skills/`, in a recipe's output destination, or anywhere else a
- * compilation target writes belongs to the user, and sous does not add files of
- * its own to it.
- */
-
-import fs from "node:fs";
-import path from "node:path";
-import { resolveSousHome } from "../lib/sous-home.js";
-
-/** The three files written into every sous-created directory. */
-export const README_FILENAME = "README.md";
-
-/** Agent instruction file names; both hold the same single pointer line. */
-export const AGENT_POINTER_FILENAMES = ["AGENTS.md", "CLAUDE.md"] as const;
-
-/** The one line both agent instruction files contain. */
-export const AGENT_POINTER_LINE = "Read `./README.md` for information about this directory.";
-
-/** The README text for a sous-created directory. */
-export type SousDirectoryReadme = {
-  /** The heading, naming the directory in plain language. */
-  title: string;
-  /** One or more paragraphs of body text; blank lines are added between them. */
-  body: string | string[];
-};
-
-/** Renders the README body into its final markdown text. */
-function renderReadme(readme: SousDirectoryReadme): string {
-  const paragraphs = Array.isArray(readme.body) ? readme.body : [readme.body];
-  return `# ${readme.title}\n\n${paragraphs.join("\n\n")}\n`;
-}
-
-/**
- * Writes a file only when it does not exist yet. The exclusive write flag makes
- * the check and the write one operation, so two sous processes racing to create
- * the same directory cannot overwrite each other. Any failure is swallowed: a
- * missing explanatory file is never a reason for a command to fail.
- *
- * @param filePath - Absolute path of the file to create.
- * @param contents - What to write when the file is absent.
- */
-function writeIfAbsent(filePath: string, contents: string): void {
-  try {
-    fs.writeFileSync(filePath, contents, { encoding: "utf8", flag: "wx" });
-  } catch {
-    // Already there, or not writable; either way there is nothing to do.
-  }
-}
-
-/**
- * Creates one of sous's own bookkeeping directories and makes it
- * self-describing: `README.md` holding the given explanation, plus `AGENTS.md`
- * and `CLAUDE.md` pointing at it. Files that already exist are left exactly as
- * they are.
- *
- * Safe to call on every command; it is idempotent and cheap.
- *
- * @param directory - Absolute path of the directory to create.
- * @param readme - The explanation written into `README.md` on first creation.
- * @returns The directory path, so calls can be inlined.
- */
-export function ensureSousDirectory(
-  directory: string,
-  readme: SousDirectoryReadme
-): string {
-  fs.mkdirSync(directory, { recursive: true });
-
-  writeIfAbsent(path.join(directory, README_FILENAME), renderReadme(readme));
-  for (const name of AGENT_POINTER_FILENAMES) {
-    writeIfAbsent(path.join(directory, name), `${AGENT_POINTER_LINE}\n`);
-  }
-
-  return directory;
-}
-
-// --- The directories sous creates for itself ----------------------------------------------------
-//
-// Each function below owns the wording for one directory, so every call site is a
-// single line and the same explanation is written no matter which command got
-// there first.
-
-/**
- * Ensures a project's `conf.d/` drop-in layer directory.
- *
- * @param directory - Absolute path to the project's `conf.d/` directory.
- */
-export function ensureConfdDirectory(directory: string): string {
-  return ensureSousDirectory(directory, {
-    title: "conf.d: drop-in configuration layers",
-    body: [
-      "Every `.js`, `.mjs`, `.json`, `.jsonc` or `.yaml` file directly inside this " +
-        "directory is a configuration layer. Sous loads them after the project's main " +
-        "`sous.config.*` file, in filename order, and merges each one over what came " +
-        "before it.",
-      "Layers numbered 500 through 599 are written by sous itself (for example " +
-        "`500-repos.jsonc`, recording the repositories this project trusts). Sous edits " +
-        "those files by key, so your comments, key order and formatting survive; it never " +
-        "touches the main config or any layer outside that band.",
-      "You may add, edit and delete layers here yourself, including the ones sous writes. " +
-        "This directory is normally committed to version control along with the rest of " +
-        "`.sous/`; keep machine-specific paths and secrets out of it and put them in " +
-        "`.sous/.env.local` instead.",
-    ],
-  });
-}
-
-/**
- * Ensures a project's `.sous/repos/` directory of linked checkouts.
- *
- * @param directory - Absolute path to the project's `repos/` directory.
- */
-export function ensureProjectReposDirectory(directory: string): string {
-  return ensureSousDirectory(directory, {
-    title: "repos: linked repository checkouts",
-    body: [
-      "`sous repo link` clones a recipe repository in here so you can work on it and on " +
-        "this project at the same time. Each checkout is an ordinary git working copy; " +
-        "sous reads from it and never writes to it.",
-      "Everything here is machine-local. The `.gitignore` beside this file holds a single " +
-        "`*`, so nothing in this directory (these explanatory files included) is visible " +
-        "to the project's own repository.",
-      "It is safe to delete a checkout once you have run `sous repo unlink` for it; sous " +
-        "goes back to the published version of that repository.",
-    ],
-  });
-}
-
-/**
- * Ensures the user-level sous directory, `$SOUS_HOME` (`~/.sous` by default).
- *
- * @param directory - Absolute path to the user-level sous directory.
- */
-export function ensureSousHomeDirectory(directory: string): string {
-  return ensureSousDirectory(directory, {
-    title: "Your user-level sous directory",
-    body: [
-      "This is `$SOUS_HOME` (`~/.sous` unless you set that variable). It holds the sous " +
-        "state that belongs to this machine rather than to any one project: the recipe " +
-        "cache in `cache/`, globally linked checkouts in `repos/`, and the machine-wide " +
-        "links map `sous.links.json`.",
-      "No project reads its configuration from here, and nothing in here is committed " +
-        "anywhere. Sous recreates whatever it needs, so you can delete any of it; you " +
-        "will lose only cached downloads and the record of which repositories you linked " +
-        "globally.",
-    ],
-  });
-}
-
-/**
- * Explains the parent directory too, but ONLY when it really is the user-level
- * sous directory. A store rooted somewhere else (a test fixture, a root somebody
- * pointed at by hand) must never leave explanatory files in a directory sous
- * does not own, such as the system temporary directory.
- *
- * @param directory - The child directory whose parent is being considered.
- */
-function ensureParentWhenSousHome(directory: string): void {
-  const parent = path.resolve(path.dirname(directory));
-  if (parent !== path.resolve(resolveSousHome())) return;
-  ensureSousHomeDirectory(parent);
-}
-
-/**
- * Ensures the machine-wide recipe store root, `$SOUS_HOME/cache/`.
- *
- * @param directory - Absolute path to the store root.
- */
-export function ensureStoreRootDirectory(directory: string): string {
-  ensureParentWhenSousHome(directory);
-  return ensureSousDirectory(directory, {
-    title: "cache: the machine-wide recipe store",
-    body: [
-      "Sous downloads every recipe version it needs into this directory, one immutable " +
-        "folder per version, and verifies each one against its content hash before using " +
-        "it. Builds read from here, so a version is downloaded once and shared by every " +
-        "project on this machine.",
-      "The store is disposable. Everything in it can be fetched again from the pins in " +
-        "each project's lockfile, so you may delete any part of it at any time; " +
-        "`sous repo gc` does the same thing tidily. Nothing here is committed, and " +
-        "editing a stored file only makes sous discard the entry as corrupted.",
-    ],
-  });
-}
-
-/**
- * Ensures the machine-wide directory of globally linked checkouts,
- * `$SOUS_HOME/repos/`.
- *
- * @param directory - Absolute path to the global repos directory.
- */
-export function ensureGlobalReposDirectory(directory: string): string {
-  ensureParentWhenSousHome(directory);
-  return ensureSousDirectory(directory, {
-    title: "repos: globally linked repository checkouts",
-    body: [
-      "`sous repo link --global` clones a recipe repository in here, where every project " +
-        "on this machine can use the same checkout. Each one is an ordinary git working " +
-        "copy; sous reads from it and never writes to it.",
-      "Everything here is machine-local and is not committed anywhere. It is safe to " +
-        "delete a checkout once no project links to it any more; sous goes back to the " +
-        "published version of that repository.",
-    ],
-  });
-}
-
-/**
- * Ensures the cached repository index directory, `$SOUS_HOME/cache/_indexes/`.
- *
- * @param directory - Absolute path to the index cache directory.
- */
-export function ensureIndexCacheDirectory(directory: string): string {
-  ensureStoreRootDirectory(path.dirname(directory));
-  return ensureSousDirectory(directory, {
-    title: "_indexes: cached repository indexes",
-    body: [
-      "Each repository sous knows about publishes one small index file listing the " +
-        "recipes and versions it offers. Sous keeps a copy of each here, beside a " +
-        "`.meta.json` sidecar recording when that copy was fetched.",
-      "Sous writes these files; there is nothing here to edit. Deleting any of them is " +
-        "safe and costs only a refetch the next time the repository is consulted. Nothing " +
-        "here is committed.",
-    ],
-  });
-}