create-next-hydra 0.3.0 → 0.4.1

package/README.md

@@ -1,6 +1,6 @@
 # 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-next-hydra` composes applications from selected Providers and compatible Add-ons. There is one shared web application: CMS is required, Auth is optional, and Commerce requires Auth. Commerce is installed as one complete package, not separately selectable catalog, cart, or checkout features. It uses [ShadCN registry items](https://ui.shadcn.com/docs/registry/registry-item-json) to copy code and adds stack validation and package-specific manifest changes.
 
 ## Create a project
 
@@ -10,67 +10,160 @@ Interactive scaffolding asks for every required Provider:
 pnpm dlx create-next-hydra@latest my-project
 ```
 
-For a non-interactive scaffold, provide all three Providers or a Preset:
+Search is an optional Provider Slot. Selecting Algolia adds the storefront search pages, header autocomplete, proxy runtime, and `search` CLI command through registry recipes; it currently requires Commerce. CMS-only sites omit Search. The local navigation-search add-on is an alternative header binding and cannot be selected alongside Algolia.
+
+For a non-interactive scaffold, select a Provider or explicitly omit each optional slot, or use a Preset:
 
 ```bash
 pnpm dlx create-next-hydra@latest my-project --yes \
   --auth workos \
   --cms drupal \
-  --commerce commercetools
+  --commerce commercetools \
+  --search algolia
 
 pnpm dlx create-next-hydra@latest my-project --yes --preset standard
