@sous-io/sous 0.1.1 → 0.2.0

package/src/lib/repos/formats/index-file.ts

@@ -0,0 +1,215 @@
+/**
+ * The repo index: `sous.index.json` at a repo's root.
+ *
+ * The index is MACHINE-WRITTEN by `sous repo release` and committed alongside
+ * the recipes it describes. It is the portable contract across providers: every
+ * provider, whatever its API looks like, can hand back this one file, and it is
+ * all sous needs to resolve a ref, enumerate published versions and check
+ * whether a cached copy is current.
+ *
+ * Adding a repo fetches only this file. Nothing else is downloaded until a
+ * project subscribes to something inside it.
+ */
+
+import { z } from "zod";
+import {
+  contentHashSchema,
+  formatVersionSchema,
+  isoTimestampSchema,
+  namespaceNameSchema,
+  parseFormat,
+  recipeKeySchema,
+  relativePathSchema,
+  repoIdentitySchema,
+  repoNameSchema,
+  semverRangeSchema,
+  semverVersionSchema,
+  stableJsonStringify,
+} from "./common.js";
+
+/**
+ * One dependency of one published version, as the release resolved it.
+ *
+ * A SIBLING (a recipe in this same repository) always resolves to an exact
+ * version, because the release that wrote this entry cut that sibling's tag or
+ * found it already cut. A CROSS-REPOSITORY dependency carries the identity of
+ * the repository it lives in, which is what a consumer needs in order to add
+ * that repository and find the recipe in the store; the version it resolves to
+ * belongs to that repository's own index, so this entry carries the range the
+ * manifest declared instead.
+ */
+export const indexDependencySchema = z
+  .strictObject({
+    /** The exact version this dependency resolved to, when the release could resolve one. */
+    version: semverVersionSchema.optional(),
+    /** The range the manifest declared, recorded when no exact version could be resolved. */
+    range: semverRangeSchema.optional(),
+    /**
+     * The canonical identity of the repository publishing it
+     * (`github.com/sous-io/sous-recipes`). Omitted for a sibling, which lives in
+     * this same repository.
+     */
+    repo: repoIdentitySchema.optional(),
+  })
+  .refine(
+    (entry) => entry.version !== undefined || entry.range !== undefined,
+    {
+      message:
+        "must record either the exact version this dependency resolved to or the range " +
+        "the recipe declared",
+    }
+  );
+
+/** One published version of one recipe. */
+export const indexVersionSchema = z.strictObject({
+  /** Content hash of the recipe folder at this version, verified after every fetch. */
+  hash: contentHashSchema,
+  /**
+   * The git tag carrying this version, shaped `namespace/recipe@version`. The
+   * index's `superRefine` checks it against the key and version it sits under,
+   * so a version can never point at a branch or at another recipe's tag.
+   */
+  tag: z.string().min(1, "must not be empty"),
+  /** True when the version is a prerelease, which ranges skip unless opted in. */
+  prerelease: z.boolean(),
+  /**
+   * True when this version is not one the repository published, but the copy of
+   * the recipe that ships inside the installed sous package, folded into the
+   * index in memory so it can be resolved like anything else.
+   *
+   * Sous never writes this onto a copy of an index it fetched; a cached index
+   * stays exactly what upstream served. The field exists so that a listing can
+   * say the version came packaged with sous rather than from the repository, and
+   * so a reader of the stand-in index sous writes for itself can tell.
+   */
+  seeded: z.boolean().optional(),
+  /** When the version was released. */
+  releasedAt: isoTimestampSchema.optional(),
+  /**
+   * What this exact version depends on, resolved at release time and keyed
+   * `namespace/recipe`. A consumer installing this version installs these
+   * versions rather than re-resolving the ranges its manifest declared, so a
+   * published version means one thing forever.
+   *
+   * The field is additive: an index written before it existed still parses, and
+   * a consumer that finds no entry falls back to the manifest's ranges.
+   */
+  dependencies: z.record(recipeKeySchema, indexDependencySchema).optional(),
+});
+
+/** One recipe, with every version the repo publishes of it. */
+export const indexRecipeSchema = z.strictObject({
+  /** The recipe folder, relative to the repo root. */
+  path: relativePathSchema("a recipe path"),
+  /** One-paragraph summary, copied from the recipe manifest at release time. */
+  description: z.string().optional(),
+  /** Every published version, keyed by the exact version string. */
+  versions: z
+    .record(semverVersionSchema, indexVersionSchema)
+    .refine((versions) => Object.keys(versions).length > 0, {
+      message: "must list at least one published version",
+    }),
+});
+
+/** One namespace declaration, copied from the repo manifest at release time. */
+export const indexNamespaceSchema = z.strictObject({
+  description: z.string().optional(),
+});
+
+/** The repo index schema. */
+export const indexFileSchema = z
+  .strictObject({
+    /**
+     * A plain-language note about where this copy of the index came from. JSON
+     * has no comment syntax and an index is machine-written, so this is the one
+     * place a writer can say something to whoever opens the file. Sous ignores
+     * the value everywhere except one place: the seed index it writes for its
+     * own built-in repository carries `SEED_INDEX_COMMENT`, which is how a
+     * later run recognizes its own placeholder and is willing to replace it.
+     */
+    $comment: z.string().optional(),
+    formatVersion: formatVersionSchema,
+    /** The repo's suggested short name, copied from its manifest. */
+    name: repoNameSchema,
+    /** When this index was generated. */
+    generatedAt: isoTimestampSchema,
+    /** The version of sous that generated it. */
+    generator: semverVersionSchema,
+    /** Every namespace the repo publishes. */
+    namespaces: z.record(namespaceNameSchema, indexNamespaceSchema),
+    /** Every recipe the repo publishes, keyed `namespace/recipe`. */
+    recipes: z.record(recipeKeySchema, indexRecipeSchema),
+  })
+  .superRefine((index, ctx) => {
+    // A recipe whose namespace is not declared could never be resolved, so a
+    // release that produced one is broken; say which recipe and which namespace.
+    for (const key of Object.keys(index.recipes)) {
+      const namespace = key.slice(0, key.indexOf("/"));
+      if (!Object.hasOwn(index.namespaces, namespace)) {
+        ctx.addIssue({
+          code: "custom",
+          path: ["recipes", key],
+          message:
+            `belongs to the namespace '${namespace}', which this index does not ` +
+            `declare under 'namespaces'`,
+        });
+      }
+    }
+
+    // A version's tag is what the provider fetches, so a tag that does not
+    // name this exact recipe and version is a version pointing somewhere else.
+    // Nothing on the consumer side could otherwise tell: an index publishing
+    // `1.0.0` with `tag: "main"` would hand `git clone --branch main` a moving
+    // target, whose content changes on every push and whose pinned hash then
+    // simply starts failing. Sous writes these tags itself, so requiring the
+    // shape it writes costs a correct index nothing.
+    for (const [key, recipe] of Object.entries(index.recipes)) {
+      for (const [version, published] of Object.entries(recipe.versions)) {
+        const expected = `${key}@${version}`;
+        if (published.tag === expected) continue;
+        ctx.addIssue({
+          code: "custom",
+          path: ["recipes", key, "versions", version, "tag"],
+          message:
+            `is '${published.tag}', but a published version's tag names the recipe and ` +
+            `the version it carries, so this one must be '${expected}'`,
+        });
+      }
+    }
+  });
+
+/** A validated repo index. */
+export type IndexFile = z.infer<typeof indexFileSchema>;
+
+/** One recipe entry in a repo index. */
+export type IndexRecipe = z.infer<typeof indexRecipeSchema>;
+
+/** One published version entry in a repo index. */
+export type IndexVersion = z.infer<typeof indexVersionSchema>;
+
+/** One resolved dependency of one published version. */
+export type IndexDependency = z.infer<typeof indexDependencySchema>;
+
+/** One namespace entry in a repo index. */
+export type IndexNamespace = z.infer<typeof indexNamespaceSchema>;
+
+/**
+ * Validates a parsed repo index, throwing a ConfigError that names the file and
+ * the path of every bad field.
+ *
+ * @param value - The parsed contents of the index file.
+ * @param sourceLabel - The index's file path or URL, named in error messages.
+ */
+export function parseIndexFile(value: unknown, sourceLabel: string): IndexFile {
+  return parseFormat(indexFileSchema, value, sourceLabel, "repo index");
+}
+
+/**
+ * Serializes a repo index for writing, with every object key sorted so a
+ * regenerated index produces a minimal diff.
+ *
+ * @param index - The index to write.
+ */
+export function stringifyIndexFile(index: IndexFile): string {
+  return stableJsonStringify(index);
+}

