@sous-io/sous 0.2.37 → 1.0.2

package/src/lib/repos/recipe-targets.ts

@@ -1,236 +0,0 @@
-/**
- * Turning subscribed recipes into compile targets.
- *
- * A recipe's manifest lists what it contributes: skills, memories, prompts and
- * config layers. Only skills are copied into the project, compiled exactly the
- * way a project's own `entryGlob` target is: the recipe's directory is the glob
- * root, the static part of each include pattern is the base the output tree
- * mirrors, and the `.tpl.` convention applies unchanged. Memories reach an agent
- * through include lines, never as copied files, and config layers are loaded
- * rather than written.
- *
- * Two rules decide what is compiled at all:
- *
- *   - Only recipes held through `subscribes` contribute files. A recipe held
- *     only through `depends` is fetched, pinned and addressable from the recipe
- *     that declared it, but its files never enter the project's output; that is
- *     the whole difference between the two dependency kinds.
- *   - Skills go to `recipes.skills.outputs`, which defaults to
- *     `.claude/skills` because that is where every agent looks. Prompts have no
- *     destination yet, so a recipe that publishes them is skipped with ONE
- *     warning naming the `recipes` config key.
- *
- * A recipe's `config` contents are not handled here. They are config layers, and
- * config layers are loaded before any of this runs; see
- * `listRecipeConfigLayers` in `config-discovery.ts`.
- */
-
-import fs from "node:fs";
-import path from "node:path";
-import { globSync } from "glob";
-import type { CompilationTarget } from "../markdown-compiler.js";
-import { inferGlobBase } from "../markdown-compiler.js";
-import { toGlobPattern } from "../glob-pattern.js";
-import type { Settings, VarScope } from "../settings.js";
-import { normalizeConfigPath, substituteVarsStrict } from "../settings.js";
-import type { ContentKind } from "./formats/recipe-manifest.js";
-import {
-  listLockedRecipes,
-  readRecipeManifestIn,
-  type LockedRecipeLocation,
-} from "./locked-recipes.js";
-
-/**
- * The content kinds whose files are copied into a project. `config` is a layer,
- * and `memories` are reached by include lines rather than copied.
- */
-export const WRITABLE_CONTENT_KINDS = ["skills"] as const;
-
-/** One content kind whose files land somewhere in the project. */
-export type WritableContentKind = (typeof WRITABLE_CONTENT_KINDS)[number];
-
-/** How the recipe targets are built. */
-export type RecipeTargetOptions = {
-  /** The project's `.sous/` directory. */
-  sousDir: string;
-  /** The merged project config, read for `recipes.skills.outputs`. */
-  settings: Settings;
-  /** The resolved settings scope, used to substitute `${var}` in destinations. */
-  scope?: VarScope;
-  /**
-   * The scope one recipe's own files render with. A recipe's answers to its own
-   * questions are laid over the project scope there, so a recipe sees its own
-   * answer even when another recipe asks the same name. Defaults to `scope`.
-   */
-  scopeFor?: (recipe: LockedRecipeLocation) => VarScope;
-  /** The environment to read; decides where the store is. */
-  env?: NodeJS.ProcessEnv;
-  /** The locked recipes, when the caller has already located them. */
-  locked?: LockedRecipeLocation[];
-};
-
-/** What the recipe targets add to a build. */
-export type RecipeTargets = {
-  /** One compile target per file a subscribed recipe contributes. */
-  targets: CompilationTarget[];
-  /** Every destination directory the targets write into, for prune's benefit. */
-  destinations: string[];
-  /** Directories a watch should follow: the linked checkouts contributing files. */
-  watchDirs: string[];
-  /** Complete, plain-language sentences a build should print before it compiles. */
-  warnings: string[];
-  /**
-   * Every variable name a recipe declares `secret: true`, which the scope-dumping
-   * template tags hide. Set by the build from the resolved answers.
-   */
-  secretVariables?: string[];
-};
-
-/**
- * The project's root directory: the parent of its `.sous/` directory. Used only
- * for the one destination sous defaults, `.claude/skills`.
- *
- * @param sousDir - The project's `.sous/` directory.
- */
-export function projectRootFor(sousDir: string): string {
-  return path.dirname(path.resolve(sousDir));
-}
-
-/**
- * Where one content kind's files are written, with `${var}` substituted and each
- * path normalized. An empty list means "nowhere configured", which is what makes
- * the caller warn and skip.
- *
- * @param kind - The content kind.
- * @param options - The project's config, scope and `.sous/` directory.
- */
-export function destinationsFor(
-  kind: WritableContentKind,
-  options: RecipeTargetOptions
-): string[] {
-  const configured = options.settings.recipes?.[kind]?.outputs;
-
-  if (configured === undefined || configured.length === 0) {
-    // `.claude/skills` is where every agent looks, so it is worth defaulting.
-    // Nothing else has an obvious home.
-    return kind === "skills"
-      ? [path.join(projectRootFor(options.sousDir), ".claude", "skills")]
-      : [];
-  }
-
-  return configured.map((destination, index) =>
-    normalizeConfigPath(
-      substituteVarsStrict(
-        destination,
-        options.scope ?? {},
-        `recipes.${kind}.outputs[${index}]`
-      )
-    )
-  );
-}
-
-/**
- * Builds the compile targets that the recipes this project subscribes to
- * contribute. Returns an empty result for a project that locks nothing, so a
- * project using no repositories pays nothing for this.
- *
- * @param options - The project's `.sous/` directory, its config and its scope.
- */
-export function buildRecipeTargets(options: RecipeTargetOptions): RecipeTargets {
-  const locked =
-    options.locked ??
-    listLockedRecipes({
-      sousDir: options.sousDir,
-      ...(options.env === undefined ? {} : { env: options.env }),
-    });
-
-  const result: RecipeTargets = {
-    targets: [],
-    destinations: [],
-    watchDirs: [],
-    warnings: [],
-  };
-  if (locked.length === 0) return result;
-
-  const destinationCache = new Map<WritableContentKind, string[]>();
-  let skippedPrompts = false;
-  const destinations = new Set<string>();
-  const watchDirs = new Set<string>();
-
-  for (const recipe of locked) {
-    // Only a co-subscription contributes files; a build dependency is fetched
-    // and addressable, and that is all.
-    if (recipe.kind !== "subscribes") continue;
-    if (!recipe.present) continue;
-
-    const manifest = readRecipeManifestIn(recipe.dir);
-    if (manifest === undefined) continue;
-
-    for (const content of manifest.contents) {
-      const kind = content.kind;
-      if (kind === "prompts") {
-        skippedPrompts = true;
-        continue;
-      }
-      if (!isWritableKind(kind)) continue;
-
-      if (!destinationCache.has(kind)) {
-        destinationCache.set(kind, destinationsFor(kind, options));
-      }
-      const kindDestinations = destinationCache.get(kind)!;
-
-      if (kindDestinations.length === 0) continue;
-
-      for (const destination of kindDestinations) destinations.add(destination);
-      if (recipe.linked) watchDirs.add(recipe.dir);
-
-      const recipeScope = options.scopeFor?.(recipe) ?? options.scope ?? {};
-
-      const ignore = (content.exclude ?? []).map((pattern) =>
-        toGlobPattern(path.join(recipe.dir, pattern))
-      );
-
-      for (const include of content.include) {
-        const pattern = toGlobPattern(path.join(recipe.dir, include));
-        const matched = globSync(pattern, { absolute: true, ignore }).filter(isFile);
-        const globBase = normalizeConfigPath(inferGlobBase(pattern));
-
-        for (const filePath of matched) {
-          result.targets.push({
-            rootInputPath: filePath,
-            globBase,
-            outputs: kindDestinations.map((destination) => ({
-              destinationDir: destination,
-              vars: recipeScope,
-            })),
-          });
-        }
-      }
-    }
-  }
-
-  if (skippedPrompts) {
-    result.warnings.push(
-      `Some subscribed recipes contribute prompts, and the 'recipes' key of your sous ` +
-        `config has no destination for prompts yet, so they were skipped.`
-    );
-  }
-
-  result.destinations = [...destinations].sort();
-  result.watchDirs = [...watchDirs].sort();
-  return result;
-}
-
-/** True when a content kind produces files rather than a config layer. */
-function isWritableKind(kind: ContentKind): kind is WritableContentKind {
-  return (WRITABLE_CONTENT_KINDS as readonly string[]).includes(kind);
-}
-
-/** True when the path is a regular file. */
-function isFile(candidate: string): boolean {
-  try {
-    return fs.statSync(candidate).isFile();
-  } catch {
-    return false;
-  }
-}

