components-differ 1.2.1 → 1.2.2

package/README.md

@@ -1,31 +1,106 @@
-# ShadCN Project Differ
+# components-differ
 
-This CLI tool figures out the difference between the initial commit of a ShadCN project and the current state of the project and creates a new ShadCN JSON output file with the changes. This ShadCN JSON file can then be used with the ShadCN CLI to generate a new project or add to an existing project.
+`components-differ` is a CLI that inspects a Shadcn-based project and emits a [registry-item](https://ui.shadcn.com/docs/registry/registry-item-json) compatible JSON bundle. The generated bundle captures only the delta between the project’s initial template commit and the current working tree, making it easy to distribute curated component packs or bootstrap new installations.
 
-# Steps
+## Features
 
-1. Create a new NextJS app
-2. Add ShadCN to the app
-3. Create a new initial commit; `rm -fr .git && git init && git add . && git commit -m "Initial commit"` or `npx components-differ --init`
-4. Make your updates to the project
-5. Run the CLI tool; `npx components-differ`
+- ⚡️ **Quick diffing** – Scans the git history to compare the initial commit against the current state of the repository.
+- 🧠 **Alias aware** – Understands `components.json` aliases and supports projects with or without a `src/` directory.
+- 📦 **Full registry support** – Outputs files using the latest Shadcn registry types (`registry:ui`, `registry:block`, `registry:page`, `registry:file`, `registry:theme`, etc.).
+- 🧩 **Automated dependency detection** – Detects new npm dependencies/devDependencies introduced since the initial commit.
+- 🛠️ **Build+publish ready** – Includes a reproducible build step, release helpers, and Vitest coverage.
 
-The reason we are recreating the initial commit is so that the resulting JSON output is only the changes to the project after ShadCN was added, and not the entire project history.
+## Installation
 
-You can then take the resulting JSON ouput and host it on a URL, then use that with the ShadCN CLI to generate a new project or add to an existing project.
+```bash
+pnpm install components-differ
+# or
+npm install components-differ
+# or
+yarn add components-differ
+```
+
+For one-off usage you can run the CLI with `npx`:
+
+```bash
+npx components-differ
+```
+
+## Usage
+
+### 1. Prepare your project
+
+1. Scaffold a new Next.js application.
+2. Install [shadcn/ui](https://ui.shadcn.com/docs/components).
+3. Commit the pristine template so that the first commit represents the baseline.
+
+You can use the built-in init helper to automate step 3:
 
 ```bash
-npx shadcn@latest init http://your-json-output-url
+npx components-differ --init
 ```
 
-You can use the `--src-dir` flag if you want to use the `src` directory in your project.
+This command wipes the current `.git` folder, initializes a new repository, creates an initial commit, and provisions a sensible `.gitignore`.
+
+### 2. Make changes
+
+Add or modify components, hooks, utilities, env files, Tailwind styles, or any other project files.
 
-Or you can add the JSON output to an existing project:
+### 3. Generate the registry diff
 
 ```bash
-npx shadcn@latest add http://your-json-output-url
+npx components-differ
 ```
 
-# Why is this useful?
+The CLI prints a JSON payload describing:
+
+- File list with appropriate registry types and targets.
+- New registry dependencies detected in your component directory.
+- Added npm dependencies and devDependencies.
+
+You can pipe this JSON to a file or publish it to a URL and consume it with the official Shadcn CLI:
+
+```bash
+npx shadcn@latest init https://your-domain.com/registry.json
+npx shadcn@latest add https://your-domain.com/registry.json
+```
+
+## CLI Options
+
+| Flag | Description |
+| ---- | ----------- |
+| `--name <name>` | Overrides the generated registry item `name`. Defaults to the current folder name. |
+| `--init` | Re-initializes git and creates the baseline commit described above. |
+
+## Development
+
+```bash
+pnpm install      # install dependencies
+pnpm test         # run Vitest suite (snapshot + unit tests)
+pnpm run build    # build the distributable into dist/
+pnpm run release  # build, test, and publish (requires npm auth + clean git tree)
+```
+
+The project relies on git worktrees to obtain the baseline commit, so ensure your repository has at least one commit before running the CLI in development.
+
+## How It Works
+
+1. **Worktree clone** – `scanForAlteredFiles` creates a temporary git worktree of the initial commit.
+2. **File classification** – `parseFilePath` maps files to Shadcn registry types (page, ui, block, theme, style, lib, hook, file, item) while honoring `components.json` aliases and `src/` directory layouts.
+3. **Manifest parsing** – `readComponentsManifest` reads alias definitions and determines whether the project uses `src/`.
+4. **Dependency diff** – `createDiff` compares the current `package.json` with the baseline to capture dependency changes.
+5. **Output assembly** – Files, registry dependencies, metadata, Tailwind placeholders, and CSS variables are assembled into a registry item schema.
+
+## Releasing
+
+1. Update `package.json` version (use `pnpm node ./scripts/bump-version.mjs` for a patch bump).
+2. Ensure the working tree is clean.
+3. Run `pnpm run release` to build, test, and publish to npm.
+
+## Contributing
+
+Pull requests are welcome! Please accompany feature changes with unit tests or snapshot updates as appropriate. If you’re unsure where files are classified or need new registry types, check `src/parse-file-path.mjs` and corresponding tests under `tests/tests`.
+
+## License
 
-This allows library maintainers or SaaS services to create a one step installer for their library or service into an existing project, or to bootstrap a new project with the library or service.
+MIT © Components Host

package/dist/src/parse-file-path.mjs

@@ -52,8 +52,8 @@ export function parseFilePath(wasInSrcDir, config, filePath, content) {
     out.type = "registry:component";
     out.target = undefined;
   } else {
-    out.type = "registry:item";
-    out.target = undefined;
+    out.type = "registry:file";
+    out.target = `./${sanitizedTargetPath}`;
   }
 
   if (out.type === "registry:example") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "components-differ",
-  "version": "1.2.1",
+  "version": "1.2.2",
   "description": "Simple CLI to create Shadcn components from project",
   "type": "module",
   "main": "dist/index.mjs",