package/src/lib/repos/formats/links-map.ts

@@ -0,0 +1,96 @@
+/**
+ * The links map: `sous.links.json`.
+ *
+ * A link redirects a repo's resolution away from the store and at a real
+ * working copy on disk, which is how a maintainer edits recipes: edits happen
+ * in a checkout, never in the store. `sous repo link` writes an entry;
+ * `sous repo unlink` removes it and leaves the checkout in place.
+ *
+ * Two maps are read: the project's `.sous/sous.links.json` and the machine-wide
+ * `$SOUS_HOME/sous.links.json`, with the project map winning on conflict. The
+ * file is MACHINE-WRITTEN and machine-local; it is never committed, because a
+ * link bypasses versions, the lockfile and freshness checks, and those bypasses
+ * belong to one person's machine rather than to the team.
+ */
+
+import { z } from "zod";
+import {
+  absolutePathSchema,
+  formatVersionSchema,
+  isoTimestampSchema,
+  parseFormat,
+  repoNameSchema,
+  stableJsonStringify,
+} from "./common.js";
+
+/** How the linked working copy came to exist. */
+export const LINK_ORIGINS = ["clone", "path"] as const;
+
+/** One linked repo. */
+export const repoLinkSchema = z.strictObject({
+  /** Absolute path to the working copy sous reads instead of the store. */
+  path: absolutePathSchema,
+  /** When the link was created. */
+  linkedAt: isoTimestampSchema,
+  /**
+   * Whether sous cloned the working copy itself ('clone') or was pointed at an
+   * existing checkout ('path'). Unlinking never deletes either, but the origin
+   * tells the user what sous put there.
+   */
+  origin: z.enum(LINK_ORIGINS),
+});
+
+/** The links map schema. */
+export const linksMapSchema = z.strictObject({
+  formatVersion: formatVersionSchema,
+  /** Every linked repo, keyed by the repo's configured short name. */
+  links: z.record(repoNameSchema, repoLinkSchema),
+});
+
+/** A validated links map. */
+export type LinksMap = z.infer<typeof linksMapSchema>;
+
+/** One validated link entry. */
+export type RepoLink = z.infer<typeof repoLinkSchema>;
+
+/** How the linked working copy came to exist. */
+export type LinkOrigin = (typeof LINK_ORIGINS)[number];
+
+/**
+ * Validates a parsed links map, throwing a ConfigError that names the file and
+ * the path of every bad field.
+ *
+ * @param value - The parsed contents of the links file.
+ * @param sourceLabel - The links file's path, named in error messages.
+ */
+export function parseLinksMap(value: unknown, sourceLabel: string): LinksMap {
+  return parseFormat(linksMapSchema, value, sourceLabel, "links map");
+}
+
+/** An empty links map, for a project or machine with nothing linked. */
+export function createEmptyLinksMap(): LinksMap {
+  return { formatVersion: 1, links: {} };
+}
+
+/**
+ * Serializes a links map for writing, with keys sorted.
+ *
+ * @param map - The links map to write.
+ */
+export function stringifyLinksMap(map: LinksMap): string {
+  return stableJsonStringify(map);
+}
+
+/**
+ * Merges a machine-wide links map with a project's, with the project's entries
+ * winning, which is the precedence `sous repo link` documents.
+ *
+ * @param global - The machine-wide map, or undefined when there is none.
+ * @param project - The project's map, or undefined when there is none.
+ */
+export function mergeLinksMaps(
+  global: LinksMap | undefined,
+  project: LinksMap | undefined
+): Record<string, RepoLink> {
+  return { ...(global?.links ?? {}), ...(project?.links ?? {}) };
+}

