create-next-hydra 0.2.0 → 0.3.0

package/README.md

@@ -57,10 +57,12 @@ Keep source in its normal package or application directory and place a `registry
 A Selection Definition declares:
 
 - its stable ID and whether it is a Provider, Add-on, or Preset;
-- a Provider Slot when it is a Provider;
+- a Provider Slot and one package `binding` when it is a Provider;
+- an optional `binding.sourcePath` for resolving a maintained Provider directly to workspace source;
+- `providerDependencies` for packages contributed by the selection that consume a Provider Slot;
 - standard ShadCN `registryDependencies` for any other registry items it needs;
 - required and conflicting selection IDs;
-- exact package entries and aliases;
+- ordinary exact package entries;
 - exact pnpm patch entries and their patch-file assets; and
 - setup instructions through the registry item's standard `docs` field.
 
@@ -77,7 +79,36 @@ pnpm registry:check
 
 `registry:sync` regenerates only each registry item's `files` list and its final workspace-root targets. Provider-owned metadata stays in the colocated registry file. Next Hydra first walks the intact `registryDependencies` graph to retain metadata and detect target conflicts, then prepares those exact artifacts and asks ShadCN to install them once from the workspace root.
 
-Standard ShadCN `dependencies` and `devDependencies` apply to the workspace root. Use `meta.nextHydra.packages` only when a dependency must be added to a specific workspace package.
+Standard ShadCN `dependencies` and `devDependencies` apply to the workspace root. Use `meta.nextHydra.packages` only when an ordinary dependency must be added to a specific workspace package. Stable Provider aliases are derived from the slot and cannot be declared in `packages`.
+
+A Provider declares its installable package once:
+
+```json
+{
+  "kind": "provider",
+  "slot": "cms",
+  "binding": {
+    "specifier": "npm:@vendor/cms-provider@^1.0.0"
+  }
+}
+```
+
+An Add-on that contributes a package which imports the selected CMS declares the consumer, not a concrete CMS package:
+
+```json
+{
+  "kind": "add-on",
+  "providerDependencies": [
+    {
+      "cwd": "packages/vendor-search",
+      "section": "dependencies",
+      "slot": "cms"
+    }
+  ]
+}
+```
+
+Scaffold and maintainer `use` resolve that dependency to `@repo/cms` using the selected Provider's `binding.specifier`. If the Provider also declares `binding.sourcePath`, they write the exact alias and its `/*` wildcard into every selected consumer's `tsconfig.json` for direct-source development. Without `sourcePath`, pnpm's installed alias is the only resolution path and Next Hydra writes no TypeScript path override. Catalog-governed overrides are removed when they are no longer selected, and `use --check` reports incorrect or stale paths. Customer `add`, which has no retained selection receipt, copies the exact Provider alias already present in `apps/web/package.json` into each contributed consumer.
 
 ShadCN reads registry source files as text. For a binary file that must survive byte-for-byte, or a root patch file referenced by `pnpmPatches`, an official or locally included source-registry selection may declare a typed `assets` source and target instead. Separately fetched external selections cannot contribute assets in v1.
 

package/dist/composition/add.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"add.d.ts","sourceRoot":"","sources":["../../src/composition/add.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,OAAO,EAAY,MAAM,gBAAgB,CAAC;AA4BnD,MAAM,MAAM,UAAU,GAAG;IACvB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,GAAG,CAAC,EAAE,OAAO,CAAC;CACf,CAAC;AAEF,KAAK,aAAa,GAAG,CACnB,OAAO,EAAE,UAAU,CAAC,OAAO,OAAO,CAAC,CAAC,CAAC,CAAC,KACnC,UAAU,CAAC,OAAO,OAAO,CAAC,CAAC;AAEhC,MAAM,MAAM,eAAe,GAAG;IAC5B,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1C,CAAC;AAufF,wBAAsB,eAAe,CACnC,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,UAAe,EACxB,YAAY,GAAE,eAAoB,GACjC,OAAO,CAAC,IAAI,CAAC,CAuKf"}
+{"version":3,"file":"add.d.ts","sourceRoot":"","sources":["../../src/composition/add.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,OAAO,EAAY,MAAM,gBAAgB,CAAC;AA6BnD,MAAM,MAAM,UAAU,GAAG;IACvB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,GAAG,CAAC,EAAE,OAAO,CAAC;CACf,CAAC;AAEF,KAAK,aAAa,GAAG,CACnB,OAAO,EAAE,UAAU,CAAC,OAAO,OAAO,CAAC,CAAC,CAAC,CAAC,KACnC,UAAU,CAAC,OAAO,OAAO,CAAC,CAAC;AAEhC,MAAM,MAAM,eAAe,GAAG;IAC5B,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1C,CAAC;AAihBF,wBAAsB,eAAe,CACnC,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,UAAe,EACxB,YAAY,GAAE,eAAoB,GACjC,OAAO,CAAC,IAAI,CAAC,CAiMf"}

package/dist/composition/add.js

@@ -13,9 +13,12 @@ import { resolveRegistryTarget } from "./paths.js";
 import { formatZodError, NEXT_HYDRA_SELECTION_SCHEMA_URL, selectionDefinitionSchema, } from "./schema.js";
 import { PROVIDER_ALIASES } from "./types.js";
 import { applyPackageEntries } from "./workspace.js";
-const PACKAGE_ALIAS_PROTOCOL = /^(?:workspace|npm):/;
 const EXACT_COPY_FILE_TYPES = new Set(["registry:file", "registry:item"]);
 const KNOWN_PROVIDERS = new Map([
+    [
+        "next-hydra/auth/clerk",
+        { dependency: "@repo/auth", packageName: "@repo/auth-clerk" },
+    ],
     [
         "next-hydra/auth/workos",
         { dependency: "@repo/auth", packageName: "@repo/auth-workos" },
@@ -171,36 +174,25 @@ function usesProviderAlias(actual, packageName) {
         actual.startsWith(`workspace:${packageName}@`) ||
         actual.startsWith(`npm:${packageName}@`));
 }
-function aliasedPackageName(specifier) {
-    const request = specifier.replace(PACKAGE_ALIAS_PROTOCOL, "");
-    const packageEnd = request.startsWith("@")
-        ? request.indexOf("@", request.indexOf("/") + 1)
-        : request.indexOf("@");
-    return packageEnd < 1 ? request || undefined : request.slice(0, packageEnd);
-}
 function providerExpectation(selectionId, selectionsById) {
-    const known = KNOWN_PROVIDERS.get(selectionId);
-    if (known) {
-        return known;
-    }
     const selection = selectionsById.get(selectionId);
-    if (selection?.kind !== "provider" || !selection.slot) {
-        return;
+    if (selection?.kind === "provider" && selection.slot && selection.binding) {
+        return {
+            dependency: PROVIDER_ALIASES[selection.slot],
+            specifier: selection.binding.specifier,
+        };
     }
-    const dependency = PROVIDER_ALIASES[selection.slot];
-    const requirement = selection.packages.find((candidate) => candidate.cwd === "apps/web" &&
-        candidate.section === "dependencies" &&
-        candidate.name === dependency);
-    const packageName = requirement
-        ? aliasedPackageName(requirement.specifier)
-        : undefined;
-    return packageName ? { dependency, packageName } : undefined;
+    return KNOWN_PROVIDERS.get(selectionId);
 }
-async function validateKnownProviderCompatibility(workspaceRoot, selections) {
+function matchesProviderExpectation(actual, expectation) {
+    return "specifier" in expectation
+        ? actual === expectation.specifier
+        : usesProviderAlias(actual, expectation.packageName);
+}
+function validateKnownProviderCompatibility(manifest, selections) {
     if (selections.length === 0) {
         return [];
     }
-    const manifest = await readPackageJson(path.join(workspaceRoot, "apps/web/package.json"), "apps/web/package.json");
     const issues = [];
     const assumptions = [];
     const selectionsById = new Map(selections.map((item) => [item.id, item]));
@@ -210,11 +202,11 @@ async function validateKnownProviderCompatibility(workspaceRoot, selections) {
         }
         const provider = providerExpectation(selection.id, selectionsById);
         if (!provider) {
-            issues.push(`${selection.id} is a Provider in the requested graph but does not declare its apps/web stable alias`);
+            issues.push(`${selection.id} is a Provider in the requested graph but does not declare a usable Provider binding`);
             continue;
         }
         const actual = manifest.dependencies?.[provider.dependency];
-        if (!usesProviderAlias(actual, provider.packageName)) {
+        if (!matchesProviderExpectation(actual, provider)) {
             issues.push(`${selection.id} is a Provider in the requested graph, but the current provider alias ${provider.dependency} is ${actual ?? "missing"}`);
         }
     }
@@ -223,7 +215,7 @@ async function validateKnownProviderCompatibility(workspaceRoot, selections) {
             const provider = providerExpectation(required, selectionsById);
             const requiredSelection = selectionsById.get(required);
             if (provider &&
-                !usesProviderAlias(manifest.dependencies?.[provider.dependency], provider.packageName)) {
+                !matchesProviderExpectation(manifest.dependencies?.[provider.dependency], provider)) {
                 issues.push(`${selection.id} requires ${required}`);
             }
             else if (!(provider || requiredSelection?.kind === "add-on")) {
@@ -234,7 +226,7 @@ async function validateKnownProviderCompatibility(workspaceRoot, selections) {
             const provider = providerExpectation(conflict, selectionsById);
             const conflictingSelection = selectionsById.get(conflict);
             if ((provider &&
-                usesProviderAlias(manifest.dependencies?.[provider.dependency], provider.packageName)) ||
+                matchesProviderExpectation(manifest.dependencies?.[provider.dependency], provider)) ||
                 conflictingSelection?.kind === "add-on") {
                 issues.push(`${selection.id} conflicts with ${conflict}`);
             }
@@ -248,6 +240,30 @@ async function validateKnownProviderCompatibility(workspaceRoot, selections) {
     }
     return [...new Set(assumptions)].sort((left, right) => left.localeCompare(right));
 }
+function resolveCustomerProviderRequirements(manifest, selections) {
+    const requirements = [];
+    const issues = [];
+    for (const selection of selections) {
+        for (const dependency of selection.providerDependencies) {
+            const name = PROVIDER_ALIASES[dependency.slot];
+            const specifier = manifest.dependencies?.[name];
+            if (!specifier) {
+                issues.push(`${selection.id} needs the ${dependency.slot} Provider at ${dependency.cwd}, but apps/web/package.json does not declare ${name}`);
+                continue;
+            }
+            requirements.push({
+                cwd: dependency.cwd,
+                name,
+                section: dependency.section,
+                specifier,
+            });
+        }
+    }
+    if (issues.length > 0) {
+        throw new CompositionValidationError("The Add-on's Provider dependencies could not be resolved from the customer workspace.", issues);
+    }
+    return requirements;
+}
 function validateRegistryTargetClaims(items) {
     const claims = new Map();
     const issues = [];
@@ -360,9 +376,7 @@ export async function addRegistryItem(reference, options = {}, dependencies = {}
         references: [resolvedReference],
     });
     const primaryName = graph.itemByReference.get(resolvedReference);
-    const primary = primaryName
-        ? graph.items.get(primaryName)
-        : undefined;
+    const primary = primaryName ? graph.items.get(primaryName) : undefined;
     if (!primary) {
         throw new Error(`The registry returned no item for ${reference}.`);
     }
@@ -390,8 +404,25 @@ export async function addRegistryItem(reference, options = {}, dependencies = {}
     if (patchSelections.length > 0) {
         throw new CompositionValidationError("Customer Add-ons cannot change pnpm patches in v1.", patchSelections.map((candidate) => `${candidate.id} must avoid pnpmPatches or be selected during a new scaffold`));
     }
-    const compatibilityAssumptions = await validateKnownProviderCompatibility(cwd, graphSelections);
     validateRegistryTargetClaims(graph.items.values());
+    const providerSelectionIds = new Set(graphSelections
+        .filter((candidate) => candidate.kind === "provider")
+        .map((candidate) => candidate.id));
+    const needsProviderManifest = graphSelections.some((candidate) => candidate.kind === "provider" ||
+        candidate.providerDependencies.length > 0 ||
+        [
+            ...candidate.compatibility.requires,
+            ...candidate.compatibility.conflicts,
+        ].some((selectionId) => KNOWN_PROVIDERS.has(selectionId) ||
+            providerSelectionIds.has(selectionId)));
+    const providerManifest = needsProviderManifest
+        ? await readPackageJson(path.join(cwd, "apps/web/package.json"), "apps/web/package.json")
+        : {};
+    const compatibilityAssumptions = validateKnownProviderCompatibility(providerManifest, graphSelections);
+    const packageRequirements = mergePackageRequirements([
+        ...graphSelections.flatMap((candidate) => candidate.packages),
+        ...resolveCustomerProviderRequirements(providerManifest, graphSelections),
+    ]);
     await withPreparedRegistryArtifacts({
         artifacts: [...graph.items.values()],
         entryItems: [primary.name],
@@ -402,7 +433,7 @@ export async function addRegistryItem(reference, options = {}, dependencies = {}
                 throw new Error(`The registry dependency graph for ${reference} is empty.`);
             }
             const fileChanges = await inspectFiles(cwd, tree);
-            const packageChanges = await inspectPackages(cwd, mergePackageRequirements(graphSelections), tree);
+            const packageChanges = await inspectPackages(cwd, packageRequirements, tree);
             const rootDependencyChanges = await inspectRootDependencies(cwd, tree);
             const disclosedPackageChanges = [
                 ...packageChanges,

package/dist/composition/catalog.d.ts

@@ -17,7 +17,10 @@ export declare function fetchRegistryItemGraph(options: {
     repository?: string;
 }): Promise<RegistryItemGraph>;
 export declare function loadSourceRegistryCatalog(cwd: string, registryFile?: string): Promise<SourceRegistryCatalog>;
-export declare function loadGitHubSourceRegistryCatalog(repository: string, ref?: string): Promise<SourceRegistryCatalog>;
+export declare function loadGitHubSourceRegistryCatalog(repository: string, ref?: string, dependencies?: {
+    fetchItems?: (addresses: string[]) => RegistryItem[] | Promise<RegistryItem[]>;
+    loadRegistryConfig?: (cwd: string) => RegistriesConfig | Promise<RegistriesConfig>;
+}): Promise<SourceRegistryCatalog>;
 export declare function addCatalogReferences(catalog: SourceRegistryCatalog, references: Iterable<string>, cwd?: string): Promise<SourceRegistryCatalog>;
 export declare function resolveCatalogSelection(catalog: SourceRegistryCatalog, reference: string): CatalogSelection;
 //# sourceMappingURL=catalog.d.ts.map

package/dist/composition/catalog.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../../src/composition/catalog.ts"],"names":[],"mappings":"AAIA,OAAO,EAEL,gBAAgB,EAEjB,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAclD,OAAO,KAAK,EACV,gBAAgB,EAChB,gBAAgB,EAChB,qBAAqB,EACtB,MAAM,YAAY,CAAC;AA4JpB,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,qBAAqB,EAC9B,UAAU,EAAE,MAAM,EAAE,GACnB,MAAM,EAAE,CA+BV;AAaD,MAAM,MAAM,iBAAiB,GAAG;IAC9B,gBAAgB,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC9B,eAAe,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;CAClC,CAAC;AAEF,wBAAsB,sBAAsB,CAAC,OAAO,EAAE;IACpD,MAAM,EAAE,gBAAgB,CAAC;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,CAAC,EAAE,OAAO,gBAAgB,CAAC;IACrC,eAAe,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,KAAK,CAAC,EAAE,QAAQ,CAAC,YAAY,CAAC,CAAC;IAC/B,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC7B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAyF7B;AAED,wBAAsB,yBAAyB,CAC7C,GAAG,EAAE,MAAM,EACX,YAAY,SAAkB,GAC7B,OAAO,CAAC,qBAAqB,CAAC,CAqChC;AAED,wBAAsB,+BAA+B,CACnD,UAAU,EAAE,MAAM,EAClB,GAAG,CAAC,EAAE,MAAM,GACX,OAAO,CAAC,qBAAqB,CAAC,CAuBhC;AAED,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,qBAAqB,EAC9B,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,EAC5B,GAAG,SAA+B,GACjC,OAAO,CAAC,qBAAqB,CAAC,CA8ChC;AAED,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,qBAAqB,EAC9B,SAAS,EAAE,MAAM,GAChB,gBAAgB,CASlB"}
+{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../../src/composition/catalog.ts"],"names":[],"mappings":"AAIA,OAAO,EAEL,gBAAgB,EAEjB,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAclD,OAAO,KAAK,EACV,gBAAgB,EAChB,gBAAgB,EAChB,qBAAqB,EACtB,MAAM,YAAY,CAAC;AA8KpB,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,qBAAqB,EAC9B,UAAU,EAAE,MAAM,EAAE,GACnB,MAAM,EAAE,CA+BV;AAaD,MAAM,MAAM,iBAAiB,GAAG;IAC9B,gBAAgB,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC9B,eAAe,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;CAClC,CAAC;AAEF,wBAAsB,sBAAsB,CAAC,OAAO,EAAE;IACpD,MAAM,EAAE,gBAAgB,CAAC;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,CAAC,EAAE,OAAO,gBAAgB,CAAC;IACrC,eAAe,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,KAAK,CAAC,EAAE,QAAQ,CAAC,YAAY,CAAC,CAAC;IAC/B,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC7B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CA0F7B;AAED,wBAAsB,yBAAyB,CAC7C,GAAG,EAAE,MAAM,EACX,YAAY,SAAkB,GAC7B,OAAO,CAAC,qBAAqB,CAAC,CAqChC;AAED,wBAAsB,+BAA+B,CACnD,UAAU,EAAE,MAAM,EAClB,GAAG,CAAC,EAAE,MAAM,EACZ,YAAY,GAAE;IACZ,UAAU,CAAC,EAAE,CACX,SAAS,EAAE,MAAM,EAAE,KAChB,YAAY,EAAE,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;IAC9C,kBAAkB,CAAC,EAAE,CACnB,GAAG,EAAE,MAAM,KACR,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;CAC9C,GACL,OAAO,CAAC,qBAAqB,CAAC,CA4BhC;AAED,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,qBAAqB,EAC9B,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,EAC5B,GAAG,SAA+B,GACjC,OAAO,CAAC,qBAAqB,CAAC,CAiDhC;AAED,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,qBAAqB,EAC9B,SAAS,EAAE,MAAM,GAChB,gBAAgB,CASlB"}

package/dist/composition/catalog.js

@@ -7,7 +7,9 @@ import { CompositionValidationError } from "./errors.js";
 import { isManagedApplicationSource, resolveRegistryTarget, resolveWorkspacePath, } from "./paths.js";
 import { formatZodError, NEXT_HYDRA_SELECTION_SCHEMA_URL, selectionDefinitionSchema, } from "./schema.js";
 const GITHUB_HOMEPAGE_PATTERN = /^https:\/\/github\.com\/([^/]+\/[^/]+?)(?:\.git)?\/?$/;
+const SHADCN_REGISTRY_ITEM_SCHEMA_URL = "https://ui.shadcn.com/schema/registry-item.json";
 const OFFICIAL_REFERENCES = {
+    clerk: "next-hydra/auth/clerk",
     commercetools: "next-hydra/commerce/commercetools",
     contentstack: "next-hydra/cms/contentstack",
     drupal: "next-hydra/cms/drupal",
@@ -15,6 +17,8 @@ const OFFICIAL_REFERENCES = {
     workos: "next-hydra/auth/workos",
 };
 const OFFICIAL_ITEM_NAMES = [
+    "auth-clerk",
+    "auth-contract",
     "auth-workos",
     "cms-contentstack",
     "cms-drupal",
@@ -22,6 +26,15 @@ const OFFICIAL_ITEM_NAMES = [
     "drupal",
     "next-hydra-standard",
 ];
+function restoreFetchedSelectionSchema(item) {
+    // ShadCN assigns its registry-item schema to every resolved artifact,
+    // including artifacts authored with the Next Hydra Selection schema.
+    if (item.meta?.nextHydra !== undefined &&
+        item.$schema === SHADCN_REGISTRY_ITEM_SCHEMA_URL) {
+        return { ...item, $schema: NEXT_HYDRA_SELECTION_SCHEMA_URL };
+    }
+    return item;
+}
 function createCatalog(options) {
     const items = new Map(options.registryItems.map((item) => [item.name, item]));
     const itemByReference = new Map(options.itemByReference);
@@ -162,12 +175,13 @@ export async function fetchRegistryItemGraph(options) {
         if (!itemName) {
             // oxlint-disable-next-line no-await-in-loop -- Breadth-first discovery reveals each next reference in order.
             const resolvedReference = await resolveRegistryReference(reference, options.cwd);
-            const [artifact] = await fetchItems([resolvedReference], {
+            const [fetchedArtifact] = await fetchItems([resolvedReference], {
                 config: options.config,
             });
-            if (!artifact) {
+            if (!fetchedArtifact) {
                 throw new CompositionValidationError("The registry dependency graph is incomplete.", [`${reference} returned no registry item`]);
             }
+            const artifact = restoreFetchedSelectionSchema(fetchedArtifact);
             const fetched = fetchedItems.get(artifact.name);
             const unpinnedReference = reference.split("#", 1)[0] ?? reference;
             const replacesPinnedRepositoryItem = reference.includes("#") &&
@@ -233,11 +247,12 @@ export async function loadSourceRegistryCatalog(cwd, registryFile = "registry.js
         repository,
     });
 }
-export async function loadGitHubSourceRegistryCatalog(repository, ref) {
+export async function loadGitHubSourceRegistryCatalog(repository, ref, dependencies = {}) {
     const suffix = ref ? `#${ref}` : "";
     const addresses = OFFICIAL_ITEM_NAMES.map((item) => `${repository}/${item}${suffix}`);
-    const registryItems = await getRegistryItems(addresses);
-    const registryConfig = await getRegistriesConfig(process.cwd());
+    const fetchedItems = await (dependencies.fetchItems ?? getRegistryItems)(addresses);
+    const registryItems = fetchedItems.map(restoreFetchedSelectionSchema);
+    const registryConfig = await (dependencies.loadRegistryConfig ?? getRegistriesConfig)(process.cwd());
     const itemByReference = new Map(registryItems.flatMap((item, index) => {
         const address = addresses[index];
         return address ? [[address, item.name]] : [];
@@ -282,7 +297,8 @@ export async function addCatalogReferences(catalog, references, cwd = catalog.cw
     }
     for (const itemName of graph.fetchedItemNames) {
         const externalSelection = current.byReference.get(itemName);
-        if (externalSelection !== undefined && externalSelection.assets.length > 0) {
+        if (externalSelection !== undefined &&
+            externalSelection.assets.length > 0) {
             throw new CompositionValidationError("External selections cannot declare separate binary assets in v1.", [
                 `${externalSelection.id} must be included by the starter source registry; separately fetched binary assets are not supported`,
             ]);

package/dist/composition/format.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../../src/composition/format.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAwCtE,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,kBAAkB,EAC3B,QAAQ,EAAE,kBAAkB,GAC3B,OAAO,CAET;AAED,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,kBAAkB,EAC3B,QAAQ,EAAE,kBAAkB,GAC3B,MAAM,CA4BR;AAED,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,kBAAkB,EAC3B,QAAQ,EAAE,kBAAkB,GAC3B,MAAM,CAKR;AAED,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,eAAe,GAAG,MAAM,CAuBnE"}
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../../src/composition/format.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAwCtE,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,kBAAkB,EAC3B,QAAQ,EAAE,kBAAkB,GAC3B,OAAO,CAET;AAED,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,kBAAkB,EAC3B,QAAQ,EAAE,kBAAkB,GAC3B,MAAM,CA6BR;AAED,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,kBAAkB,EAC3B,QAAQ,EAAE,kBAAkB,GAC3B,MAAM,CAKR;AAED,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,eAAe,GAAG,MAAM,CA2BnE"}

package/dist/composition/format.js

@@ -35,7 +35,7 @@ export function formatCompositionPreview(current, proposed) {
         `Add-ons: ${currentAddOns === proposedAddOns ? `${currentAddOns} (unchanged)` : `${currentAddOns} -> ${proposedAddOns}`}`,
     ];
     if (hasCompositionChanges(current, proposed)) {
-        lines.push("", "Planned actions:", "  replace managed application files", "  install selected source", "  update package aliases", "  update pnpm patches", "  run pnpm install");
+        lines.push("", "Planned actions:", "  replace managed application files", "  install selected source", "  update package aliases", "  update TypeScript paths", "  update pnpm patches", "  run pnpm install");
     }
     return lines.join("\n");
 }
@@ -54,6 +54,8 @@ export function formatCompositionPlan(plan) {
         ...plan.registryItems.map((item) => `  ${item}`),
         "Package entries:",
         ...plan.packageRequirements.map((requirement) => `  ${requirement.cwd}: ${requirement.name} = ${requirement.specifier}`),
+        "TypeScript paths:",
+        ...plan.typeScriptPathAliases.map((entry) => `  ${entry.cwd}: ${entry.alias} -> ${entry.sourcePath}`),
         "pnpm patches:",
         ...plan.pnpmPatches.map((patch) => `  ${patch.dependency} -> ${patch.path}`),
         "Managed application files:",

package/dist/composition/packages.d.ts

@@ -1,6 +1,6 @@
-import type { DependencySection, PackageRequirement, SelectionDefinition } from "./types.js";
+import type { DependencySection, PackageRequirement } from "./types.js";
 export type PackageJson = Partial<Record<DependencySection, Record<string, string>>> & Record<string, unknown>;
 export declare function parsePackageJson(source: string, label: string): PackageJson;
 export declare function readPackageJson(filePath: string, label?: string): Promise<PackageJson>;
-export declare function mergePackageRequirements(selections: Pick<SelectionDefinition, "packages">[]): PackageRequirement[];
+export declare function mergePackageRequirements(entries: Iterable<PackageRequirement>): PackageRequirement[];
 //# sourceMappingURL=packages.d.ts.map

package/dist/composition/packages.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"packages.d.ts","sourceRoot":"","sources":["../../src/composition/packages.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EACV,iBAAiB,EACjB,kBAAkB,EAClB,mBAAmB,EACpB,MAAM,YAAY,CAAC;AAWpB,MAAM,MAAM,WAAW,GAAG,OAAO,CAC/B,MAAM,CAAC,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAClD,GACC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAe1B,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,WAAW,CAY3E;AAED,wBAAsB,eAAe,CACnC,QAAQ,EAAE,MAAM,EAChB,KAAK,SAAW,GACf,OAAO,CAAC,WAAW,CAAC,CAEtB;AAED,wBAAgB,wBAAwB,CACtC,UAAU,EAAE,IAAI,CAAC,mBAAmB,EAAE,UAAU,CAAC,EAAE,GAClD,kBAAkB,EAAE,CA8BtB"}
+{"version":3,"file":"packages.d.ts","sourceRoot":"","sources":["../../src/composition/packages.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAWxE,MAAM,MAAM,WAAW,GAAG,OAAO,CAC/B,MAAM,CAAC,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAClD,GACC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAe1B,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,WAAW,CAY3E;AAED,wBAAsB,eAAe,CACnC,QAAQ,EAAE,MAAM,EAChB,KAAK,SAAW,GACf,OAAO,CAAC,WAAW,CAAC,CAEtB;AAED,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,QAAQ,CAAC,kBAAkB,CAAC,GACpC,kBAAkB,EAAE,CA8BtB"}

package/dist/composition/packages.js

@@ -32,23 +32,24 @@ export function parsePackageJson(source, label) {
 export async function readPackageJson(filePath, label = filePath) {
     return parsePackageJson(await readFile(filePath, "utf-8"), label);
 }
-export function mergePackageRequirements(selections) {
+export function mergePackageRequirements(entries) {
     const requirements = new Map();
     const issues = [];
-    for (const selection of selections) {
-        for (const requirement of selection.packages) {
-            const key = `${requirement.cwd}\0${requirement.section}\0${requirement.name}`;
-            const existing = requirements.get(key);
-            if (existing && existing.specifier !== requirement.specifier) {
-                issues.push(`${requirement.cwd}/${requirement.section}.${requirement.name} is requested as both ${existing.specifier} and ${requirement.specifier}`);
-            }
-            else {
-                requirements.set(key, requirement);
-            }
+    for (const requirement of entries) {
+        const key = `${requirement.cwd}\0${requirement.section}\0${requirement.name}`;
+        const existing = requirements.get(key);
+        if (existing && existing.specifier !== requirement.specifier) {
+            issues.push(`${requirement.cwd}/${requirement.section}.${requirement.name} is requested as both ${existing.specifier} and ${requirement.specifier}`);
+        }
+        else {
+            requirements.set(key, requirement);
         }
     }
     if (issues.length > 0) {
-        throw new CompositionValidationError("Package requirements conflict.", [...new Set(issues)].sort((left, right) => left.localeCompare(right)));
+        throw new CompositionValidationError("Package requirements conflict.", 
+        // eslint-disable-next-line unicorn/no-array-sort -- The newly-created array is safe to sort in place.
+        [...new Set(issues)].sort((left, right) => left.localeCompare(right)));
     }
+    // eslint-disable-next-line unicorn/no-array-sort -- The newly-created array is safe to sort in place.
     return [...requirements.values()].sort((left, right) => `${left.cwd}/${left.section}/${left.name}`.localeCompare(`${right.cwd}/${right.section}/${right.name}`));
 }

package/dist/composition/planner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"planner.d.ts","sourceRoot":"","sources":["../../src/composition/planner.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAEV,eAAe,EAIf,qBAAqB,EACrB,kBAAkB,EACnB,MAAM,YAAY,CAAC;AAiWpB,wBAAgB,eAAe,CAC7B,OAAO,EAAE,qBAAqB,EAC9B,SAAS,EAAE,kBAAkB,GAC5B,eAAe,CAoGjB;AAED,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,qBAAqB,EAC9B,SAAS,EAAE,MAAM,GAChB,kBAAkB,CAuBpB"}
+{"version":3,"file":"planner.d.ts","sourceRoot":"","sources":["../../src/composition/planner.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAEV,eAAe,EAMf,qBAAqB,EAGrB,kBAAkB,EACnB,MAAM,YAAY,CAAC;AA2YpB,wBAAgB,eAAe,CAC7B,OAAO,EAAE,qBAAqB,EAC9B,SAAS,EAAE,kBAAkB,GAC5B,eAAe,CAmHjB;AAED,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,qBAAqB,EAC9B,SAAS,EAAE,MAAM,GAChB,kBAAkB,CAuBpB"}

package/dist/composition/planner.js

@@ -109,54 +109,92 @@ function validateCompatibility(selections) {
         throw new CompositionValidationError("The requested selections are incompatible.", uniqueSorted(issues));
     }
 }
-function validateProviderAliasRequirements(providers) {
-    const requiredLocations = {
-        auth: [
-            { cwd: "apps/api", section: "dependencies" },
-            { cwd: "apps/web", section: "dependencies" },
-            { cwd: "packages/feature-flags", section: "dependencies" },
-        ],
-        cms: [
-            { cwd: "apps/cli", section: "dependencies" },
-            { cwd: "apps/web", section: "dependencies" },
-        ],
-        commerce: [
-            { cwd: "apps/api", section: "dependencies" },
-            { cwd: "apps/cli", section: "dependencies" },
-            { cwd: "apps/web", section: "dependencies" },
-        ],
-    };
-    const issues = [];
-    for (const provider of providers) {
-        if (!provider.slot) {
-            continue;
+const BASELINE_PROVIDER_DEPENDENCIES = [
+    { cwd: "apps/admin", section: "dependencies", slot: "auth" },
+    { cwd: "apps/api", section: "dependencies", slot: "auth" },
+    { cwd: "apps/cli", section: "dependencies", slot: "auth" },
+    { cwd: "apps/web", section: "dependencies", slot: "auth" },
+    { cwd: "packages/feature-flags", section: "dependencies", slot: "auth" },
+    { cwd: "tests/e2e", section: "devDependencies", slot: "auth" },
+    { cwd: "apps/cli", section: "dependencies", slot: "cms" },
+    { cwd: "apps/web", section: "dependencies", slot: "cms" },
+    { cwd: "apps/api", section: "dependencies", slot: "commerce" },
+    { cwd: "apps/cli", section: "dependencies", slot: "commerce" },
+    { cwd: "apps/web", section: "dependencies", slot: "commerce" },
+    { cwd: "tests/e2e", section: "devDependencies", slot: "commerce" },
+];
+function selectedProviderDependencies(selections) {
+    return [
+        ...BASELINE_PROVIDER_DEPENDENCIES,
+        ...selections.flatMap((selection) => selection.providerDependencies),
+    ];
+}
+function catalogProviderDependencies(catalog) {
+    return [
+        ...BASELINE_PROVIDER_DEPENDENCIES,
+        ...catalog.selections.flatMap((selection) => selection.providerDependencies),
+    ];
+}
+function resolveProviderRequirements(providers, dependencies) {
+    const packageRequirements = [];
+    const typeScriptPathAliases = new Map();
+    for (const dependency of dependencies) {
+        const provider = providers.get(dependency.slot);
+        if (!provider?.binding) {
+            throw new CompositionValidationError("Provider binding is missing.", [
+                `${dependency.slot} does not supply a Provider binding`,
+            ]);
         }
-        const alias = PROVIDER_ALIASES[provider.slot];
-        const requiredClaims = new Set(requiredLocations[provider.slot].map((requirement) => `${requirement.cwd}\0${requirement.section}\0${alias}`));
-        const actualClaims = new Set(provider.packages.map((requirement) => `${requirement.cwd}\0${requirement.section}\0${requirement.name}`));
-        for (const claim of requiredClaims) {
-            if (!actualClaims.has(claim)) {
-                const [cwd, section, name] = claim.split("\0");
-                issues.push(`${provider.id} must declare ${cwd}/${section}.${name} for the ${provider.slot} Provider Slot`);
-            }
+        const alias = PROVIDER_ALIASES[dependency.slot];
+        packageRequirements.push({
+            cwd: dependency.cwd,
+            name: alias,
+            section: dependency.section,
+            specifier: provider.binding.specifier,
+        });
+        if (provider.binding.sourcePath) {
+            typeScriptPathAliases.set(`${dependency.cwd}\0${alias}`, {
+                alias,
+                cwd: dependency.cwd,
+                sourcePath: resolveWorkspacePath(provider.binding.sourcePath, `${provider.id} Provider binding source path`),
+            });
         }
     }
-    if (issues.length > 0) {
-        throw new CompositionValidationError("Providers do not supply all stable Provider aliases required by the Baseline.", uniqueSorted(issues));
+    // eslint-disable-next-line unicorn/no-array-sort -- The newly-created array is safe to sort in place.
+    const aliases = [...typeScriptPathAliases.values()].sort((left, right) => `${left.cwd}/${left.alias}`.localeCompare(`${right.cwd}/${right.alias}`));
+    return { packageRequirements, typeScriptPathAliases: aliases };
+}
+function catalogTypeScriptPathAliases(dependencies) {
+    const aliases = new Map();
+    for (const dependency of dependencies) {
+        const alias = PROVIDER_ALIASES[dependency.slot];
+        aliases.set(`${dependency.cwd}\0${alias}`, {
+            alias,
+            cwd: dependency.cwd,
+        });
     }
+    // eslint-disable-next-line unicorn/no-array-sort -- The newly-created array is safe to sort in place.
+    return [...aliases.values()].sort((left, right) => `${left.cwd}/${left.alias}`.localeCompare(`${right.cwd}/${right.alias}`));
 }
-function catalogPackageRequirements(catalog) {
-    const requirements = new Map();
+function catalogPackageRequirementTargets(catalog, providerDependencies) {
+    const targets = new Map();
+    const add = (target) => {
+        targets.set(`${target.cwd}\0${target.section}\0${target.name}`, target);
+    };
     for (const selection of catalog.selections) {
-        for (const requirement of selection.packages) {
-            const key = `${requirement.cwd}\0${requirement.section}\0${requirement.name}`;
-            if (!requirements.has(key)) {
-                requirements.set(key, requirement);
-            }
+        for (const { cwd, name, section } of selection.packages) {
+            add({ cwd, name, section });
         }
     }
+    for (const dependency of providerDependencies) {
+        add({
+            cwd: dependency.cwd,
+            name: PROVIDER_ALIASES[dependency.slot],
+            section: dependency.section,
+        });
+    }
     // eslint-disable-next-line unicorn/no-array-sort -- The newly-created array is safe to sort in place.
-    return [...requirements.values()].sort((left, right) => `${left.cwd}/${left.section}/${left.name}`.localeCompare(`${right.cwd}/${right.section}/${right.name}`));
+    return [...targets.values()].sort((left, right) => `${left.cwd}/${left.section}/${left.name}`.localeCompare(`${right.cwd}/${right.section}/${right.name}`));
 }
 function resolvePnpmPatches(selections) {
     const patches = new Map();
@@ -240,8 +278,14 @@ export function planComposition(catalog, selection) {
     });
     const addOns = resolveAddOns(catalog, selection.addOns, providerSelections);
     const selections = [...providerSelections, ...addOns];
-    validateProviderAliasRequirements(providerSelections);
     validateCompatibility(selections);
+    const providerDependencies = selectedProviderDependencies(selections);
+    const catalogDependencies = catalogProviderDependencies(catalog);
+    const providerRequirements = resolveProviderRequirements(providers, providerDependencies);
+    const packageRequirements = mergePackageRequirements([
+        ...selections.flatMap((selected) => selected.packages),
+        ...providerRequirements.packageRequirements,
+    ]);
     const entryItems = uniqueSorted(selections.map((selected) => selected.itemName));
     const registryItems = resolveRegistryItemGraph(catalog, entryItems);
     const assets = selections
@@ -272,8 +316,9 @@ export function planComposition(catalog, selection) {
     return {
         assets,
         catalogManagedTargets: catalog.managedTargets,
-        catalogPackageRequirements: catalogPackageRequirements(catalog),
+        catalogPackageRequirementTargets: catalogPackageRequirementTargets(catalog, catalogDependencies),
         catalogPnpmPatches: catalogPnpmPatches(catalog),
+        catalogTypeScriptPathAliases: catalogTypeScriptPathAliases(catalogDependencies),
         entryItems,
         instructions: [
             ...new Set(selections
@@ -281,7 +326,7 @@ export function planComposition(catalog, selection) {
                 .filter((value) => Boolean(value))),
         ],
         managedTargets,
-        packageRequirements: mergePackageRequirements(selections),
+        packageRequirements,
         pnpmPatches,
         registryItems,
         selection: {
@@ -290,6 +335,7 @@ export function planComposition(catalog, selection) {
             providers: { ...selection.providers },
         },
         selections,
+        typeScriptPathAliases: providerRequirements.typeScriptPathAliases,
         variableTargets: uniqueSorted([
             ...catalogVariableTargets(catalog),
             ...catalog.selections.flatMap((selected) => selected.assets.map((asset) => resolveWorkspacePath(asset.target, `${selected.id} asset target`))),