@sous-io/sous 0.2.37 → 1.0.1

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

@@ -1,98 +0,0 @@
-/**
- * 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 unless asked
- * to delete one sous cloned.
- *
- * 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 leaves either in place unless
-   * `--remove` is passed, and even then only a 'clone' is ever deleted: a
-   * 'path' checkout belongs to whoever linked it.
-   */
-  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

@@ -1,169 +0,0 @@
-/**
- * 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,
-  DEPENDENCY_KINDS,
-  type DependencyKind,
-} 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: the dependency kinds every format shares. */
-export const LOCK_KINDS = DEPENDENCY_KINDS;
-
-/** 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 = DependencyKind;
-
-/**
- * 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

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

package/src/lib/repos/formats/recipe-manifest.ts

@@ -1,205 +0,0 @@
-/**
- * The recipe manifest: `sous.recipe.yaml` (or `.yml`, or `.json`) in each
- * recipe folder. It is HAND-WRITTEN and is the complete, executable-free
- * description of one publishable unit: what it is called, what version it is,
- * what it depends on, what files it contributes, and what variables it needs
- * answered.
- *
- * Two dependency lists exist, and they mean different things:
- *
- * - `depends` is a build dependency. The target is fetched, pinned and trust
- *   gated, and is addressable from this recipe's own files, but its files do
- *   NOT enter the subscribing project's output.
- * - `subscribes` is a co-subscription. Subscribing to this recipe subscribes
- *   the project to the target too, with full semantics: its questions run and
- *   its files DO enter the output. A curated bundle is simply a recipe made
- *   mostly of `subscribes` entries.
- *
- * Both lists name their targets BY LOCATION:
- *
- *     workflow/sat                                  a sibling in this repository
- *     github://sous-io/sous-recipes/workflow/sat    a recipe in another one
- *
- * Every other location form works too (an HTTPS or SSH URL, a browser URL); a
- * short name such as `sous-recipes:` is a consuming project's own label, so it
- * never appears in a published manifest. See `RefResolverService.parse` with
- * `RefSource.Manifest`.
- */
-
-import { z } from "zod";
-import {
-  extensibleObject,
-  formatVersionSchema,
-  namespaceNameSchema,
-  parseFormat,
-  recipeNameSchema,
-  relativePathSchema,
-  semverVersionSchema,
-  submissionsSchema,
-} from "./common.js";
-import { RefSource, sharedRefResolver } from "../../../services/ref-resolver/index.js";
-import { variableDefinitionSchema } from "./variable-definition.js";
-
-// Variable definitions live in their own module, so the index can read them
-// without importing the ref parser this manifest needs; they are re-exported
-// here because a definition is part of the manifest.
-export * from "./variable-definition.js";
-
-// --- Dependency refs ----------------------------------------------------------------------------
-
-/**
- * A dependency in `depends` or `subscribes`: a bare ref naming a recipe in this
- * same repository, or a location naming one in another repository. Parsed with the real parser so
- * a manifest and the rest of sous never disagree about what a dependency means;
- * the parser's message is carried through as the zod issue message.
- */
-const dependencyRefSchema = z.string().superRefine((value, ctx) => {
-  try {
-    sharedRefResolver().parse(value, RefSource.Manifest);
-  } catch (error) {
-    ctx.addIssue({ code: "custom", message: (error as Error).message });
-  }
-});
-
-/** Builds a list-of-refs schema that also rejects the same target listed twice. */
-function refListSchema(label: string) {
-  return z.array(dependencyRefSchema).superRefine((refs, ctx) => {
-    const seen = new Set<string>();
-    refs.forEach((entry, index) => {
-      const trimmed = entry.trim();
-      if (seen.has(trimmed)) {
-        ctx.addIssue({
-          code: "custom",
-          path: [index],
-          message: `'${trimmed}' is listed more than once in ${label}`,
-        });
-      }
-      seen.add(trimmed);
-    });
-  });
-}
-
-// --- Contents -----------------------------------------------------------------------------------
-
-/**
- * What a content entry contributes. `skills`, `memories` and `prompts` are
- * compiled or copied into the subscribing project's agent directories; `config`
- * entries name config layer files that are merged into the subscriber's config.
- */
-export const CONTENT_KINDS = ["skills", "memories", "prompts", "config"] as const;
-
-/** One group of files this recipe contributes, all of the same kind. */
-export const recipeContentSchema = extensibleObject({
-  /** What the files are, which decides where they land in a subscribing project. */
-  kind: z.enum(CONTENT_KINDS),
-  /** Glob patterns, relative to the recipe folder, naming the files to contribute. */
-  include: z
-    .array(relativePathSchema("an include pattern", true))
-    .min(1, "must list at least one include pattern"),
-  /** Glob patterns, relative to the recipe folder, removed from the include set. */
-  exclude: z.array(relativePathSchema("an exclude pattern", true)).optional(),
-});
-
-// --- The manifest -------------------------------------------------------------------------------
-
-/** The recipe manifest schema. */
-export const recipeManifestSchema = extensibleObject({
-  formatVersion: formatVersionSchema,
-  /** The namespace this recipe belongs to. Must be declared by the repo manifest. */
-  namespace: namespaceNameSchema,
-  /** The recipe's name, unique within its namespace. */
-  name: recipeNameSchema,
-  /**
-   * The published version. Recipe metadata is the source of truth for versions;
-   * a git tag of the shape `namespace/recipe@1.2.3` is a convenience ref that
-   * `sous repo release` keeps consistent with this field.
-   */
-  version: semverVersionSchema,
-  /** One-paragraph summary, shown by `sous repo search` and `sous repo list`. */
-  description: z.string().optional(),
-  /**
-   * Whether this recipe takes proposed changes, winning over the repository's
-   * own `submissions` block. A recipe whose files are copied in from somewhere
-   * else sets `allowed: false` and says where to go instead.
-   */
-  submissions: submissionsSchema.optional(),
-  /**
-   * Build dependencies: fetched and addressable here, but not added to the
-   * project. Each entry is a bare ref naming a sibling recipe in this same
-   * repository, or a locator URL naming a recipe in another one.
-   */
-  depends: refListSchema("'depends'").optional(),
-  /** Co-subscriptions: subscribing here subscribes the project to these too. */
-  subscribes: refListSchema("'subscribes'").optional(),
-  /**
-   * The files this recipe contributes. A curated bundle contributes no files of
-   * its own, so this may be omitted; it then defaults to an empty list.
-   */
-  contents: z.array(recipeContentSchema).default([]),
-  /** Variable definitions this recipe publishes. */
-  variables: z
-    .array(variableDefinitionSchema)
-    .superRefine((definitions, ctx) => {
-      const seenNames = new Set<string>();
-      const seenEnv = new Map<string, number>();
-      definitions.forEach((definition, index) => {
-        if (seenNames.has(definition.name)) {
-          ctx.addIssue({
-            code: "custom",
-            path: [index, "name"],
-            message: `the variable '${definition.name}' is defined more than once`,
-          });
-        }
-        seenNames.add(definition.name);
-
-        if (definition.env !== undefined) {
-          const first = seenEnv.get(definition.env);
-          if (first !== undefined) {
-            ctx.addIssue({
-              code: "custom",
-              path: [index, "env"],
-              message:
-                `the environment variable '${definition.env}' is already claimed by ` +
-                `variables[${first}]; two definitions cannot share one environment variable`,
-            });
-          } else {
-            seenEnv.set(definition.env, index);
-          }
-        }
-      });
-    })
-    .optional(),
-});
-
-/** A validated recipe manifest. */
-export type RecipeManifest = z.infer<typeof recipeManifestSchema>;
-
-/** One validated content group from a recipe manifest. */
-export type RecipeContent = z.infer<typeof recipeContentSchema>;
-
-/** What a content group contributes. */
-export type ContentKind = (typeof CONTENT_KINDS)[number];
-
-/**
- * Validates a parsed recipe manifest, throwing a ConfigError that names the
- * file and the path of every bad field.
- *
- * @param value - The parsed contents of the manifest file.
- * @param sourceLabel - The manifest's file path, named in error messages.
- */
-export function parseRecipeManifest(
-  value: unknown,
-  sourceLabel: string
-): RecipeManifest {
-  return parseFormat(recipeManifestSchema, value, sourceLabel, "recipe manifest");
-}
-
-/**
- * The recipe's key (`namespace/name`), which is how it is stored in an index,
- * a lockfile and a project's subscriptions.
- *
- * @param manifest - A validated recipe manifest.
- */
-export function recipeManifestKey(manifest: RecipeManifest): string {
-  return `${manifest.namespace}/${manifest.name}`;
-}