package/src/lib/repos/formats/lockfile.ts

@@ -0,0 +1,167 @@
+/**
+ * The project lockfile: `.sous/sous.lock.json`, committed to the project.
+ *
+ * The lockfile is MACHINE-WRITTEN and records the exact version and content
+ * hash of everything a project currently uses, so a fresh clone restores
+ * deterministically with no prompts and no version drift. Together with repo
+ * trust it is the supply-chain defense: nothing new enters a project except
+ * through an explicit, visible change to these files.
+ *
+ * A repository appears twice over: the project's own short name is the key of
+ * the `repos` map and is what every recipe entry and every message names, while
+ * the entry's `identity` is what the machine-wide store is keyed by.
+ *
+ * `requestedBy` is what makes removal safe. Every entry lists who holds it, the
+ * literal string `project` for something the project subscribed to directly and
+ * a recipe key for something pulled in as a dependency. Unsubscribing removes
+ * one holder; the entry itself goes only when the last holder does.
+ */
+
+import { z } from "zod";
+import { repoIdentity } from "../identity.js";
+import { requireProvider } from "../providers/index.js";
+import {
+  contentHashSchema,
+  formatVersionSchema,
+  parseFormat,
+  recipeKeySchema,
+  repoIdentitySchema,
+  repoNameSchema,
+  repoUrlSchema,
+  semverVersionSchema,
+  stableJsonStringify,
+} from "./common.js";
+
+/** The literal `requestedBy` holder meaning "the project subscribed to this directly". */
+export const PROJECT_HOLDER = "project";
+
+/** How a locked recipe entered the project. */
+export const LOCK_KINDS = ["subscribes", "depends"] as const;
+
+/** One repo the project resolves against. */
+export const lockedRepoSchema = z
+  .strictObject({
+    /**
+     * Where the repo lives, as recorded when it was added: a URL, or an absolute
+     * path for a repository on this machine read through the `local` provider.
+     */
+    url: repoUrlSchema,
+    /**
+     * The repository's canonical identity, derived from that URL. The keys of
+     * `repos` are the project's own short names, which no other project has to
+     * agree with; this is what the machine-wide store and the index cache file
+     * the repository under, so a restore finds the same cached copy every other
+     * project uses.
+     *
+     * Optional ON READ only, for lockfiles written before the store was keyed by
+     * identity: an entry without one has its identity derived from `url` below,
+     * exactly as the writer would have derived it. Every lockfile sous writes
+     * carries it, so the field fills itself in on the next write.
+     */
+    identity: repoIdentitySchema.optional(),
+    /** Content hash of the index this lock was resolved against, when known. */
+    indexHash: contentHashSchema.optional(),
+  })
+  .transform((entry, ctx) => {
+    if (entry.identity !== undefined) return { ...entry, identity: entry.identity };
+
+    // An older lockfile recorded only the URL. Deriving the identity through the
+    // provider that handles that URL is what the writer itself does, so the
+    // answer is the one the entry would have carried had it been written today.
+    try {
+      const identity = repoIdentity(requireProvider(entry.url).canonicalize(entry.url));
+      return { ...entry, identity };
+    } catch {
+      ctx.addIssue({
+        code: "custom",
+        path: ["identity"],
+        message:
+          `is missing, and sous could not work one out from the url '${entry.url}' ` +
+          `because no provider recognizes it. Add an 'identity' to this entry, or ` +
+          `remove the lockfile and subscribe again to have sous rebuild it.`,
+      });
+      return z.NEVER;
+    }
+  });
+
+/** One locked recipe. */
+export const lockedRecipeSchema = z.strictObject({
+  /** The short name of the repo it came from; must appear under `repos`. */
+  repo: repoNameSchema,
+  /** The exact version resolved. */
+  version: semverVersionSchema,
+  /** Content hash of that version, verified against the store after every fetch. */
+  hash: contentHashSchema,
+  /**
+   * Who holds this entry: `project` for a direct subscription, or the ref key of
+   * a recipe that requires it. Used to refcount removal.
+   */
+  requestedBy: z
+    .array(z.string().min(1, "must not be empty"))
+    .min(1, "must name at least one holder"),
+  /** Whether the holder relationship is a co-subscription or a build dependency. */
+  kind: z.enum(LOCK_KINDS),
+});
+
+/** The lockfile schema. */
+export const lockfileSchema = z
+  .strictObject({
+    formatVersion: formatVersionSchema,
+    /** Every repo the locked recipes came from, keyed by short name. */
+    repos: z.record(repoNameSchema, lockedRepoSchema),
+    /** Every locked recipe, keyed `namespace/recipe`. */
+    recipes: z.record(recipeKeySchema, lockedRecipeSchema),
+  })
+  .superRefine((lock, ctx) => {
+    // A recipe pointing at a repo the lockfile does not describe cannot be
+    // restored, so name the pair rather than failing later at fetch time.
+    for (const [key, entry] of Object.entries(lock.recipes)) {
+      if (!Object.hasOwn(lock.repos, entry.repo)) {
+        ctx.addIssue({
+          code: "custom",
+          path: ["recipes", key, "repo"],
+          message:
+            `names the repo '${entry.repo}', which this lockfile does not describe ` +
+            `under 'repos'`,
+        });
+      }
+    }
+  });
+
+/** A validated lockfile. */
+export type Lockfile = z.infer<typeof lockfileSchema>;
+
+/** One locked repo entry. */
+export type LockedRepo = z.infer<typeof lockedRepoSchema>;
+
+/** One locked recipe entry. */
+export type LockedRecipe = z.infer<typeof lockedRecipeSchema>;
+
+/** How a locked recipe entered the project. */
+export type LockKind = (typeof LOCK_KINDS)[number];
+
+/**
+ * Validates a parsed lockfile, throwing a ConfigError that names the file and
+ * the path of every bad field.
+ *
+ * @param value - The parsed contents of the lockfile.
+ * @param sourceLabel - The lockfile's path, named in error messages.
+ */
+export function parseLockfile(value: unknown, sourceLabel: string): Lockfile {
+  return parseFormat(lockfileSchema, value, sourceLabel, "lockfile");
+}
+
+/** An empty lockfile, for a project that has locked nothing yet. */
+export function createEmptyLockfile(): Lockfile {
+  return { formatVersion: 1, repos: {}, recipes: {} };
+}
+
+/**
+ * Serializes a lockfile for writing, with every object key sorted so the
+ * committed file changes only when its content genuinely does.
+ *
+ * @param lockfile - The lockfile to write.
+ */
+export function stringifyLockfile(lockfile: Lockfile): string {
+  return stableJsonStringify(lockfile);
+}