+
+pnpm dlx create-next-hydra@latest content-site --yes \
+  --cms contentstack --without auth --without commerce --without search
 ```
 
 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.
+Use `--repo-url <repository>` to scaffold from another Git repository and `--ref <revision>` to select a revision. Local repository paths, including `--repo-url .`, resolve from the directory where you invoke the command. Scaffolding reads the committed revision, not uncommitted source edits.
 
-## Change the maintainer workspace
+After installation, the CLI prints setup instructions supplied by the selected registry items. Follow those instructions before starting the application; composition does not run external provisioning commands for you.
 
-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:
+The project destination must be missing or empty. Named workspaces support safe initialization and updates instead. New applications retain the registry's existing `vercel.json` defaults and app-local skip-CI scripts. Maintainer composition commands and cache-location settings are not added to these files.
 
-```bash
+Projects include Portless. Run `pnpm dev` in the installed project for stable `<app>.<project>.localhost` origins and automatically allocated application ports. The package name is normalized from the destination name without renaming the folder: `My App` becomes `my-app`. The project hostname label also replaces dots/underscores with hyphens and is limited to 63 characters. Package-owned dev scripts, including API tunneling, remain intact. Local HTTPS may require Portless's one-time proxy/certificate setup; remote authentication callback allowlists must match the actual development origins. Drupal's `dev:web` command keeps Portless while pinning the internal frontend port for DDEV revalidation.
+
+## Initialize and update named workspaces
+
+The preferred maintainer workflow uses definitions in `workspaces/`. New definitions are visible to Git before being committed; no parent ignore exception is needed. Compose seeds a missing workspace-local `.gitignore` with defaults that expose settings and hide materialized output, then leaves that file under your control. An existing file, including an empty one, is never replaced. No `apps` field or app-profile flag is needed: the shared web application is implicit, and selected packages extend its templates.
+
+```sh
+pnpm --filter create-next-hydra compose cms-contentstack --copy-env
+pnpm --filter create-next-hydra compose cms-contentstack
+pnpm --filter create-next-hydra compose --all --copy-env
+pnpm --filter create-next-hydra compose cms-contentstack --watch
+pnpm --filter create-next-hydra compose --all --check
+pnpm --filter create-next-hydra compose cms-contentstack --explain 'apps/web/app/[locale]/layout.tsx'
+pnpm --dir workspaces/cms-contentstack typecheck
+pnpm --dir workspaces/cms-contentstack dev
+```
+
+The same command initializes or updates the same folder. All files are physical copies, including ordinary source and template output. Refresh preserves caches and does not reinstall unchanged dependencies. Unowned local files remain untouched and do not block refresh or `--check`. Conflicting edits to managed files and unowned files occupying new output targets still block changes. `--diff` lists eligible unowned files for optional reconciliation without adopting them. `--no-install` lets you manage installation yourself with pnpm inside the workspace, `--offline` uses the local store, and `--copy-env` explicitly copies only missing local env files. Omit it for deployment. Watch uses the same synchronization and installation policy on every refresh; it does not run an application server. External provisioning is separate.
+
+`--check` verifies that composed files match the current definition and source. It does not inspect `.npmrc` or installed dependencies, and it does not run pnpm. A files-only composition can pass Check before dependencies are installed. Install dependencies separately before running application commands.
+
+See [Named workspaces](../../workspaces/README.md) for the four definitions, stable Portless hostnames, deployment settings, interruption recovery, and reconciliation instructions. Definitions, workspace-owned `.gitignore` files, optional READMEs, app-local `vercel.json` settings are tracked; materialized runtime manifests, installed files and applied state are ignored. Compose preserves these ignore rules rather than regenerating them. The workspace name determines each Next app's `<app>.<workspace>.localhost` hostname (with Portless's branch prefix inside a Git worktree).
+
+Adding a definition or changing its selection requires no task-inventory synchronization. Compose it, then run Turbo inside its installed workspace. Deployments compose directly and use ordinary application-task caching. The source checkout's pnpm workspace declarations still supply canonical package discovery. A filtered tooling install can omit source application dependencies; see [application-root caching](../../workspaces/README.md#application-root-caching).
+
+## Command boundaries
+
+- `create-next-hydra <directory>` creates a project. It acquires the requested source revision in a temporary directory, constructs only selected files and hands over ordinary copied source. There is no ongoing composition step.
+- `create-next-hydra compose <name>` initializes or refreshes a named workspace from canonical source. Application source is always copied. `compose --all` covers Git-visible definitions, including new untracked ones; `compose --all --check` checks their local state.
+- `create-next-hydra add <item>` adds registry items to an existing project.
+
+The source checkout contains canonical modules, templates and registry ownership; runnable applications live in named workspaces. `--explain <file>` shows the selected owner and edit location without updating. Compose explicitly before running application tasks inside the workspace's own Turbo graph. Root `pnpm test` runs package/provider suites and composition checks from source, with common app integration tests only in that WorkOS + Contentstack + commercetools reference; root build/typecheck target the composition CLI. Project creation and named composition share preparation for the baseline, selected files, dependency closure, registry transformations, templates, aliases and patches. Scaffolding owns source acquisition and Git initialization; named composition owns safe refresh and local change inspection.
+
+## Deploy a named workspace
+
+Deploy the same named folder used for development:
+
+```sh
+pnpm --filter create-next-hydra compose storefront-contentstack
+pnpm --dir workspaces/storefront-contentstack exec turbo run build --filter=web
+```
+
+Named composition uses the same application task configuration as project creation. Source, dependency and environment changes invalidate caches; unchanged inputs can restore prior outputs. Host-specific cache placement belongs in the build invocation, not a different generated Turbo configuration. Portless remains installed; named workspaces retain optional `development.port`; source credentials are copied only with explicit `--copy-env`. Existing destination environment files are preserved, not scrubbed.
+
+Put selections in `next-hydra.json`. Compose updates that named folder and preserves caches automatically. Use the root creation command for a new application. See [Vercel configuration and installation order](../../workspaces/README.md#deploy-a-composed-application).
+
+## Local source authoring and environment files
+
+Use a named definition and `compose <name>` for local development. Add `--copy-env` when you want to initialize missing environment files from your checkout.
+
+Each workspace has its own manifests, lockfile, dependencies and physical application files. Canonical modules, template output and third-party registry content use the same materialization as scaffolded projects. Provider aliases and application runtime aliases resolve inside that workspace; no maintainer-only resolution layer is installed.
+
+With `--copy-env`, ignored local environment files named `.env` or `.env.*` are copied into matching materialized paths. The primary checkout supplies defaults; the current worktree takes precedence. Copies have owner-only permissions (`0600`). Existing destination files are preserved; occupied non-file destinations are rejected before copying; dependency/build directories and example files are excluded. Contents are never printed or recorded in ownership state or Git snapshots. Composition does not seed values from examples: provisioning owns that. These are local credentials, not distribution assets, and unused capability credentials inside a selected env file are not filtered out.
+
+Provider-owned application files are copied from their canonical registry sources. Use `--explain <file>` when the edit location is unclear, edit that source, then refresh. Selection changes never rewrite tracked source applications or manifests.
+
+Authoring constraints:
+
+- New files and edits to physical copies are **work to preserve**. Named workspaces provide `compose --check`, but adoption remains manual. Reconcile changes into canonical source and registry ownership, run `pnpm registry:sync` and `pnpm registry:check`, then refresh and verify the same workspace. Preserve unreconciled output until this is done; applied state is not a backup.
+- Refresh the same workspace after changing selections, templates, or dependency manifests. Failed updates preserve before/after fingerprints and can be retried after resolving the reported issue.
+
+Named workspaces maintain `.workspace-composition.json` ownership fingerprints for safe refresh and save a private Git snapshot outside the application: `compose <name> --diff` shows local edits, deletions and unregistered files, while `--explain` without a filename lists selected files and their canonical edit locations. See [Inspect workspace changes](../../workspaces/README.md#inspect-workspace-changes) for the authoring workflow and exclusions. This is not application runtime input. Project creation retains no receipt, private snapshot or source-root metadata and requires no ongoing generation step.
+
+## Verification
+
+The implementation uses one shared planner and module-reference renderer. Composition recipes bind normal modules into shared templates; materialized modules have ordinary filenames. The CLI builds with its own pinned TypeScript compiler rather than depending on a root-level executable.
+
+Composition lint runs optional package `lint:prepare` scripts in its disposable workspace before checking types. Use these for local generated modules, such as the Drupal Canvas component registry; they must not require credentials or provision external services.
+
+Run the bounded local suite before accepting composition changes:
+
+```sh
 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
+pnpm --filter create-next-hydra test --maxWorkers 2 --testTimeout 30000
+pnpm registry:check
+node packages/create-next-hydra/dist/cli.js compose --all --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.
+The suite checks materialization, template ownership and path collisions, working-tree deletions, environment isolation, overwrite refusal, installation recovery, observation and package closure through the workspace and CLI boundaries. Install-heavy E2E tests use the executable to create independent applications and need sufficient local disk/store capacity. Filesystem paths are trusted; ownership checks are not a sandbox for hostile package lifecycle scripts or concurrent directory mutation. See the [implementation guide](src/README.md) for services, state, packaging exercises and platform limits.
+
+Live watcher fixtures resolve their temporary root with `FileSystem.realPath` before deriving source and application paths. Preserve this when adding fixtures: on macOS, `/var/folders/...` can refer to the same directory as `/private/var/folders/...`, while native watcher events use the physical path. Comparing these different path strings can discard valid events and cause timeouts. If watcher tests time out, check the fixture root and reported event paths before increasing timeouts or attributing the failure to a code change. The normal test command requires no `TMPDIR` override.
+
+Whole-package and exact-route materialization are covered by local tests. Named-workspace tests also cover template refresh, dependency retry, local-edit protection, unregistered files and interruption recovery. Fresh external provisioning, hosted authentication, payment journeys and production builds remain separate integration gates. `compose --check` reports reconciliation work; automatic adoption is not implemented.
 
-## Add code to a customer workspace
+## Add code to your project
 
-Run `add` from an existing customer-owned workspace:
+Run `add` from an existing project:
 
 ```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.
+The command inspects the complete registry graph, checks known Provider requirements against installed aliases, and discloses compatibility assumptions it cannot prove without selection state. Inspection and execution retain the same artifacts and recheck project preconditions. ShadCN performs native installation in the existing project; Hydra then reconciles package-local requirements. Configuration-dependent changes need an explicitly configured ShadCN context: the CLI does not invent a workspace-root `components.json` or CSS configuration. Like ShadCN, `--yes` skips confirmation prompts and `--overwrite` authorizes replacing changed targets. `--yes` alone never approves replacing code or dependency versions. Dependency-bearing additions install on every explicit invocation, including retries. Addition has no project lock, receipt or composition snapshot. A native operation or installation failure may leave changes; inspect them before retrying rather than assuming rollback.
+
+`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 named workspace or during a new scaffold.
+
+After a successful addition, the CLI prints setup instructions from the installed item and its registry dependencies.
 
-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, Recipe or Add-on
 
-## Author a Provider or Add-on
+Commerce's registry item depends on the composition recipes `commerce-web`, `commerce-api`, and `commerce-admin`. These wire the complete Commerce package into other applications; they are not independent shopping-feature choices. Auth owns its provider routes and its Commerce identity/webhook recipe. No application profile or separate web shell is required. The planner includes `app-web` automatically; the shared constructor includes only selected applications and their package dependency closure. Unselected source never enters the destination.
+
+Recipe describes an assembly unit, not its size: recipes can depend on smaller recipes through `registryDependencies`. A recipe may install files and dependencies, bind module exports into template slots, or combine these. The individual placements are **slot bindings**, not separate recipes. Provider-specific **provisioning recipes**, such as Drupal configuration or Contentstack content blocks, configure external systems in a separate provisioning step. Composition can include their files but never executes them.
 
 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;
+- its stable ID and whether it is a Provider, Package, Recipe, Add-on, or Preset;
 - 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;
+- an optional `binding.sourcePath` for resolving a Provider to its package inside the materialized workspace;
+- `providerDependencies` for packages installed by the selection that consume a Provider Slot;
 - standard ShadCN `registryDependencies` for any other registry items it needs;
+- conditional dependencies for recipes activated by occupied Provider Slots;
+- `providerSlots` requirements on a Package or Recipe, such as Commerce requiring Auth;
 - required and conflicting selection IDs;
 - ordinary exact package entries;
-- exact pnpm patch entries and their patch-file assets; and
+- exact pnpm patch entries and their patch-file assets;
+- composition templates, named insertion slots, and ordered slot bindings;
+- selection-owned TypeScript aliases needed for composed modules to resolve inside the workspace;
 - 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.
+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 `add`, while named `compose` copies their canonical sources and may remove or replace unchanged owned targets when the selected stack changes.
+
+A composition recipe may instead reference ordinary files already authored in the destination app, as `commerce-web` does for Checkout. Its colocated app registry declares those files, and the owning package depends on that item. This preserves direct source authoring without making duplicate route templates or using unsupported parent-directory registry paths.
 
-Run these commands after adding, moving, or removing contribution files:
+Run these commands after adding, moving, or removing registry-owned files:
 
 ```bash
 pnpm registry:sync
@@ -81,6 +174,12 @@ pnpm registry:check
 
 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`.
 
+Project creation and named `compose` record those standard dependency fields through the same manifest logic before the final package install, including with `--no-install`. Only selected registry items and their transitive dependencies participate. Bare package names preserve existing requirements; a new bare name uses `latest` until installation resolves it. Explicit versions, tags, and named aliases are preserved, and conflicting explicit requirements fail during preparation. URL or local-path requirements must include a package name (`name@specifier`); unnamed sources cannot be resolved in an install-free plan. `add` continues to use ShadCN's dependency installer.
+
+Use `meta.composition.templates` for shared-file structure and `meta.composition.slotBindings` for references to ordinary module exports. This renderer is shared by `compose` and initial scaffolding. Modules remain normal TypeScript/TSX source, and targets have ordinary filenames with no ongoing generation step in scaffolded projects. A selection may declare `typeScriptAliases` for application-level module overrides that must persist in both named and scaffolded workspaces. Both target and alias are catalog-governed. `add` rejects composition recipes and template recomposition because it cannot safely regenerate files you may have edited.
+
+Contentstack declares `conditionalDependencies: [{ providers: ["commerce"], items: ["cms-contentstack-commerce"] }]`; Drupal uses `cms-drupal-commerce` in the same way. These `kind: "recipe"` items connect the selected CMS to Commerce core, not to a specific Commerce provider. They install the CMS mapping and `@repo/commerce` dependency automatically when both capabilities are selected, rather than exposing product collection as a selectable Add-on. Registry discovery fetches possible recipes, while planning installs only applicable ones. Contentstack's `recipe/recipes/product-collection.json` remains a feature-specific provisioning recipe: the provisioning command applies it to the base content type and seed entry before importing the stack.
+
 A Provider declares its installable package once:
 
 ```json
@@ -93,7 +192,7 @@ A Provider declares its installable package once:
 }
 ```
 
-An Add-on that contributes a package which imports the selected CMS declares the consumer, not a concrete CMS package:
+An Add-on that installs a package which imports the selected CMS declares the consumer, not a concrete CMS package:
 
 ```json
 {
@@ -108,7 +207,7 @@ An Add-on that contributes a package which imports the selected CMS declares the
 }
 ```
 
-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.
+Scaffold and `compose` 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`, resolving source inside the materialized project. These aliases are identical in named and scaffolded workspaces. 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; named `compose --check` reports changed or stale physical configuration. `add`, which has no retained selection receipt, copies the exact Provider alias already present in `apps/web/package.json` into each installed 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.
 
@@ -116,7 +215,7 @@ ShadCN registry mappings, including private registry URLs and environment-backed
 
 ## 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.
+- The official registry requires CMS. Auth is optional; Commerce requires Auth. A source catalog must include the shared `app-web` item.
+- A scaffolded project has no composition receipt and cannot be automatically upgraded or switched later.
+- Composition installs local code and JavaScript dependencies. External service setup runs separately through explicit provider administration commands or manual setup; composition never provisions remote systems.
 - Selection Definitions are declarative and cannot run arbitrary hooks.

package/dist/add-command.d.ts

@@ -0,0 +1,11 @@
+import { Stdio } from "effect";
+import { Command, Prompt } from "effect/unstable/cli";
+import { AdditionConflict } from "./addition.ts";
+import { InvalidComposition } from "./errors.ts";
+import { Workspaces } from "./workspaces.ts";
+export declare const addCommand: (cwd: string) => Command.Command<"add", {
+    readonly overwrite: boolean;
+    readonly reference: string;
+    readonly yes: boolean;
+}, {}, InvalidComposition | import("./errors.ts").RegistryFailure | import("./errors.ts").StagingRetained | import("./errors.ts").DependencyInstallationFailed | import("effect/Schema").SchemaError | import("effect/PlatformError").PlatformError | import("./addition.ts").AdditionChanged | AdditionConflict | import("./addition.ts").AdditionFailed | import("effect/Terminal").QuitError, Workspaces | Stdio.Stdio | Prompt.Environment>;
+//# sourceMappingURL=add-command.d.ts.map

package/dist/add-command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"add-command.d.ts","sourceRoot":"","sources":["../src/add-command.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmB,KAAK,EAAE,MAAM,QAAQ,CAAC;AAChD,OAAO,EAAY,OAAO,EAAQ,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAEtE,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE7C,eAAO,MAAM,UAAU,GAAI,KAAK,MAAM;;;;+aAmGmC,CAAC"}

package/dist/add-command.js

@@ -0,0 +1,75 @@
+import { Console, Effect, Stdio } from "effect";
+import { Argument, Command, Flag, Prompt } from "effect/unstable/cli";
+import { AdditionConflict } from "./addition.js";
+import { InvalidComposition } from "./errors.js";
+import { Workspaces } from "./workspaces.js";
+export const addCommand = (cwd) => Command.make("add", {
+    overwrite: Flag.Boolean("overwrite").pipe(Flag.withAlias("o"), Flag.withDefault(false), Flag.withDescription("Replace changed files and package entries.")),
+    reference: Argument.String("reference").pipe(Argument.withDescription("Registry item URL, namespaced reference or local JSON file.")),
+    yes: Flag.Boolean("yes").pipe(Flag.withAlias("y"), Flag.withDefault(false), Flag.withDescription("Skip confirmation prompts; does not permit replacement.")),
+}, (options) => Effect.gen(function* () {
+    const workspace = yield* (yield* Workspaces).existing({ root: cwd });
+    const inspection = yield* workspace.inspectAdd({
+        reference: options.reference,
+    });
+    for (const assumption of inspection.assumptions) {
+        yield* Console.warn(assumption);
+    }
+    if (inspection.environment.length) {
+        yield* Console.warn(`Registry environment defaults may be added by ShadCN: ${inspection.environment.join(", ")}`);
+    }
+    const changes = [
+        ...inspection.files.map((file) => ({ ...file, label: file.target })),
+        ...inspection.packages.map((entry) => ({
+            ...entry,
+            label: `${entry.target}: ${entry.section}.${entry.name}`,
+        })),
+    ];
+    for (const change of changes) {
+        yield* Console.log(`${change.status}: ${change.label}`);
+    }
+    const conflicts = changes.filter((change) => change.status === "changed");
+    let { overwrite } = options;
+    if (options.yes) {
+        if (conflicts.length && !overwrite) {
+            return yield* new AdditionConflict({
+                paths: conflicts.map((change) => change.label),
+            });
+        }
+    }
+    else {
+        const stdio = yield* Stdio.Stdio;
+        if (!(yield* stdio.stdinIsTerminal) ||
+            !(yield* stdio.stdoutIsTerminal)) {
+            return yield* new InvalidComposition({
+                message: "Addition requires confirmation. Use --yes for noninteractive installation and --overwrite only to permit replacements.",
+            });
+        }
+        if (!overwrite) {
+            for (const conflict of conflicts) {
+                if (!(yield* Prompt.Confirm({
+                    initial: false,
+                    message: `Replace ${conflict.label}?`,
+                }))) {
+                    return;
+                }
+            }
+            overwrite = conflicts.length > 0;
+        }
+        if (!(yield* Prompt.Confirm({
+            initial: false,
+            message: "Install this registry item and its dependencies?",
+        }))) {
+            return;
+        }
+    }
+    const result = yield* workspace.add({
+        expected: inspection.precondition,
+        overwrite,
+        reference: options.reference,
+    });
+    yield* Console.log("Registry item installed.");
+    for (const instruction of result.instructions) {
+        yield* Console.log(`${instruction.item}:\n${instruction.text}`);
+    }
+})).pipe(Command.withDescription("Add a registry item to this project."));

package/dist/addition.d.ts

@@ -0,0 +1,67 @@
+import { Effect, FileSystem, Path, Schema } from "effect";
+import { InvalidComposition } from "./errors.ts";
+import type { PackageRequirement } from "./packages.ts";
+import { Shadcn } from "./shadcn.ts";
+import { WorkspaceDependencies } from "./workspace-dependencies.ts";
+declare const AdditionChanged_base: Schema.Class<AdditionChanged, Schema.TaggedStruct<"AdditionChanged", {}>, import("effect/Cause").YieldableError>;
+export declare class AdditionChanged extends AdditionChanged_base {
+    readonly message = "The registry or project changed after inspection. Inspect the addition again before applying it. No installation was started.";
+}
+declare const AdditionConflict_base: Schema.Class<AdditionConflict, Schema.TaggedStruct<"AdditionConflict", {
+    readonly paths: Schema.$Array<Schema.String>;
+}>, import("effect/Cause").YieldableError>;
+export declare class AdditionConflict extends AdditionConflict_base {
+    get message(): string;
+}
+declare const AdditionFailed_base: Schema.Class<AdditionFailed, Schema.TaggedStruct<"AdditionFailed", {
+    readonly diagnostic: Schema.Redacted<Schema.String>;
+    readonly directory: Schema.String;
+    readonly phase: Schema.Literals<readonly ["registry", "packages"]>;
+}>, import("effect/Cause").YieldableError>;
+export declare class AdditionFailed extends AdditionFailed_base {
+    get message(): string;
+}
+export interface AddRequest {
+    readonly reference: string;
+    readonly overwrite: boolean;
+    readonly expected?: string;
+}
+export interface AddInspection {
+    readonly assumptions: readonly string[];
+    readonly environment: readonly string[];
+    readonly files: readonly {
+        readonly target: string;
+        readonly status: "create" | "identical" | "changed";
+    }[];
+    readonly packages: readonly (Omit<PackageRequirement, "specifier"> & {
+        readonly status: "create" | "identical" | "changed";
+    })[];
+    readonly precondition: string;
+}
+export declare const existingWorkspace: (root: string) => Effect.Effect<{
+    add: (request: AddRequest) => Effect.Effect<{
+        directory: string;
+        files: {
+            readonly target: string;
+            readonly status: "create" | "identical" | "changed";
+        }[];
+        instructions: readonly import("./model.ts").RegistryInstruction[];
+    }, InvalidComposition | import("./errors.ts").RegistryFailure | import("./errors.ts").StagingRetained | import("./errors.ts").DependencyInstallationFailed | Schema.SchemaError | import("effect/PlatformError").PlatformError | AdditionChanged | AdditionConflict | AdditionFailed, never>;
+    inspectAdd: (request: {
+        readonly reference: string;
+    }) => Effect.Effect<{
+        assumptions: string[];
+        environment: string[];
+        files: {
+            readonly target: string;
+            readonly status: "create" | "identical" | "changed";
+        }[];
+        packages: (Omit<PackageRequirement, "specifier"> & {
+            readonly status: "create" | "identical" | "changed";
+        })[];
+        precondition: string;
+    }, InvalidComposition | import("./errors.ts").RegistryFailure | Schema.SchemaError | import("effect/PlatformError").PlatformError, never>;
+}, never, FileSystem.FileSystem | Path.Path | Shadcn | WorkspaceDependencies>;
+export type ExistingWorkspace = Effect.Success<ReturnType<typeof existingWorkspace>>;
+export {};
+//# sourceMappingURL=addition.d.ts.map

package/dist/addition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"addition.d.ts","sourceRoot":"","sources":["../src/addition.ts"],"names":[],"mappings":"AAEA,OAAO,EAEL,MAAM,EACN,UAAU,EAEV,IAAI,EAEJ,MAAM,EACP,MAAM,QAAQ,CAAC;AAEhB,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAGjD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAGxD,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAErC,OAAO,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAC;;AAEpE,qBAAa,eAAgB,SAAQ,oBAGpC;IACC,QAAQ,CAAC,OAAO,mIACkH;CACnI;;;;AACD,qBAAa,gBAAiB,SAAQ,qBAGrC;IACC,IAAI,OAAO,WAEV;CACF;;;;;;AACD,qBAAa,cAAe,SAAQ,mBAOnC;IACC,IAAI,OAAO,WAEV;CACF;AACD,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AACD,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC,QAAQ,CAAC,KAAK,EAAE,SAAS;QACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QACxB,QAAQ,CAAC,MAAM,EAAE,QAAQ,GAAG,WAAW,GAAG,SAAS,CAAC;KACrD,EAAE,CAAC;IACJ,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC,IAAI,CAAC,kBAAkB,EAAE,WAAW,CAAC,GAAG;QACnE,QAAQ,CAAC,MAAM,EAAE,QAAQ,GAAG,WAAW,GAAG,SAAS,CAAC;KACrD,CAAC,EAAE,CAAC;IACL,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAoND,eAAO,MAAM,iBAAiB;;;;6BA3NT,MAAM;6BACN,QAAQ,GAAG,WAAW,GAAG,SAAS;;;;;4BAoZT,MAAM;;;;;6BArZ/B,MAAM;6BACN,QAAQ,GAAG,WAAW,GAAG,SAAS;;;6BAGlC,QAAQ,GAAG,WAAW,GAAG,SAAS;;;;6EAghBrD,CAAC;AAEH,MAAM,MAAM,iBAAiB,GAAG,MAAM,CAAC,OAAO,CAC5C,UAAU,CAAC,OAAO,iBAAiB,CAAC,CACrC,CAAC"}