package/src/lib/repos/ref-search.ts

@@ -1,46 +0,0 @@
-/**
- * What was searched when a ref matched nothing.
- *
- * Resolving a ref itself lives in `src/services/ref-resolver/`, which every command shares.
- * All that is left here is the one thing only a repository search can say: which
- * repositories were actually looked in, and which were trusted but unreadable,
- * so the reader can tell "the name is wrong" from "the repository holding it
- * was never fetched".
- */
-
-import type { IndexFile } from "./formats/index-file.js";
-
-/** The repositories a ref was searched in, and the indexes that were available. */
-export type IndexSearchInputs = {
-  /** The name that was searched for. */
-  name: string;
-  /** The repositories the search covered, in search order. */
-  repoOrder: string[];
-  /** The cached index of each repository, keyed by short name. */
-  indexes: Map<string, IndexFile>;
-};
-
-/**
- * The lines a name that matched nothing is explained with: every repository
- * whose index was searched, and every trusted repository whose index could not
- * be read.
- *
- * @param inputs - The same inputs the search was given.
- */
-export function describeIndexSearch(inputs: IndexSearchInputs): string[] {
-  const searched = inputs.repoOrder.filter((repo) => inputs.indexes.has(repo));
-  const missing = inputs.repoOrder.filter((repo) => !inputs.indexes.has(repo));
-
-  const lines = [
-    searched.length === 0
-      ? `  No repository index could be read, so there was nothing to search.`
-      : `  Searched the namespaces and the recipe names of: ${searched.join(", ")}.`,
-  ];
-  if (missing.length > 0) {
-    lines.push(
-      `  These repositories are trusted but their index could not be read, so nothing ` +
-        `in them was searched: ${missing.join(", ")}.`
-    );
-  }
-  return lines;
-}