package/src/lib/repos/formats/repo-manifest.ts

@@ -1,97 +0,0 @@
-/**
- * The repo manifest: `sous.repo.yaml` (or `.yml`, or `.json`) at the root of a
- * repository. It is HAND-WRITTEN by the repo's maintainers and is the entry
- * point sous reads to learn what a repo publishes: its namespaces, and where
- * each recipe folder lives.
- *
- * The manifest is deliberately declarative and executable-free: it is data, so
- * sous can read, validate and browse it before the repository is trusted, in a
- * dry run and in `repo release --check` without executing anything. So
- * manifests are YAML or JSON only.
- */
-
-import { z } from "zod";
-import {
-  extensibleObject,
-  formatVersionSchema,
-  namespaceNameSchema,
-  parseFormat,
-  relativePathSchema,
-  repoNameSchema,
-  submissionsSchema,
-} from "./common.js";
-
-/** A namespace declaration. Namespaces group recipes and are not versioned. */
-export const repoNamespaceSchema = extensibleObject({
-  /** One-line, plain-language summary of what the namespace holds. */
-  description: z.string().optional(),
-});
-
-/** Path to a recipe folder, relative to the repo root. */
-const recipePathSchema = relativePathSchema("a recipe path");
-
-/**
- * The repo manifest schema.
- *
- * `name` is only a SUGGESTED short name. The short name a project actually uses
- * is recorded in its own config by `sous repo add`, which defaults to the last
- * URL segment and can be overridden, so two repos suggesting the same name
- * never collide in a project.
- */
-export const repoManifestSchema = extensibleObject({
-  formatVersion: formatVersionSchema,
-  /** Suggested short name for the repo. */
-  name: repoNameSchema,
-  /** One-paragraph summary of the repo, shown by `sous repo list` and `sous repo search`. */
-  description: z.string().optional(),
-  /**
-   * Where to send a contribution: a URL, or free text describing the process.
-   * Surfaced when a provider does not support `sous repo submit`, so a
-   * contributor is never left without a route.
-   */
-  contribute: z.string().min(1, "must not be empty").optional(),
-  /**
-   * Whether the repository's recipes take proposed changes. A recipe's own
-   * `submissions` block wins over this one. `sous repo submit` warns before
-   * proposing a change to a recipe that does not, and `sous repo release
-   * --check` fails a pull request that changes one.
-   */
-  submissions: submissionsSchema.optional(),
-  /** Every namespace the repo publishes, keyed by namespace name. */
-  namespaces: z.record(namespaceNameSchema, repoNamespaceSchema),
-  /**
-   * Every recipe folder in the repo, as a path relative to the repo root. Each
-   * folder must contain a recipe manifest (`sous.recipe.yaml` or a supported
-   * variant); `sous repo release` verifies that and builds the index from it.
-   */
-  recipes: z.array(recipePathSchema).superRefine((paths, ctx) => {
-    const seen = new Set<string>();
-    paths.forEach((entry, index) => {
-      if (seen.has(entry)) {
-        ctx.addIssue({
-          code: "custom",
-          path: [index],
-          message: `the recipe path '${entry}' is listed more than once`,
-        });
-      }
-      seen.add(entry);
-    });
-  }),
-});
-
-/** A validated repo manifest. */
-export type RepoManifest = z.infer<typeof repoManifestSchema>;
-
-/** A validated namespace declaration from a repo manifest. */
-export type RepoNamespace = z.infer<typeof repoNamespaceSchema>;
-
-/**
- * Validates a parsed repo manifest, throwing a ConfigError that names the file
- * and the path of every bad field.
- *
- * @param value - The parsed contents of the manifest file.
- * @param sourceLabel - The manifest's file path, named in error messages.
- */
-export function parseRepoManifest(value: unknown, sourceLabel: string): RepoManifest {
-  return parseFormat(repoManifestSchema, value, sourceLabel, "repo manifest");
-}