@sous-io/sous 0.1.0 → 0.2.0

package/src/lib/repos/freshness.ts

@@ -0,0 +1,208 @@
+/**
+ * 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;
+}

package/src/lib/repos/git-clone.ts

@@ -0,0 +1,312 @@
+/**
+ * The thin git layer used by `sous repo link`.
+ *
+ * Linking a repository sometimes means cloning it, and always means asking
+ * whether a directory already on disk is the right checkout. Both jobs are done
+ * by shelling out to the user's own `git`, rather than by bundling a git
+ * implementation: the user's credentials, SSH agent, proxy settings and
+ * `insteadOf` rewrites are already configured there, and sous inheriting all of
+ * that for free is worth more than any library.
+ *
+ * Every function takes an optional `runner`, so tests can drive the whole
+ * surface without a real git or a network connection.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { ConfigError } from "../errors.js";
+
+/** What one git invocation produced. */
+export type GitResult = {
+  /** The process exit code, or null when it was killed by a signal. */
+  status: number | null;
+  /** Everything git wrote to standard output, trimmed. */
+  stdout: string;
+  /** Everything git wrote to standard error, trimmed. */
+  stderr: string;
+};
+
+/**
+ * Runs one git command. Swappable so tests never need a real git binary.
+ *
+ * @param args - The arguments passed to git, without the leading "git".
+ * @param options - Where to run it.
+ */
+export type GitRunner = (args: string[], options: { cwd?: string }) => GitResult;
+
+/** Options shared by every function here. */
+export type GitOptions = {
+  /** The git runner to use. Defaults to the real `git` on PATH. */
+  runner?: GitRunner;
+};
+
+/**
+ * The default runner: invokes the real `git` on PATH and captures its output.
+ *
+ * @param args - The arguments passed to git, without the leading "git".
+ * @param options - Where to run it.
+ */
+export const runGit: GitRunner = (args, options = {}) => {
+  const result = spawnSync("git", args, {
+    cwd: options.cwd,
+    encoding: "utf8",
+    // A clone must never stop to ask for a password; a prompt in a
+    // non-interactive run would hang the command with no explanation.
+    env: { ...process.env, GIT_TERMINAL_PROMPT: "0" },
+  });
+
+  if (result.error !== undefined) {
+    const reason = (result.error as NodeJS.ErrnoException).code === "ENOENT"
+      ? "git is not installed, or is not on your PATH"
+      : result.error.message;
+    throw new ConfigError(
+      `Could not run git.\n` +
+        `  ${reason}.\n` +
+        `  sous uses your own git so that your credentials and configuration apply; ` +
+        `install git and try again.`
+    );
+  }
+
+  return {
+    status: result.status,
+    stdout: (result.stdout ?? "").trim(),
+    stderr: (result.stderr ?? "").trim(),
+  };
+};
+
+/** Runs git and throws a ConfigError, carrying git's own message, on failure. */
+function runGitOrThrow(
+  args: string[],
+  options: { cwd?: string; runner?: GitRunner; what: string }
+): GitResult {
+  const runner = options.runner ?? runGit;
+  const result = runner(args, { cwd: options.cwd });
+  if (result.status !== 0) {
+    const detail = result.stderr.length > 0 ? result.stderr : result.stdout;
+    throw new ConfigError(
+      `${options.what} failed.\n` +
+        `  Command: git ${args.join(" ")}\n` +
+        (detail.length > 0 ? `  git said: ${detail}\n` : "") +
+        `  Fix the problem git reported, then run the command again.`
+    );
+  }
+  return result;
+}
+
+/**
+ * True when the directory is inside a git working tree whose root is that same
+ * directory. A subdirectory of a checkout is deliberately not a checkout here:
+ * linking half a repository would silently produce a repo with no manifest at
+ * its root.
+ *
+ * @param directory - The directory to test.
+ * @param options - The git runner to use.
+ */
+export function isGitCheckout(directory: string, options: GitOptions = {}): boolean {
+  if (!directoryExists(directory)) return false;
+
+  const runner = options.runner ?? runGit;
+  const result = runner(["rev-parse", "--show-toplevel"], { cwd: directory });
+  if (result.status !== 0) return false;
+
+  return samePath(result.stdout, directory);
+}
+
+/**
+ * The URL of a checkout's `origin` remote, or undefined when it has none (a
+ * repository created locally with `git init` has no remote until one is added).
+ *
+ * @param directory - The checkout to inspect.
+ * @param options - The git runner to use.
+ */
+export function remoteUrlOf(directory: string, options: GitOptions = {}): string | undefined {
+  const runner = options.runner ?? runGit;
+  const result = runner(["remote", "get-url", "origin"], { cwd: directory });
+  if (result.status !== 0 || result.stdout.length === 0) return undefined;
+  return result.stdout;
+}
+
+/** What a clone actually did. */
+export type CloneResult = {
+  /** The depth git was finally asked for; 0 means the full history. */
+  depth: number;
+  /** True when a shallow clone was refused and the full history was fetched instead. */
+  fellBackToFullClone: boolean;
+};
+
+/**
+ * Clones a repository into a directory that does not yet exist, creating its
+ * parents. A shallow clone is the default for a link, because a linked checkout
+ * exists to be read and edited, not to carry the project's whole history; pass
+ * `depth: 0` to ask for the full history outright.
+ *
+ * Not every remote will serve a shallow clone (`file://` transports and some
+ * servers refuse one), so a failed shallow attempt is retried in full rather
+ * than reported as a failure. The result says whether that happened, so the
+ * caller can tell the user why the clone took longer than they expected.
+ *
+ * @param url - Where the repository lives.
+ * @param destDir - Absolute path the working copy is created at.
+ * @param options - Clone depth and the git runner to use.
+ */
+export function cloneRepo(
+  url: string,
+  destDir: string,
+  options: GitOptions & { depth?: number } = {}
+): CloneResult {
+  if (fs.existsSync(destDir) && !isEmptyDirectory(destDir)) {
+    throw new ConfigError(
+      `Cannot clone into ${destDir}: the directory already exists and is not empty.\n` +
+        `  Move or delete it, or link the checkout that is already there by passing ` +
+        `its path to 'sous repo link'.`
+    );
+  }
+
+  fs.mkdirSync(path.dirname(destDir), { recursive: true });
+
+  const depth = options.depth ?? 1;
+  const runner = options.runner ?? runGit;
+
+  if (depth > 0) {
+    const shallow = runner(["clone", "--depth", String(depth), "--", url, destDir], {});
+    if (shallow.status === 0) return { depth, fellBackToFullClone: false };
+    // git leaves the destination behind on some failures; clear it so the retry
+    // is not refused by its own leftovers.
+    fs.rmSync(destDir, { recursive: true, force: true });
+  }
+
+  runGitOrThrow(["clone", "--", url, destDir], {
+    runner: options.runner,
+    what: `Cloning ${url}`,
+  });
+
+  return { depth: 0, fellBackToFullClone: depth > 0 };
+}
+
+/**
+ * True when two remote URLs name the same repository, ignoring the differences
+ * that never change what is fetched: a `.git` suffix, a trailing slash, the
+ * host's letter case, and SCP-style syntax (`git@host:owner/repo`) against URL
+ * syntax (`https://host/owner/repo`).
+ *
+ * @param a - One remote URL.
+ * @param b - The other remote URL.
+ */
+export function sameRemote(a: string, b: string): boolean {
+  return normalizeRemoteUrl(a) === normalizeRemoteUrl(b);
+}
+
+/**
+ * Reduces a remote URL to `host/path` in lower case, with any `.git` suffix,
+ * trailing slash, scheme, port and user info removed, so two spellings of one
+ * repository compare equal.
+ *
+ * @param url - The remote URL to normalize.
+ */
+export function normalizeRemoteUrl(url: string): string {
+  let value = url.trim();
+
+  // SCP-style syntax, which is not a URL: git@github.com:sous-io/sous.git
+  const scp = /^(?:[^@/]+@)?([^/:]+):(?!\/\/)(.+)$/.exec(value);
+  if (scp !== null) {
+    value = `${scp[1]}/${scp[2]}`;
+  } else {
+    value = value.replace(/^[a-zA-Z][a-zA-Z0-9+.-]*:\/\//, "");
+    // Strip user info (user@ or user:password@) from an authority.
+    value = value.replace(/^[^/]*@/, "");
+    // Strip a port from the host.
+    value = value.replace(/^([^/]+):\d+/, "$1");
+  }
+
+  value = value.replace(/\/+$/, "");
+  value = value.replace(/\.git$/i, "");
+  return value.toLowerCase();
+}
+
+/** A repository's owner and name, as taken from its URL. */
+export type RepoSlug = {
+  /** The owning user or organization, or "repos" when the URL has no owner segment. */
+  owner: string;
+  /** The repository's own name, with any `.git` suffix removed. */
+  name: string;
+};
+
+/**
+ * Splits a remote URL into the owner and name that decide where a default clone
+ * lands (`.sous/repos/<owner>/<name>`). A URL with no owner segment yields the
+ * literal owner "repos", so the layout stays two levels deep whatever the URL
+ * looked like.
+ *
+ * @param url - The remote URL to read.
+ */
+export function repoSlugFromUrl(url: string): RepoSlug {
+  const normalized = normalizeRemoteUrl(url);
+  const segments = normalized.split("/").filter((segment) => segment.length > 0);
+
+  if (segments.length < 2) {
+    throw new ConfigError(
+      `Could not work out an owner and a repository name from the URL '${url}'.\n` +
+        `  A repository URL looks like 'https://github.com/sous-io/sous-recipes'. ` +
+        `Pass a path to 'sous repo link' to link a checkout that is already on disk.`
+    );
+  }
+
+  const name = segments[segments.length - 1]!;
+  const owner = segments.length >= 3 ? segments[segments.length - 2]! : "repos";
+  return { owner: sanitizeSegment(owner), name: sanitizeSegment(name) };
+}
+
+/**
+ * The short name a repository is known by when its URL was given on the command
+ * line rather than configured: the last segment of the URL, with any `.git`
+ * suffix removed.
+ *
+ * @param url - The remote URL to read.
+ */
+export function repoNameFromUrl(url: string): string {
+  return repoSlugFromUrl(url).name;
+}
+
+/**
+ * True when the string looks like something git can clone rather than a short
+ * name: an explicit scheme, SCP-style syntax, or an absolute path.
+ *
+ * @param value - The string to test.
+ */
+export function looksLikeRepoUrl(value: string): boolean {
+  if (value.includes("://")) return true;
+  if (/^[^@/\s]+@[^/\s:]+:/.test(value)) return true;
+  return value.startsWith("/") || value.startsWith("./") || value.startsWith("../");
+}
+
+// --- Small filesystem helpers -------------------------------------------------------------------
+
+/** Replaces anything outside a safe path segment, so a URL can never escape the store. */
+function sanitizeSegment(segment: string): string {
+  const cleaned = segment.replace(/[^A-Za-z0-9._-]+/g, "-").replace(/^\.+/, "");
+  return cleaned.length > 0 ? cleaned : "repo";
+}
+
+/** True when the path exists and is a directory. */
+function directoryExists(candidate: string): boolean {
+  try {
+    return fs.statSync(candidate).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/** True when the path is a directory holding nothing at all. */
+function isEmptyDirectory(candidate: string): boolean {
+  try {
+    return fs.readdirSync(candidate).length === 0;
+  } catch {
+    return false;
+  }
+}
+
+/** Compares two paths after resolving them, so a trailing slash never matters. */
+function samePath(a: string, b: string): boolean {
+  return path.resolve(a) === path.resolve(b);
+}

package/src/lib/repos/identity.ts

@@ -0,0 +1,89 @@
+/**
+ * Canonical repository identity: what the machine-wide store, the index cache
+ * and the lockfile key a repository by.
+ *
+ * A repository's short name (`sous-recipes`) is a CONSUMER's label. Two
+ * projects may call the same repository different things, and two different
+ * repositories may be called the same thing in two projects, so a short name
+ * can never key anything shared between projects. The identity can: it is
+ * derived from the location the repository actually lives at, so every project
+ * on a machine agrees about it.
+ *
+ *     github.com/sous-io/sous-recipes
+ *     gitlab.example.com/group/subgroup/project
+ *     localhost/home/me/Projects/my-recipes
+ *
+ * The shape is `<host>/<owner path>/<name>`, lowercased, with any `.git`
+ * suffix already gone (the providers strip it while canonicalizing). Short
+ * names stay exactly where they were: in a project's config, in its lockfile
+ * keys, and in everything sous prints, because that is what a person typed.
+ */
+
+import type { CanonicalRepo } from "./providers/provider.js";
+import { REPO_NAME_PATTERN } from "./formats/patterns.js";
+
+/**
+ * The canonical identity of a repository, as every machine-wide key spells it.
+ *
+ * repoIdentity({ host: "GitHub.com", owner: "sous-io", name: "sous-recipes" });
+ * // -> "github.com/sous-io/sous-recipes"
+ *
+ * @param canonical - The repository, taken apart by its provider.
+ */
+export function repoIdentity(canonical: CanonicalRepo): string {
+  const name = canonical.name.replace(/\.git$/i, "");
+  return identitySegments(`${canonical.host}/${canonical.owner}/${name}`).join("/");
+}
+
+/**
+ * The path segments an identity is made of, with empty segments dropped and
+ * every segment lowercased. A local repository's owner is an absolute path, so
+ * its leading separator would otherwise produce an empty first segment.
+ *
+ * identitySegments("localhost//home/me/recipes");
+ * // -> ["localhost", "home", "me", "recipes"]
+ *
+ * @param identity - The identity, or the pieces of one joined with slashes.
+ */
+export function identitySegments(identity: string): string[] {
+  return identity
+    .split("/")
+    .map((segment) => segment.trim().toLowerCase())
+    .filter((segment) => segment.length > 0);
+}
+
+/**
+ * A short name derived from an identity, used when sous has to name a
+ * repository a project has never added (a dependency's locator URL, for
+ * instance) before the person has chosen a name for it.
+ *
+ * shortNameFromIdentity("github.com/sous-io/sous-recipes"); // -> "sous-recipes"
+ *
+ * @param identity - The repository's canonical identity.
+ */
+export function shortNameFromIdentity(identity: string): string {
+  const segments = identitySegments(identity);
+  const last = segments[segments.length - 1] ?? "";
+  const cleaned = last
+    .replace(/[^a-z0-9-]+/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-+|-+$/g, "");
+
+  // A short name is lowercase kebab-case starting with a letter. A repository
+  // whose name starts with a digit, or is made entirely of characters a name
+  // may not carry, still needs something to be called.
+  if (REPO_NAME_PATTERN.test(cleaned)) return cleaned;
+  return cleaned.length === 0 ? "repository" : `repo-${cleaned}`;
+}
+
+/**
+ * True when two identities name the same repository. Identities are already
+ * normalized, so this is a plain comparison; it exists so callers read as what
+ * they mean rather than as a string equality.
+ *
+ * @param left - One identity.
+ * @param right - The other.
+ */
+export function sameRepoIdentity(left: string, right: string): boolean {
+  return left === right;
+}

package/src/lib/repos/index.ts

@@ -0,0 +1,58 @@
+/**
+ * The Repositories layer: every on-disk format, the loaders that read them, and
+ * the ref parser that names what is inside them.
+ *
+ * Import from here rather than from the individual modules, so later phases
+ * (the store, the providers, the resolver, the CLI surface) have one place to
+ * look for what this layer offers.
+ */
+
+// The regular expressions in formats/patterns.js reach here through
+// formats/common.js, which re-exports them; listing patterns.js again would
+// make every one of those names an ambiguous star export.
+export * from "./formats/common.js";
+export * from "./formats/repo-manifest.js";
+export * from "./formats/recipe-manifest.js";
+export * from "./formats/index-file.js";
+export * from "./formats/lockfile.js";
+export * from "./formats/store-entry.js";
+export * from "./formats/links-map.js";
+export * from "./load-manifest.js";
+export * from "./ref.js";
+export * from "./identity.js";
+
+// Phase 2a: the machine-wide recipe store, under the user-level sous directory.
+export * from "./store/contract.js";
+export * from "./store/hash.js";
+export * from "./store/recipe-store.js";
+export * from "./store/settings.js";
+
+// Phase 6a: the CLI surface for editable checkouts (`sous repo init`, `link`,
+// `unlink`). The links map and its ignore hygiene, the thin git layer both of
+// them use, and the scaffold that `repo init` writes.
+export * from "./links.js";
+export * from "./git-clone.js";
+export * from "./scaffold/index.js";
+
+// Phase 2b: the store contract, the providers, the resolver, the trust layer
+// and the lockfile service.
+export * from "./providers/index.js";
+export * from "./resolver.js";
+export * from "./managed-layer.js";
+export * from "./trust.js";
+export * from "./lock-service.js";
+export * from "./freshness.js";
+
+// Phase 3: the consumer surface. Where a locked recipe's files are, the
+// namespace resolver and compile targets built from that, and the service the
+// `repo`, `subscribe` and `unsubscribe` commands drive.
+export * from "./locked-recipes.js";
+export * from "./locked-namespace-resolver.js";
+export * from "./subscription-service.js";
+
+// Phase 7: the core namespace. The recipe that ships inside the package, the
+// seed that puts it in the store on first run, and the built-in repository and
+// subscription every project gets unless it opts out.
+export * from "./core-recipe.js";
+export * from "./seed.js";
+export * from "./defaults.js";