@sous-io/sous 0.2.36 → 1.0.1

package/src/lib/repos/formats/store-entry.ts

@@ -1,84 +0,0 @@
-/**
- * The store entry marker: `.sous.entry.json`, written beside every cached
- * recipe version in the machine-wide store
- * (`$SOUS_HOME/cache/<repository identity>/<namespace>/<recipe>/<version>/`).
- *
- * The marker is MACHINE-WRITTEN and makes an entry self-describing, so the
- * store can be swept without consulting any project: `hash` is checked against
- * the lockfile before the entry is used, `sizeBytes` and `lastAccessAt` drive
- * the size-capped least-recently-used collection that `sous repo gc` performs.
- *
- * The store is disposable by design; everything in it is re-fetchable from the
- * pins in a project's lockfile.
- */
-
-import { z } from "zod";
-import {
-  byteCountSchema,
-  contentHashSchema,
-  formatVersionSchema,
-  isoTimestampSchema,
-  namespaceNameSchema,
-  parseFormat,
-  recipeNameSchema,
-  repoIdentitySchema,
-  semverVersionSchema,
-  stableJsonStringify,
-} from "./common.js";
-
-/** The store entry marker schema. */
-export const storeEntrySchema = z.strictObject({
-  formatVersion: formatVersionSchema,
-  /**
-   * The canonical identity of the repository the recipe came from, such as
-   * `github.com/sous-io/sous-recipes`. The store is machine-wide, so it records
-   * where a recipe really came from rather than what one project calls it.
-   */
-  repo: repoIdentitySchema,
-  /** The recipe's namespace. */
-  namespace: namespaceNameSchema,
-  /** The recipe's name. */
-  name: recipeNameSchema,
-  /** The exact version cached here. */
-  version: semverVersionSchema,
-  /** Content hash of the cached files, verified before the entry is used. */
-  hash: contentHashSchema,
-  /** When the entry was fetched. */
-  fetchedAt: isoTimestampSchema,
-  /** When the entry was last read by a build. Drives least-recently-used collection. */
-  lastAccessAt: isoTimestampSchema,
-  /** Total size of the entry's files, so the store can be capped without a rescan. */
-  sizeBytes: byteCountSchema,
-});
-
-/** A validated store entry marker. */
-export type StoreEntry = z.infer<typeof storeEntrySchema>;
-
-/**
- * Validates a parsed store entry marker, throwing a ConfigError that names the
- * file and the path of every bad field.
- *
- * @param value - The parsed contents of the marker file.
- * @param sourceLabel - The marker's path, named in error messages.
- */
-export function parseStoreEntry(value: unknown, sourceLabel: string): StoreEntry {
-  return parseFormat(storeEntrySchema, value, sourceLabel, "store entry marker");
-}
-
-/**
- * Serializes a store entry marker for writing, with keys sorted.
- *
- * @param entry - The marker to write.
- */
-export function stringifyStoreEntry(entry: StoreEntry): string {
-  return stableJsonStringify(entry);
-}
-
-/**
- * The recipe key (`namespace/recipe`) a store entry holds.
- *
- * @param entry - A validated store entry marker.
- */
-export function storeEntryKey(entry: StoreEntry): string {
-  return `${entry.namespace}/${entry.name}`;
-}

package/src/lib/repos/formats/variable-definition.ts

