create-next-hydra 0.1.0 → 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 JAKALA
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,91 @@
+# create-next-hydra
+
+`create-next-hydra` composes a Next Hydra workspace from one Auth Provider, one CMS Provider, one Commerce Provider, and any compatible Add-ons. It uses [ShadCN registry items](https://ui.shadcn.com/docs/registry/registry-item-json) to copy code and adds Next Hydra's stack validation and package-specific manifest changes.
+
+## Create a project
+
+Interactive scaffolding asks for every required Provider:
+
+```bash
+pnpm dlx create-next-hydra@latest my-project
+```
+
+For a non-interactive scaffold, provide all three Providers or a Preset:
+
+```bash
+pnpm dlx create-next-hydra@latest my-project --yes \
+  --auth workos \
+  --cms drupal \
+  --commerce commercetools
+
+pnpm dlx create-next-hydra@latest my-project --yes --preset standard
+```
+
+Use `--add-on <selection>` more than once to include compatible Add-ons. A selection can be an official shorthand, a local registry-item JSON file, a URL, a public GitHub address such as `owner/repository/item#ref`, or a configured ShadCN registry name.
+
+The destination must be missing or empty. If scaffolding fails, the CLI leaves the partial project in place and reports what completed and what was not attempted.
+
+## Change the maintainer workspace
+
+The repository root is a Maintainer Workspace because it contains `next-hydra.json` and the source registry. Build the local CLI, then change a Provider or apply a Preset:
+
+```bash
+pnpm --filter create-next-hydra build
+node packages/create-next-hydra/dist/cli.js use --cms contentstack
+node packages/create-next-hydra/dist/cli.js use --preset standard
+node packages/create-next-hydra/dist/cli.js use --check
+```
+
+`use` updates `next-hydra.json`, governed package entries, Provider-owned application files such as Next.js routes, and the lockfile. It does not remove canonical Provider or Add-on implementation source from the maintainer repository. If an operation fails, it leaves the Git diff in place for inspection or repair.
+
+## Add code to a customer workspace
+
+Run `add` from an existing customer-owned workspace:
+
+```bash
+pnpm dlx create-next-hydra@latest add owner/repository/drupal-dam
+```
+
+The command walks the complete registry dependency graph before ShadCN flattens it, rejects duplicate file targets, and lists every prospective file, package entry, and other ShadCN-managed effect. It verifies known Provider requirements through exact aliases in `apps/web/package.json` and labels compatibility requirements that cannot be proven without a customer receipt. The inspected graph is prepared locally so the exact approved artifacts are also the installation input. To keep that preview truthful, customer `add` accepts only explicitly targeted, exact-copy `registry:file` and `registry:item` file entries; file types that ShadCN would transform are rejected. It creates missing files, skips files ShadCN considers identical after newline and surrounding-whitespace normalization, and asks before replacing a changed file or dependency. Like ShadCN, `--yes` skips confirmation prompts and `--overwrite` authorizes replacing changed targets. Combine them for a fully non-interactive installation after reviewing the disclosed plan. `--yes` alone still refuses changed customer code. When package-specific entries change, `add` runs the root `pnpm install` to settle the lockfile and workspace links. The command never deletes files and does not retain a receipt.
+
+Customer `add` accepts ordinary registry items and Next Hydra Add-ons. It does not switch Providers or apply Presets. In v1, an Add-on that declares separate binary assets or pnpm patches must be selected in a Maintainer Workspace or during a new scaffold.
+
+## Author a Provider or Add-on
+
+Keep source in its normal package or application directory and place a `registry.json` beside it. Add that registry file to the root `registry.json` `include` list. A registry containing Selection Definitions uses [`source-registry.json`](./schema/source-registry.json), which applies the complete [`selection-definition.json`](./schema/selection-definition.json) registry-item schema whenever an item contains `meta.nextHydra`. Ordinary registry items continue to use ShadCN's schema.
+
+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;
+- standard ShadCN `registryDependencies` for any other registry items it needs;
+- required and conflicting selection IDs;
+- exact package entries and aliases;
+- exact pnpm patch entries and their patch-file assets; and
+- setup instructions through the registry item's standard `docs` field.
+
+Every copied registry file must have an explicit workspace-root target such as `~/packages/cms-drupal/src/index.ts`. The source `path` remains relative to the colocated registry, so maintainers edit and test canonical Provider code in its normal package or application.
+
+When a Provider or Add-on needs to place a file outside its own source directory, keep that source under a colocated `registry/` directory using its final workspace path. For example, `packages/cms-drupal/registry/apps/web/app/api/draft/route.ts` is installed as `~/apps/web/app/api/draft/route.ts`. These files are ordinary ShadCN registry files: ShadCN installs them during scaffolding and customer `add`, while maintainer `use` may remove or replace their known targets when the selected stack changes.
+
+Run these commands after adding, moving, or removing contribution files:
+
+```bash
+pnpm registry:sync
+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.
+
+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.
+
+ShadCN registry mappings, including private registry URLs and environment-backed headers, are read from the invoking workspace's `components.json` or `package.json`, used for both graph preflight and installation, and are not copied into a new scaffold. Secrets are never requested or generated by Next Hydra; registry `envVars` remain suitable only for safe placeholders or development defaults.
+
+## Current limits
+
+- Auth, CMS, and Commerce each require exactly one Provider.
+- A scaffolded Customer Workspace has no composition receipt and cannot be automatically upgraded or switched later.
+- Composition installs local code and JavaScript dependencies. Remote service setup, real secrets, Composer changes, Drupal module enablement, and deployed extensions remain manual.
+- Selection Definitions are declarative and cannot run arbitrary hooks.

package/dist/composition/add.d.ts

@@ -0,0 +1,14 @@
+import { confirm } from "@clack/prompts";
+export type AddOptions = {
+    cwd?: string;
+    overwrite?: boolean;
+    yes?: boolean;
+};
+type ConfirmPrompt = (options: Parameters<typeof confirm>[0]) => ReturnType<typeof confirm>;
+export type AddDependencies = {
+    confirm?: ConfirmPrompt;
+    install?: (cwd: string) => Promise<void>;
+};
+export declare function addRegistryItem(reference: string, options?: AddOptions, dependencies?: AddDependencies): Promise<void>;
+export {};
+//# sourceMappingURL=add.d.ts.map

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

@@ -0,0 +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"}

package/dist/composition/add.js

@@ -0,0 +1,453 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { confirm, isCancel } from "@clack/prompts";
+import { getRegistriesConfig, resolveRegistryItems } from "shadcn/registry";
+import { pathExists } from "../fs-utils.js";
+import { runCommand } from "../git.js";
+import { info, success } from "../logger.js";
+import { fetchRegistryItemGraph } from "./catalog.js";
+import { CompositionValidationError } from "./errors.js";
+import { addRegistryItemsQuietly, withPreparedRegistryArtifacts, } from "./install.js";
+import { mergePackageRequirements, parsePackageJson, readPackageJson, } from "./packages.js";
+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/workos",
+        { dependency: "@repo/auth", packageName: "@repo/auth-workos" },
+    ],
+    [
+        "next-hydra/cms/contentstack",
+        { dependency: "@repo/cms", packageName: "@repo/cms-contentstack" },
+    ],
+    [
+        "next-hydra/cms/drupal",
+        { dependency: "@repo/cms", packageName: "@repo/cms-drupal" },
+    ],
+    [
+        "next-hydra/commerce/commercetools",
+        {
+            dependency: "@repo/commerce-provider",
+            packageName: "@repo/commerce-commercetools",
+        },
+    ],
+]);
+function parseDependency(request) {
+    const packageEnd = request.startsWith("@")
+        ? request.indexOf("@", request.indexOf("/") + 1)
+        : request.indexOf("@");
+    if (packageEnd < 1) {
+        return { name: request };
+    }
+    return {
+        name: request.slice(0, packageEnd),
+        specifier: request.slice(packageEnd + 1),
+    };
+}
+function packageStatus(actual, expected) {
+    if (actual === undefined) {
+        return "create";
+    }
+    return actual === expected ? "identical" : "changed";
+}
+function dependencyStatus(actual, requested) {
+    if (requested.specifier) {
+        return packageStatus(actual, requested.specifier);
+    }
+    return actual === undefined ? "create" : "identical";
+}
+function parseSelection(item) {
+    if (item.meta?.nextHydra === undefined) {
+        return;
+    }
+    if (item.$schema !== NEXT_HYDRA_SELECTION_SCHEMA_URL) {
+        throw new CompositionValidationError(`${item.name} does not use the Next Hydra Selection Definition schema.`, [`$schema must be ${NEXT_HYDRA_SELECTION_SCHEMA_URL}`]);
+    }
+    const result = selectionDefinitionSchema.safeParse(item.meta.nextHydra);
+    if (!result.success) {
+        throw new CompositionValidationError(`${item.name} contains invalid Next Hydra metadata. Run the latest create-next-hydra and try again.`, formatZodError(result.error));
+    }
+    return result.data;
+}
+async function changeStatus(absoluteTarget, expected) {
+    if (!(await pathExists(absoluteTarget))) {
+        return "create";
+    }
+    const normalize = (content) => content.replaceAll("\r\n", "\n").trim();
+    return normalize(await readFile(absoluteTarget, "utf-8")) ===
+        normalize(expected)
+        ? "identical"
+        : "changed";
+}
+function requireExactCopyFile(type, owner) {
+    if (!EXACT_COPY_FILE_TYPES.has(type)) {
+        throw new CompositionValidationError("Customer add supports only exact-copy registry files in v1.", [
+            `${owner} uses ${type}; use registry:file or registry:item with an explicit target so the reviewed content is exactly what ShadCN writes`,
+        ]);
+    }
+}
+async function inspectFiles(workspaceRoot, tree) {
+    const registryFiles = await Promise.all((tree.files ?? []).map(async (file) => {
+        requireExactCopyFile(file.type, file.path);
+        if (!(file.target && file.content !== undefined)) {
+            throw new CompositionValidationError("Next Hydra Add-ons require explicit workspace-root file targets.", [`${file.path} must include content and a target beginning with ~/`]);
+        }
+        const target = resolveRegistryTarget(file.target);
+        return {
+            kind: "registry file",
+            status: await changeStatus(path.join(workspaceRoot, target), file.content),
+            target,
+        };
+    }));
+    const claimed = new Map();
+    for (const change of registryFiles) {
+        const existing = claimed.get(change.target);
+        if (existing) {
+            throw new CompositionValidationError("The requested Add-on targets the same customer file more than once.", [`${change.target} is both a ${existing} and a ${change.kind}`]);
+        }
+        claimed.set(change.target, change.kind);
+    }
+    return registryFiles.sort((left, right) => left.target.localeCompare(right.target));
+}
+async function inspectPackages(workspaceRoot, requirements, tree) {
+    const prospectiveManifests = new Map();
+    for (const file of tree.files ?? []) {
+        if (!(file.target && file.content !== undefined)) {
+            continue;
+        }
+        const target = resolveRegistryTarget(file.target);
+        if (target.endsWith("/package.json") || target === "package.json") {
+            prospectiveManifests.set(target, file.content);
+        }
+    }
+    return await Promise.all(requirements.map(async (requirement) => {
+        const relativeManifest = path.posix.join(requirement.cwd, "package.json");
+        const prospective = prospectiveManifests.get(relativeManifest);
+        const manifest = prospective === undefined
+            ? await readPackageJson(path.join(workspaceRoot, relativeManifest), relativeManifest)
+            : parsePackageJson(prospective, relativeManifest);
+        const actual = manifest[requirement.section]?.[requirement.name];
+        return {
+            ...requirement,
+            actual,
+            status: packageStatus(actual, requirement.specifier),
+        };
+    }));
+}
+async function inspectRootDependencies(workspaceRoot, tree) {
+    const manifest = await readPackageJson(path.join(workspaceRoot, "package.json"), "package.json");
+    const requests = [
+        ...(tree.dependencies ?? []).map((request) => ({
+            ...parseDependency(request),
+            section: "dependencies",
+        })),
+        ...(tree.devDependencies ?? []).map((request) => ({
+            ...parseDependency(request),
+            section: "devDependencies",
+        })),
+    ];
+    return requests.map((request) => {
+        const actual = manifest[request.section]?.[request.name];
+        const specifier = request.specifier ?? actual ?? "registry default";
+        return {
+            actual,
+            cwd: ".",
+            name: request.name,
+            section: request.section,
+            specifier,
+            status: dependencyStatus(actual, request),
+        };
+    });
+}
+function usesProviderAlias(actual, packageName) {
+    if (!actual) {
+        return false;
+    }
+    return (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;
+    }
+    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;
+}
+async function validateKnownProviderCompatibility(workspaceRoot, 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]));
+    for (const selection of selections) {
+        if (selection.kind !== "provider") {
+            continue;
+        }
+        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`);
+            continue;
+        }
+        const actual = manifest.dependencies?.[provider.dependency];
+        if (!usesProviderAlias(actual, provider.packageName)) {
+            issues.push(`${selection.id} is a Provider in the requested graph, but the current provider alias ${provider.dependency} is ${actual ?? "missing"}`);
+        }
+    }
+    for (const selection of selections) {
+        for (const required of selection.compatibility.requires) {
+            const provider = providerExpectation(required, selectionsById);
+            const requiredSelection = selectionsById.get(required);
+            if (provider &&
+                !usesProviderAlias(manifest.dependencies?.[provider.dependency], provider.packageName)) {
+                issues.push(`${selection.id} requires ${required}`);
+            }
+            else if (!(provider || requiredSelection?.kind === "add-on")) {
+                assumptions.push(`${selection.id} requires ${required}; this customer workspace has no authoritative selection record, so Next Hydra cannot verify it`);
+            }
+        }
+        for (const conflict of selection.compatibility.conflicts) {
+            const provider = providerExpectation(conflict, selectionsById);
+            const conflictingSelection = selectionsById.get(conflict);
+            if ((provider &&
+                usesProviderAlias(manifest.dependencies?.[provider.dependency], provider.packageName)) ||
+                conflictingSelection?.kind === "add-on") {
+                issues.push(`${selection.id} conflicts with ${conflict}`);
+            }
+            else if (!provider) {
+                assumptions.push(`${selection.id} conflicts with ${conflict}; this customer workspace has no authoritative selection record, so Next Hydra cannot verify its absence`);
+            }
+        }
+    }
+    if (issues.length > 0) {
+        throw new CompositionValidationError("The Add-on is incompatible with the current provider aliases.", issues);
+    }
+    return [...new Set(assumptions)].sort((left, right) => left.localeCompare(right));
+}
+function validateRegistryTargetClaims(items) {
+    const claims = new Map();
+    const issues = [];
+    for (const item of items) {
+        for (const file of item.files ?? []) {
+            requireExactCopyFile(file.type, `${item.name}:${file.path}`);
+            if (!(file.target && file.content !== undefined)) {
+                throw new CompositionValidationError("Next Hydra Add-ons require explicit workspace-root file targets.", [
+                    `${item.name}:${file.path} must include content and a target beginning with ~/`,
+                ]);
+            }
+            const target = resolveRegistryTarget(file.target);
+            const owner = `${item.name}:${file.path}`;
+            const existing = claims.get(target);
+            if (existing && existing !== owner) {
+                issues.push(`${target} is claimed by both ${existing} and ${owner}`);
+            }
+            else {
+                claims.set(target, owner);
+            }
+        }
+    }
+    if (issues.length > 0) {
+        throw new CompositionValidationError("The registry dependency graph targets the same customer file more than once.", issues);
+    }
+}
+function describeShadcnEffects(tree, items) {
+    const hasValues = (value) => {
+        if (Array.isArray(value)) {
+            return value.some(hasValues);
+        }
+        if (value !== null && typeof value === "object") {
+            return Object.values(value).some(hasValues);
+        }
+        return (value !== undefined && value !== null && value !== false && value !== "");
+    };
+    const effects = [];
+    const envKeys = Object.keys(tree.envVars ?? {}).sort();
+    if (envKeys.length > 0) {
+        effects.push(`environment placeholders may be merged by ShadCN: ${envKeys.join(", ")}`);
+    }
+    if (hasValues(tree.tailwind)) {
+        effects.push("Tailwind configuration will be merged by ShadCN");
+    }
+    if (hasValues(tree.cssVars)) {
+        effects.push("CSS variables will be merged by ShadCN");
+    }
+    if (hasValues(tree.css)) {
+        effects.push("CSS declarations will be merged by ShadCN");
+    }
+    if ((tree.fonts?.length ?? 0) > 0) {
+        effects.push(`${tree.fonts?.length ?? 0} font definition(s) will be applied by ShadCN`);
+    }
+    if ([...items].some((item) => "config" in item && item.config !== undefined)) {
+        effects.push("ShadCN project configuration will be updated");
+    }
+    return [...new Set(effects)];
+}
+async function confirmChanges(fileChanges, packageChanges, options, prompt) {
+    const overwrite = options.overwrite ?? false;
+    const yes = options.yes === true;
+    const conflicts = [
+        ...fileChanges
+            .filter((change) => change.status === "changed")
+            .map((change) => ({ kind: change.kind, label: change.target })),
+        ...packageChanges
+            .filter((change) => change.status === "changed")
+            .map((change) => ({
+            kind: "dependency",
+            label: `${change.cwd}/package.json ${change.name}: ${change.actual} -> ${change.specifier}`,
+        })),
+    ];
+    if (yes && !overwrite && conflicts.length > 0) {
+        throw new CompositionValidationError("Additive installation found customer-owned conflicts.", conflicts.map((conflict) => `${conflict.label} requires --overwrite; --yes only skips confirmation prompts for non-conflicting changes`));
+    }
+    if (!overwrite) {
+        for (const conflict of conflicts) {
+            // Without a global overwrite authorization, each customer-owned change
+            // receives its own explicit confirmation.
+            // oxlint-disable-next-line no-await-in-loop -- Sequential confirmation is the safety contract.
+            const approved = await prompt({
+                initialValue: false,
+                message: `Replace changed ${conflict.kind} ${conflict.label}?`,
+            });
+            if (isCancel(approved) || !approved) {
+                throw new Error("Installation cancelled. No files or package entries were changed.");
+            }
+        }
+    }
+    if (!yes) {
+        const approved = await prompt({
+            initialValue: true,
+            message: "Apply the listed Add-on changes?",
+        });
+        if (isCancel(approved) || !approved) {
+            throw new Error("Installation cancelled. No changes were made.");
+        }
+    }
+}
+export async function addRegistryItem(reference, options = {}, dependencies = {}) {
+    const cwd = path.resolve(options.cwd ?? process.cwd());
+    const localReference = path.resolve(cwd, reference);
+    const resolvedReference = !path.isAbsolute(reference) && (await pathExists(localReference))
+        ? localReference
+        : reference;
+    const config = await getRegistriesConfig(cwd);
+    const graph = await fetchRegistryItemGraph({
+        config,
+        cwd,
+        references: [resolvedReference],
+    });
+    const primaryName = graph.itemByReference.get(resolvedReference);
+    const primary = primaryName
+        ? graph.items.get(primaryName)
+        : undefined;
+    if (!primary) {
+        throw new Error(`The registry returned no item for ${reference}.`);
+    }
+    const selection = parseSelection(primary);
+    const graphSelections = [...graph.items.values()]
+        .map(parseSelection)
+        .filter((value) => Boolean(value));
+    if (selection) {
+        if (selection.kind === "preset") {
+            throw new Error("Presets compose a new workspace. Use `create-next-hydra <directory> --preset ...` instead of `add`.");
+        }
+        if (selection.kind === "provider") {
+            throw new Error("Providers must be selected while scaffolding or with `create-next-hydra use`; `add` does not switch a customer workspace provider.");
+        }
+    }
+    const nestedPresets = graphSelections.filter((candidate) => candidate.kind === "preset");
+    if (nestedPresets.length > 0) {
+        throw new CompositionValidationError("Presets cannot be installed into a Customer Workspace.", nestedPresets.map((candidate) => `${candidate.id} appears in the requested registry dependency graph`));
+    }
+    const assetSelections = graphSelections.filter((candidate) => candidate.assets.length > 0);
+    if (assetSelections.length > 0) {
+        throw new CompositionValidationError("Customer Add-ons cannot install separate binary assets in v1.", assetSelections.map((candidate) => `${candidate.id} must put text files in its registry item; binary asset transport requires a future extension`));
+    }
+    const patchSelections = graphSelections.filter((candidate) => candidate.pnpmPatches.length > 0);
+    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());
+    await withPreparedRegistryArtifacts({
+        artifacts: [...graph.items.values()],
+        entryItems: [primary.name],
+        itemByReference: graph.itemByReference,
+        run: async (entries) => {
+            const tree = await resolveRegistryItems(entries, { config });
+            if (!tree) {
+                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 rootDependencyChanges = await inspectRootDependencies(cwd, tree);
+            const disclosedPackageChanges = [
+                ...packageChanges,
+                ...rootDependencyChanges,
+            ];
+            const shadcnEffects = describeShadcnEffects(tree, graph.items.values());
+            info([
+                `Registry item: ${primary.name}`,
+                "Files:",
+                ...fileChanges.map((change) => `  ${change.status}: ${change.target} (${change.kind})`),
+                "Package entries:",
+                ...disclosedPackageChanges.map((change) => `  ${change.status}: ${change.cwd} ${change.name} = ${change.specifier}`),
+                ...(compatibilityAssumptions.length > 0
+                    ? [
+                        "Compatibility assumptions:",
+                        ...compatibilityAssumptions.map((assumption) => `  ${assumption}`),
+                    ]
+                    : []),
+                ...(shadcnEffects.length > 0
+                    ? [
+                        "Additional ShadCN effects:",
+                        ...shadcnEffects.map((effect) => `  ${effect}`),
+                    ]
+                    : []),
+            ].join("\n"));
+            await confirmChanges(fileChanges, disclosedPackageChanges, options, dependencies.confirm ?? confirm);
+            await addRegistryItemsQuietly(entries, {
+                config,
+                cwd,
+                overwrite: options.overwrite === true ||
+                    fileChanges.some((change) => change.kind === "registry file" && change.status === "changed"),
+            });
+            const changedPackageEntries = packageChanges
+                .filter((change) => change.status !== "identical")
+                .map(({ status: _status, actual: _actual, ...requirement }) => requirement);
+            await applyPackageEntries(cwd, changedPackageEntries);
+            if (changedPackageEntries.length > 0) {
+                if (dependencies.install) {
+                    await dependencies.install(cwd);
+                }
+                else {
+                    await runCommand("pnpm", ["install"], { cwd });
+                }
+            }
+        },
+    });
+    success(`Added ${primary.name}.`);
+}

package/dist/composition/catalog.d.ts

@@ -0,0 +1,26 @@
+import { getRegistryItems } from "shadcn/registry";
+import type { RegistryItem } from "shadcn/schema";
+import type { CatalogSelection, RegistriesConfig, SourceRegistryCatalog } from "./types.js";
+export declare function resolveRegistryItemGraph(catalog: SourceRegistryCatalog, entryItems: string[]): string[];
+export type RegistryItemGraph = {
+    fetchedItemNames: Set<string>;
+    itemByReference: Map<string, string>;
+    items: Map<string, RegistryItem>;
+};
+export declare function fetchRegistryItemGraph(options: {
+    config: RegistriesConfig;
+    cwd: string;
+    fetchItems?: typeof getRegistryItems;
+    itemByReference?: Map<string, string>;
+    items?: Iterable<RegistryItem>;
+    references: Iterable<string>;
+    repository?: string;
+}): Promise<RegistryItemGraph>;
+export declare function loadSourceRegistryCatalog(cwd: string, registryFile?: 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

@@ -0,0 +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;AA2KpB,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,CA8ChC;AAED,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,qBAAqB,EAC9B,SAAS,EAAE,MAAM,GAChB,gBAAgB,CASlB"}