package/src/lib/repos/release/bump.ts

@@ -1,161 +0,0 @@
-/**
- * Raising, or setting, the version in a recipe manifest.
- *
- * A recipe manifest is HAND-WRITTEN, and the scaffold sous writes is mostly
- * comments, so a version bump must give the file back to its author looking the
- * way they left it. Both supported formats are edited in place rather than
- * re-serialized from a parsed object: YAML through the `yaml` package's
- * document model, which keeps comments and layout, and JSON through
- * `jsonc-parser`, which edits the exact byte range of the value and leaves
- * everything else, comments included, untouched.
- */
-
-import fs from "node:fs";
-import path from "node:path";
-import semver from "semver";
-import YAML from "yaml";
-import { applyEdits, modify } from "jsonc-parser";
-import { ConfigError } from "../../errors.js";
-import { parseJsoncText } from "../load-manifest.js";
-
-/** How far a version is being raised. */
-export const BUMP_LEVELS = ["patch", "minor", "major", "prerelease"] as const;
-
-/** One of the ways `sous repo release --bump` can raise a version. */
-export type BumpLevel = (typeof BUMP_LEVELS)[number];
-
-/** What one bump did. */
-export type BumpResult = {
-  /** The manifest that was rewritten. */
-  manifestPath: string;
-  /** The version it declared before. */
-  from: string;
-  /** The version it declares now. */
-  to: string;
-};
-
-/**
- * The version one level up from the current one, using npm's own semantics.
- *
- * @param current - The version the manifest declares now.
- * @param level - How far to raise it.
- */
-export function nextVersion(current: string, level: BumpLevel): string {
-  const next = semver.inc(current, level);
-  if (next === null) {
-    throw new ConfigError(
-      `Cannot raise the version '${current}' by a ${level} step.\n` +
-        `  A recipe version is an exact semantic version, such as '1.4.0' or '2.0.0-beta.1'.`
-    );
-  }
-  return next;
-}
-
-/**
- * Rewrites a recipe manifest's `version` field in place, preserving the rest of
- * the file as written.
- *
- * @param manifestPath - Absolute path to the recipe manifest.
- * @param level - How far to raise the version.
- */
-export function bumpRecipeVersion(manifestPath: string, level: BumpLevel): BumpResult {
-  return rewriteVersion(manifestPath, (current) => nextVersion(current, level));
-}
-
-/**
- * Writes an exact version into a recipe manifest, preserving the rest of the
- * file as written.
- *
- * This is what the release pipeline uses to hold the packaged core recipe at
- * the sous package's own version (see `scripts/sync-core-version.mts`), where
- * the new version is dictated rather than stepped. A manifest that already
- * declares this version is left untouched, byte for byte, so running the sync
- * twice cannot reformat a hand-written file.
- *
- * @param manifestPath - Absolute path to the recipe manifest.
- * @param version - The exact semantic version the manifest should declare.
- */
-export function setRecipeVersion(manifestPath: string, version: string): BumpResult {
-  if (semver.valid(version) === null) {
-    throw new ConfigError(
-      `Cannot set the recipe version to '${version}'.\n` +
-        `  A recipe version is an exact semantic version, such as '1.4.0' or '2.0.0-beta.1'.`
-    );
-  }
-  return rewriteVersion(manifestPath, () => version);
-}
-
-/**
- * The one writer both callers share: read the version the manifest declares,
- * work out what it becomes, and rewrite that value alone.
- *
- * @param manifestPath - Absolute path to the recipe manifest.
- * @param nextFrom - Given the declared version, the version to write.
- */
-function rewriteVersion(
-  manifestPath: string,
-  nextFrom: (current: string) => string
-): BumpResult {
-  const text = fs.readFileSync(manifestPath, "utf8");
-  const extension = path.extname(manifestPath).toLowerCase();
-
-  if (extension === ".json" || extension === ".jsonc") {
-    return rewriteJson(manifestPath, text, nextFrom);
-  }
-  return rewriteYaml(manifestPath, text, nextFrom);
-}
-
-/** Rewrites the version in a YAML manifest, keeping its comments and layout. */
-function rewriteYaml(
-  manifestPath: string,
-  text: string,
-  nextFrom: (current: string) => string
-): BumpResult {
-  const document = YAML.parseDocument(text);
-  const node = document.get("version", true);
-
-  if (!YAML.isScalar(node) || typeof node.value !== "string") {
-    throw missingVersion(manifestPath);
-  }
-
-  const from = node.value;
-  const to = nextFrom(from);
-  if (to === from) return { manifestPath, from, to };
-
-  node.value = to;
-  fs.writeFileSync(manifestPath, document.toString(), "utf8");
-
-  return { manifestPath, from, to };
-}
-
-/** Rewrites the version in a JSON or JSONC manifest, editing only that value's bytes. */
-function rewriteJson(
-  manifestPath: string,
-  text: string,
-  nextFrom: (current: string) => string
-): BumpResult {
-  // The manifest dialect allows comments and trailing commas, so it is read
-  // through the loader's own permissive parser rather than JSON.parse.
-  const parsed = parseJsoncText(text, manifestPath);
-  const from =
-    typeof parsed === "object" && parsed !== null
-      ? (parsed as Record<string, unknown>).version
-      : undefined;
-  if (typeof from !== "string") throw missingVersion(manifestPath);
-
-  const to = nextFrom(from);
-  if (to === from) return { manifestPath, from, to };
-
-  const edits = modify(text, ["version"], to, {});
-  fs.writeFileSync(manifestPath, applyEdits(text, edits), "utf8");
-
-  return { manifestPath, from, to };
-}
-
-/** The error for a manifest with no usable `version` field. */
-function missingVersion(manifestPath: string): ConfigError {
-  return new ConfigError(
-    `The recipe manifest at ${manifestPath} has no 'version' field to write.\n` +
-      `  Every recipe declares an exact semantic version; add one, then try again.`
-  );
-}