@@ -1,268 +0,0 @@
-/**
- * A recipe's variable definitions: what each variable is called, what shape an
- * answer takes, and what question to ask. A recipe manifest declares them
- * (`recipe-manifest.ts` re-exports everything here), and `sous repo release`
- * copies each version's definitions into the index, so the same fields and the
- * same rules read both copies.
- *
- * This module imports nothing but the shared primitives, because the index
- * reads it, and the index sits below the ref parser the manifest needs.
- */
-
-import { z } from "zod";
-import {
-  envVarNameSchema,
-  extensibleObject,
-  forwardCompatibleObject,
-  variableNameSchema,
-} from "./common.js";
-
-// --- Variable definitions -----------------------------------------------------------------------
-
-/** The value types a recipe may declare for a variable. */
-export const VARIABLE_TYPES = [
-  "string",
-  "number",
-  "boolean",
-  "enum",
-  "path",
-  "url",
-] as const;
-
-/** Which env file an answer is written to. */
-export const VARIABLE_SCOPES = ["shared", "local"] as const;
-
-/** Constraints checked against an answer before it is accepted or stored. */
-const variableValidationShape = {
-  /** A regular expression the answer must match, as a string. */
-  pattern: z
-    .string()
-    .refine(
-      (value) => {
-        try {
-          new RegExp(value);
-          return true;
-        } catch {
-          return false;
-        }
-      },
-      { message: "must be a valid regular expression" }
-    )
-    .optional(),
-  /** Minimum length of a string answer. */
-  minLength: z.number().int().min(0).optional(),
-  /** Maximum length of a string answer. */
-  maxLength: z.number().int().min(0).optional(),
-  /** Minimum value of a numeric answer. */
-  min: z.number().optional(),
-  /** Maximum value of a numeric answer. */
-  max: z.number().optional(),
-  /** The allowed answers. Required when the variable's type is 'enum'. */
-  enum: z.array(z.string()).min(1, "must list at least one option").optional(),
-};
-
-/** Constraints checked against an answer before it is accepted or stored. */
-export const variableValidationSchema = extensibleObject(variableValidationShape);
-
-/**
- * The fields of a variable definition, shared by the two schemas that read
- * one: the hand-written manifest, and the copy a release records in the index.
- *
- * @param validate - The schema for the `validate` block, strict or forward compatible.
- */
-function variableDefinitionShape<Validate extends z.ZodType>(validate: Validate) {
-  return {
-    /** The variable's camelCase name, as templates refer to it. */
-    name: variableNameSchema,
-    /**
-     * The environment variable an answer binds to. Authors may name an existing
-     * variable such as GITHUB_TOKEN to reuse a value already in the environment.
-     * When omitted, `sous repo release` derives an upper snake case default from
-     * the name; the runtime never derives one.
-     */
-    env: envVarNameSchema.optional(),
-    /** The answer's type, which decides how it is validated and prompted for. */
-    type: z.enum(VARIABLE_TYPES),
-    /** The one-line question shown when the variable is asked. */
-    prompt: z.string().min(1, "must not be empty"),
-    /**
-     * The paragraph that explains the variable: what it is for, what a good
-     * answer looks like, and what changes when it is set. Shown above the
-     * question when sous asks, and by `sous vars <name>`. Required, because a
-     * consumer reading the question has no other way to learn what a publisher
-     * meant by it.
-     */
-    description: z
-      .string({
-        error:
-          "is required: every published variable must explain itself in a sentence or " +
-          "two. The description is shown above the question when sous asks, and by " +
-          "'sous vars <name>'",
-      })
-      .min(1, "must not be empty"),
-    /**
-     * A realistic sample answer. It is documentation and prompt copy only; sous
-     * never stores it, never offers it as the answer, and never falls back to it.
-     * Use `default` for a value a project should actually start with.
-     */
-    example: z.union([z.string(), z.number(), z.boolean()], {
-      error:
-        "is required: every published variable must show what a real answer looks like. " +
-        "The example is shown with the question and by 'sous vars <name>'; it is " +
-        "documentation only and is never stored as the answer (use 'default' for that)",
-    }),
-    /** The value offered when the question is asked with nothing else in scope. */
-    default: z.union([z.string(), z.number(), z.boolean()]).optional(),
-    /** Whether an answer is needed for a build to run. Defaults to true. */
-    required: z.boolean().default(true),
-    /**
-     * Whether the answer is a secret. A secret is always written to the
-     * gitignored `.sous/.env.local`, never to the committed `.sous/.env`.
-     */
-    secret: z.boolean().default(false),
-    /**
-     * Which env file the answer is written to: 'shared' is `.sous/.env`, which is
-     * committed and shared with the team; 'local' is `.sous/.env.local`, which is
-     * gitignored and machine-specific. Defaults to 'shared'.
-     */
-    scope: z.enum(VARIABLE_SCOPES).default("shared"),
-    /** Constraints checked against an answer. */
-    validate: validate.optional(),
-  };
-}
-
-/** What `checkVariableDefinition` reads from a definition. */
-type CheckedDefinition = {
-  type: VariableType;
-  secret: boolean;
-  scope: VariableScope;
-  default?: string | number | boolean | undefined;
-  example: string | number | boolean;
-  validate?:
-    | { minLength?: number; maxLength?: number; min?: number; max?: number; enum?: string[] }
-    | undefined;
-};
-
-/**
- * The rules a variable definition obeys beyond the shape of each field, shared
- * by both schemas so a definition the index records is held to exactly the rules
- * its manifest was.
- *
- * @param definition - The definition, already parsed field by field.
- * @param ctx - The refinement context issues are added to.
- */
-function checkVariableDefinition(definition: CheckedDefinition, ctx: z.RefinementCtx): void {
-  const { type, validate } = definition;
-
-  if (type === "enum" && (validate?.enum === undefined || validate.enum.length === 0)) {
-    ctx.addIssue({
-      code: "custom",
-      path: ["validate", "enum"],
-      message:
-        "a variable of type 'enum' must list its options under 'validate.enum'",
-    });
-  }
-
-  if (validate !== undefined) {
-    const { minLength, maxLength, min, max } = validate;
-    if (minLength !== undefined && maxLength !== undefined && minLength > maxLength) {
-      ctx.addIssue({
-        code: "custom",
-        path: ["validate", "maxLength"],
-        message: "must not be smaller than 'validate.minLength'",
-      });
-    }
-    if (min !== undefined && max !== undefined && min > max) {
-      ctx.addIssue({
-        code: "custom",
-        path: ["validate", "max"],
-        message: "must not be smaller than 'validate.min'",
-      });
-    }
-  }
-
-  // A secret written to the committed env file would leak, so the two fields
-  // are not allowed to contradict each other.
-  if (definition.secret && definition.scope === "shared") {
-    ctx.addIssue({
-      code: "custom",
-      path: ["scope"],
-      message:
-        "a secret variable is stored in the gitignored '.sous/.env.local', so its " +
-        "scope must be 'local' (or left unset)",
-    });
-  }
-
-  // `default` and `example` are both literal values written by the publisher,
-  // so both have to fit the variable they describe; an example that could
-  // never be a valid answer is worse than no example at all.
-  checkDeclaredValue(definition.default, "default");
-  checkDeclaredValue(definition.example, "example");
-
-  /**
-   * Checks one publisher-written literal against the declared type and the
-   * 'validate.enum' options.
-   *
-   * @param value - The literal to check, or undefined when it was omitted.
-   * @param field - The field name, used as the issue path.
-   */
-  function checkDeclaredValue(
-    value: string | number | boolean | undefined,
-    field: "default" | "example"
-  ): void {
-    if (value === undefined) return;
-
-    const expected =
-      type === "boolean" ? "boolean" : type === "number" ? "number" : "string";
-    if (typeof value !== expected) {
-      ctx.addIssue({
-        code: "custom",
-        path: [field],
-        message: `must be a ${expected}, to match the declared type '${type}'`,
-      });
-    } else if (
-      type === "enum" &&
-      validate?.enum !== undefined &&
-      !validate.enum.includes(String(value))
-    ) {
-      ctx.addIssue({
-        code: "custom",
-        path: [field],
-        message: "must be one of the options listed under 'validate.enum'",
-      });
-    }
-  }
-}
-
-/**
- * A published variable definition: a specification, not a value. Definitions
- * are inert; a question is asked only when a subscribed recipe needs the
- * variable and no valid answer is already in scope.
- */
-export const variableDefinitionSchema = extensibleObject(
-  variableDefinitionShape(variableValidationSchema)
-).superRefine(checkVariableDefinition);
-
-/**
- * A variable definition as a release records it in the index, so a consumer
- * can list a recipe's questions before its files are fetched. It is the
- * manifest's definition, field for field and rule for rule; the one difference
- * is that a field this sous does not define is kept rather than refused,
- * because the index is read by every sous a project happens to pin, and a
- * later one may add a field.
- */
-export const publishedVariableDefinitionSchema = forwardCompatibleObject(
-  variableDefinitionShape(forwardCompatibleObject(variableValidationShape))
-).superRefine(checkVariableDefinition);
-
-/** One validated variable definition from a recipe manifest. */
-export type VariableDefinition = z.infer<typeof variableDefinitionSchema>;
-
-/** The constraints attached to a variable definition. */
-export type VariableValidation = z.infer<typeof variableValidationSchema>;
-
-/** The value type a variable definition declares. */
-export type VariableType = (typeof VARIABLE_TYPES)[number];
-
-/** Which env file an answer is written to. */
-export type VariableScope = (typeof VARIABLE_SCOPES)[number];