package/src/lib/repos/formats/patterns.ts

@@ -0,0 +1,57 @@
+/**
+ * Dependency-free regular expressions shared by the Repositories on-disk
+ * formats, the ref parser and the sous config schema.
+ *
+ * This module deliberately imports nothing, so `config-schema.ts` can reuse the
+ * patterns without pulling in zod schemas, semver, or the rest of the repos
+ * layer. `formats/common.ts` re-exports everything here.
+ */
+
+/**
+ * Lowercase kebab-case identifier: starts with a letter, then letters, digits
+ * or hyphens. Used for repo short names, namespace names and recipe names
+ * (`sous-recipes`, `tool-usage`, `automated-browser-tasks`).
+ */
+export const KEBAB_NAME_PATTERN = /^[a-z][a-z0-9-]*$/;
+
+/** A repo's configured short name, as used by the `repo:` ref qualifier. */
+export const REPO_NAME_PATTERN = KEBAB_NAME_PATTERN;
+
+/** A namespace name. */
+export const NAMESPACE_NAME_PATTERN = KEBAB_NAME_PATTERN;
+
+/** A recipe name, unique within its namespace. */
+export const RECIPE_NAME_PATTERN = KEBAB_NAME_PATTERN;
+
+/**
+ * A ref key: either a bare namespace (`workflow`) or a fully qualified recipe
+ * (`workflow/task-files`). Never carries a repo qualifier or a version range.
+ */
+export const REF_KEY_PATTERN = /^[a-z][a-z0-9-]*(\/[a-z][a-z0-9-]*)?$/;
+
+/** A recipe key, which always has both segments (`workflow/task-files`). */
+export const RECIPE_KEY_PATTERN = /^[a-z][a-z0-9-]*\/[a-z][a-z0-9-]*$/;
+
+/**
+ * A repository's canonical identity: the host, then the path it lives at, all
+ * lowercase (`github.com/sous-io/sous-recipes`). It is what every machine-wide
+ * key uses, because a project's short name for a repository is its own label
+ * and no other project has to agree with it.
+ */
+export const REPO_IDENTITY_PATTERN = /^[^\s/]+(\/[^\s/]+)+$/;
+
+/** A content hash, written as the algorithm name followed by lowercase hex. */
+export const CONTENT_HASH_PATTERN = /^sha256-[0-9a-f]{64}$/;
+
+/** An environment variable name, as declared by a recipe variable definition. */
+export const ENV_VAR_NAME_PATTERN = /^[A-Z][A-Z0-9_]*$/;
+
+/** A camelCase variable name, as declared by a recipe variable definition. */
+export const VARIABLE_NAME_PATTERN = /^[a-z][a-zA-Z0-9]*$/;
+
+/**
+ * An ISO 8601 timestamp carrying an explicit offset (`Z` or `+hh:mm`). Machine
+ * written timestamps come from `new Date().toISOString()`, which matches.
+ */
+export const ISO_TIMESTAMP_PATTERN =
+  /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,9})?(Z|[+-]\d{2}:\d{2})$/;