package/src/lib/repos/freshness.ts

@@ -1,264 +0,0 @@
-/**
- * Freshness: when sous bothers to look upstream.
- *
- * A build does not want to talk to the network on every run, and a lockfile
- * means it usually has no reason to. So the rule is deliberately dull: a
- * repository is checked when it has never been checked, when the freshness
- * window has lapsed since the last check, or when something asks to always
- * pull. Watch mode passes a shorter window; a one-off command can force it.
- *
- * The last-check time is remembered in the sidecar the index cache already
- * writes, so there is one record per repository rather than two.
- *
- * A failed check NEVER breaks a build. That belongs to the index cache, which
- * falls back to the copy it already holds; this module only decides whether to
- * look.
- */
-
-import semver from "semver";
-import type { IndexFile } from "./formats/index-file.js";
-import type { IndexMeta } from "./providers/index-cache.js";
-
-/** How long a check stays good when nothing says otherwise: five minutes. */
-// The freshness default is shared with the store settings so there is one number.
-import { DEFAULT_FRESHNESS_SECONDS } from "./store/settings.js";
-
-/** The part of the index cache this module uses; IndexCache satisfies it. */
-export type UpstreamCheckRecord = {
-  readMeta(repoName: string): IndexMeta | undefined;
-  writeMeta(repoName: string, meta: IndexMeta): void;
-};
-
-/** What decides whether to look upstream. */
-export type FreshnessInput = {
-  /** When sous last asked upstream, from the repository's sidecar. */
-  lastCheckedAt?: string;
-  /** How long a check stays good, in seconds. Defaults to five minutes. */
-  freshnessSeconds?: number;
-  /**
-   * Whether something in play prefers a newer in-range version over the locked
-   * one. Always-pull still respects the freshness window; it changes what
-   * happens after the check, not how often the check happens.
-   */
-  alwaysPull?: boolean;
-  /** Check regardless, which is what an explicit update command does. */
-  force?: boolean;
-  /** The clock. Defaults to now. */
-  now?: Date;
-};
-
-/**
- * True when sous should ask upstream whether there is anything newer.
- *
- * shouldCheckUpstream({ lastCheckedAt: "2026-01-01T00:00:00.000Z", freshnessSeconds: 300 })
- * // -> false a minute later, true six minutes later
- *
- * @param input - The last check, the window, and the flags.
- */
-export function shouldCheckUpstream(input: FreshnessInput): boolean {
-  if (input.force === true) return true;
-  if (input.lastCheckedAt === undefined) return true;
-
-  const last = Date.parse(input.lastCheckedAt);
-  if (Number.isNaN(last)) return true;
-
-  const now = (input.now ?? new Date()).getTime();
-  const windowSeconds = input.freshnessSeconds ?? DEFAULT_FRESHNESS_SECONDS;
-  if (windowSeconds <= 0) return true;
-
-  const ageSeconds = (now - last) / 1000;
-  // A last-check time in the future means a clock changed under sous; check
-  // rather than trusting an answer that cannot be right.
-  if (ageSeconds < 0) return true;
-  return ageSeconds >= windowSeconds;
-}
-
-/**
- * Records that sous just looked upstream for a repository, whether or not the
- * look succeeded. Recording a failed check too is what stops an unreachable
- * host from being retried on every single build.
- *
- * @param record - The index cache, or anything with its sidecar methods.
- * @param identity - The repository's canonical identity, which the cache is keyed by.
- * @param when - The moment to record. Defaults to now.
- */
-export function recordUpstreamCheck(
-  record: UpstreamCheckRecord,
-  identity: string,
-  when: Date = new Date()
-): IndexMeta {
-  const existing = record.readMeta(identity);
-  const meta: IndexMeta = {
-    fetchedAt: existing?.fetchedAt ?? when.toISOString(),
-    ...(existing?.etag === undefined ? {} : { etag: existing.etag }),
-    ...(existing?.ref === undefined ? {} : { ref: existing.ref }),
-    lastCheckedAt: when.toISOString(),
-  };
-  record.writeMeta(identity, meta);
-  return meta;
-}
-
-/** What an always-pull check found. */
-export type NewerVersion = {
-  /** The recipe key. */
-  key: string;
-  /** The version currently locked. */
-  from: string;
-  /** The newer version that also satisfies the range. */
-  to: string;
-};
-
-/**
- * Finds a newer in-range version of a locked recipe, or undefined when the
- * locked one is still the best the range allows. This is the whole of what
- * always-pull does: it re-resolves WITHIN the declared range and never widens
- * it, so a dependency's constraint still holds.
- *
- * @param options - The index, the recipe, its locked version and its range.
- */
-export function findNewerInRange(options: {
-  /** The repository's index. */
-  index: IndexFile;
-  /** The recipe key, `namespace/recipe`. */
-  key: string;
-  /** The version the lockfile pins. */
-  lockedVersion: string;
-  /** The range the subscription or dependency declared. Defaults to any version. */
-  range?: string;
-  /** Whether prereleases take part. */
-  prerelease?: boolean;
-}): NewerVersion | undefined {
-  const entry = options.index.recipes[options.key];
-  if (entry === undefined) return undefined;
-
-  const prerelease = options.prerelease ?? false;
-  const candidates = Object.keys(entry.versions).filter((version) => {
-    if (!prerelease && entry.versions[version]!.prerelease === true) return false;
-    return semver.satisfies(version, options.range ?? "*", { includePrerelease: prerelease });
-  });
-
-  const best = semver.maxSatisfying(candidates, "*", { includePrerelease: prerelease });
-  if (best === null) return undefined;
-  if (semver.lte(best, options.lockedVersion)) return undefined;
-
-  return { key: options.key, from: options.lockedVersion, to: best };
-}
-
-/** The holder meaning the project subscribed to a recipe itself. */
-const PROJECT = "project";
-
-/** Every range a locked recipe's holders declared, or nothing when one cannot be told. */
-export type DeclaredRangeLookup = {
-  /**
-   * The range the project's subscription declares for a recipe key, `"*"` when
-   * the subscription declares none, or undefined when the project holds nothing
-   * matching it any more.
-   */
-  subscriptionRange(key: string): string | undefined;
-  /**
-   * The range one holding recipe's manifest declares for a dependency, `"*"`
-   * when it declares none, or undefined when its manifest cannot be read or no
-   * longer names that dependency.
-   */
-  dependencyRange(holder: string, key: string): string | undefined;
-};
-
-/**
- * The version range an always-pull check may move ONE locked recipe within, or
- * undefined when sous cannot tell and therefore must not move it at all.
- *
- * Always-pull re-resolves within what was declared; it never widens it. What was
- * declared depends on who holds the recipe. The project's own hold means the
- * subscription's range, which may genuinely be any version. A hold by another
- * recipe means the range that recipe's manifest declared in `depends`, and no
- * subscription anywhere carries it, so falling back to `*` for such an entry
- * would move it straight past the constraint the dependency declared. Several
- * holders mean every one of their ranges at once: whitespace between comparator
- * sets is AND in semver, which is exactly that.
- *
- * Returning undefined is the safe answer, and the entry stays where the lockfile
- * pins it. It happens when a holder's declaration cannot be read and when the
- * combined range is not one semver can express.
- *
- * @param key - The locked recipe key, `namespace/recipe`.
- * @param requestedBy - Its lockfile holders: "project", and any recipe keys.
- * @param lookup - How to read what each holder declared.
- */
-export function effectiveRangeForHolders(
-  key: string,
-  requestedBy: readonly string[],
-  lookup: DeclaredRangeLookup
-): string | undefined {
-  const ranges: string[] = [];
-
-  for (const holder of requestedBy) {
-    const declared =
-      holder === PROJECT ? lookup.subscriptionRange(key) : lookup.dependencyRange(holder, key);
-    if (declared === undefined) return undefined;
-    ranges.push(declared);
-  }
-
-  if (ranges.length === 0) return undefined;
-
-  const constraints = [...new Set(ranges.filter((range) => range !== "*"))];
-  if (constraints.length === 0) return "*";
-
-  const combined = constraints.join(" ");
-  return semver.validRange(combined) === null ? undefined : combined;
-}
-
-/**
- * How long a build waits for a repository that it is only checking so it can
- * say whether a newer version exists: three seconds. Past that the check is
- * abandoned, quietly, and the build goes on with what the cache already knew.
- */
-export const NEWER_VERSION_CHECK_TIMEOUT_MS = 3000;
-
-/**
- * Runs a piece of upstream work with a deadline. The work is handed an abort
- * signal that fires at the deadline, so a request that honors it is cancelled
- * rather than left to keep the process alive; either way the returned promise
- * rejects at the deadline, and the timer never holds the process open itself.
- *
- * await withDeadline((signal) => fetchSomething(signal), 3000);
- * // -> the result, or an error saying the repository did not answer in time
- *
- * @param work - The work to run, given the signal that cancels it.
- * @param milliseconds - How long to wait.
- */
-export async function withDeadline<T>(
-  work: (signal: AbortSignal) => Promise<T>,
-  milliseconds: number
-): Promise<T> {
-  const controller = new AbortController();
-  let timer: ReturnType<typeof setTimeout> | undefined;
-
-  const deadline = new Promise<never>((_, reject) => {
-    timer = setTimeout(() => {
-      controller.abort();
-      reject(
-        new Error(
-          `The repository did not answer within ${formatSeconds(milliseconds)}, so sous ` +
-            `stopped waiting for it.`
-        )
-      );
-    }, milliseconds);
-    timer.unref?.();
-  });
-
-  try {
-    return await Promise.race([work(controller.signal), deadline]);
-  } finally {
-    if (timer !== undefined) clearTimeout(timer);
-  }
-}
-
-/**
- * A duration in plain words, such as "3 seconds" or "1 second".
- *
- * @param milliseconds - The duration.
- */
-function formatSeconds(milliseconds: number): string {
-  const seconds = Math.round((milliseconds / 1000) * 10) / 10;
-  return seconds === 1 ? "1 second" : `${seconds} seconds`;
-}