components-differ 1.0.17 → 1.2.0

package/README.md

@@ -1,206 +1,31 @@
-# components-differ
+# ShadCN Project Differ
 
-`components-differ` is a companion CLI for shadcn/ui projects. It compares the current state of a codebase to its initial shadcn scaffold, then emits an installable registry entry that captures only the changes you made. You can pipe that output straight into the official shadcn CLI to bootstrap new projects, patch existing installs, or maintain a fully fledged custom registry.
+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.
 
-## Features
+# Steps
 
-- Generates shadcn-compatible registry items from real projects
-- Detects component dependencies based on the latest shadcn/ui catalog
-- Understands both `src/` and app-root layouts
-- Skips built-in primitives so the diff contains only custom code
-- Creates or updates `registry.json` in-place (schema: [`registry.json`](https://ui.shadcn.com/docs/registry/registry-json))
-- Supports environment-based configuration for registry metadata
-- Ships with TypeScript types, tests, and build scripts for local development
+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`
 
-## Prerequisites
+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.
 
-- Node.js 18+
-- `pnpm` (recommended) or `npm`
-- A project that has already been initialised with the shadcn CLI
-
-## Installation
-
-Install globally or run via `npx`:
-
-```bash
-pnpm add -g components-differ
-# or
-npx components-differ --help
-```
-
-During local development, clone the repo and install dependencies:
-
-```bash
-git clone https://github.com/componentshost/components-differ.git
-cd components-differ
-pnpm install
-```
-
-## Quick Start
-
-1. Create a fresh Next.js app.
-2. Initialise shadcn/ui (`npx shadcn@latest init`).
-3. Commit the baseline scaffold:
-
-   ```bash
-   rm -fr .git && git init
-   git add .
-   git commit -m "Initial shadcn scaffold"
-   ```
-
-   _Tip: use `npx components-differ --init` to automate the reset + commit._
-
-4. Build out your custom components, hooks, utilities, and pages.
-5. Run the differ:
-
-   ```bash
-   npx components-differ > registry-item.json
-   ```
-
-6. Publish or host the JSON output, then use it with the shadcn CLI:
-
-   ```bash
-   npx shadcn@latest add https://example.com/registry-item.json
-   ```
-
-## CLI Usage
-
-```bash
-npx components-differ [options]
-```
-
-| Option | Description |
-| --- | --- |
-| `-n, --name <name>` | Override the generated item name (defaults to the current directory name). |
-| `--init` | Reset the git repository and recreate the initial commit (useful for fresh scaffolds). |
-| `--registry [path]` | Create or update a `registry.json` file. If no path is provided, `./registry.json` is used. |
-| `--initshadcn [type]` | Configure shadcn/ui for your project. Detects project type automatically; pass `next` or `vite` to force a specific scaffold. |
-
-When `--registry` is omitted, the CLI prints a single registry item (JSON) to stdout. The item includes inferred dependencies, registry dependencies, file payloads, and metadata compatible with the shadcn registry tooling.
-
-### Bootstrapping shadcn/ui
-
-Use `--initshadcn` to apply the official shadcn setup steps for supported frameworks:
-
-```bash
-# Auto-detect (looks at package.json)
-npx components-differ --initshadcn
-
-# Explicit Vite support (adds Tailwind deps, config files, and runs the shadcn CLI)
-npx components-differ --initshadcn vite
-
-# Explicit Next.js support (runs the shadcn CLI in your project)
-npx components-differ --initshadcn next
-```
-
-For Vite projects the command will:
-
-- Add `tailwindcss`, `@tailwindcss/vite`, and `@types/node`
-- Locate the first CSS file imported by the Vite entry file (`src/main.{ts,tsx,js,jsx}`) and replace its contents with the Tailwind entrypoint
-- Inject the required `baseUrl`/`paths` aliases into `tsconfig.json` and `tsconfig.app.json`
-- Overwrite `vite.config.ts` with the recommended configuration (includes Tailwind and path aliases)
-- Run the interactive `shadcn@latest init` command
-
-Next.js projects skip the file edits (Next provides the required Tailwind setup) and go straight to the `shadcn` CLI.
-
-## Working with `registry.json`
-
-Passing `--registry` switches the CLI into registry mode:
-
-```bash
-npx components-differ --registry           # writes ./registry.json
-npx components-differ --registry configs/registry.json
-```
-
-- Existing files are parsed and updated; if the item already exists (matching `name`), it is replaced.
-- New files are created with the official schema URL and project metadata.
-- Parent directories are created automatically.
-
-### Registry metadata
-
-By default the generated file uses:
-
-- `name`: `shadcn`
-- `homepage`: `https://ui.shadcn.com`
-
-Override these values by defining environment variables at runtime:
-
-```bash
-REGISTRY_NAME=acme \
-REGISTRY_HOMEPAGE=https://acme.dev \
-npx components-differ --registry
-```
-
-If the variables are absent, the CLI also reads a `.env` file in the project root:
-
-```
-REGISTRY_NAME=acme
-REGISTRY_HOMEPAGE=https://acme.dev
-```
-
-## Building registry artifacts
-
-Add a script to your `package.json` so you can build the registry payload with the official shadcn toolchain:
-
-```json
-{
-  "scripts": {
-    "registry:build": "shadcn build"
-  }
-}
-```
-
-Then run:
+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 registry:build
+npx shadcn@latest init http://your-json-output-url
 ```
 
-Combine this with the differ to capture changes, sync `registry.json`, and ship ready-to-install artifacts in a single workflow.
-
-## Recommended Workflow
+You can use the `--src-dir` flag if you want to use the `src` directory in your project.
 
-1. Run `pnpm build && pnpm test` to ensure your project is green.
-2. Execute `npx components-differ --registry` to keep `registry.json` current.
-3. Publish the updated registry (via HTTP or a git-backed registry).
-4. Consumers install the latest slice using `npx shadcn@latest add <url>`.
-
-## Development Scripts
-
-| Command | Description |
-| --- | --- |
-| `pnpm build` | Compile TypeScript sources to `dist/`. |
-| `pnpm test` | Run the Vitest suite once. |
-| `pnpm test:watch` | Run tests in watch mode. |
-| `pnpm bump` | Increment the package version (patch) and update `package.json`. |
-| `pnpm registry:build` | Run the shadcn CLI build pipeline (requires `shadcn` CLI). |
-
-During development you can execute the CLI locally:
+Or you can add the JSON output to an existing project:
 
 ```bash
-pnpm build
-node dist/index.js --registry
+npx shadcn@latest add http://your-json-output-url
 ```
 
-Or link it globally:
-
-```bash
-pnpm link --global
-components-differ --help
-```
-
-## Releasing
-
-1. Bump the version: `pnpm bump` (or adjust `package.json` manually).
-2. Rebuild and test: `pnpm build && pnpm test`.
-3. Publish: `npm publish`.
-
-Ensure you are authenticated with an npm account that has publish rights (`npm whoami`).
-
-## Contributing
-
-Contributions are welcome! Please open an issue or pull request with a clear description of the change. Run the full test suite before submitting (`pnpm test`), and include updates to the documentation where relevant.
-
-## License
+# Why is this useful?
 
-MIT © Izet Molla
+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.

package/dist/index.mjs

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import path from "node:path";
+import { program } from "commander";
+
+import { scanForAlteredFiles, scanForFiles, hasSrcDir } from "./src/git.mjs";
+import { readComponentsManifest } from "./src/components.mjs";
+import { createDiff } from "./src/create-diff.mjs";
+import { execSync } from "node:child_process";
+
+
+program.option("-n, --name <name>").option('--init');
+program.parse();
+
+const options = program.opts();
+
+const runCommand = (command) => {
+  try {
+    execSync(command, { stdio: "inherit" });
+  } catch (error) {
+    console.error(`Failed to execute command: ${command}`);
+    process.exit(1);
+  }
+};
+
+const ensureGitignore = () => {
+  const gitignorePath = path.join(process.cwd(), ".gitignore");
+  if (!fs.existsSync(gitignorePath)) {
+    console.log(".gitignore file is missing. Creating one...");
+    const content = `
+/node_modules
+/.pnp
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/versions
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# env files (can opt-in for committing if needed)
+.env*
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts
+`;
+    fs.writeFileSync(gitignorePath, content, "utf8");
+    console.log(".gitignore file created with default rules.");
+  } else {
+    console.log(".gitignore file already exists.");
+  }
+};
+
+const main = () => {
+  if (options.init) {
+    console.log("Initializing git repository for new component");
+    // Cross-platform logic
+    if (process.platform === "win32") {
+      runCommand("rmdir /s /q .git && git init && git add . && git commit -m \"Initial commit\"");
+    } else {
+      runCommand("rm -fr .git && git init && git add . && git commit -m \"Initial commit\"");
+    }
+    ensureGitignore()
+    return;
+  }
+
+  const name = options.name || path.basename(process.cwd());
+
+  const { alteredFiles, specificFiles } = scanForAlteredFiles([
+    "./package.json",
+  ]);
+  const currentFiles = scanForFiles(process.cwd());
+
+  const currentPackageJson = fs.readFileSync("./package.json", "utf-8");
+
+  const config = readComponentsManifest(process.cwd());
+  config.isSrcDir = hasSrcDir(process.cwd());
+
+  const output = createDiff({
+    name,
+    config,
+    alteredFiles,
+    currentFiles,
+    specificFiles,
+    currentPackageJson,
+  });
+
+  console.log(JSON.stringify(output, null, 2));
+};
+
+main();

package/dist/src/components.mjs

@@ -0,0 +1,98 @@
+import path from "node:path";
+import fs from "node:fs";
+
+const WHITELISTED_COMPONENTS = [
+  "accordion",
+  "alert",
+  "alert-dialog",
+  "aspect-ratio",
+  "avatar",
+  "badge",
+  "breadcrumb",
+  "button",
+  "calendar",
+  "card",
+  "carousel",
+  "chart",
+  "checkbox",
+  "collapsible",
+  "command",
+  "context-menu",
+  "table",
+  "dialog",
+  "drawer",
+  "dropdown-menu",
+  "form",
+  "hover-card",
+  "input",
+  "input-otp",
+  "label",
+  "menubar",
+  "navigation-menu",
+  "pagination",
+  "popover",
+  "progress",
+  "radio-group",
+  "resizable",
+  "scroll-area",
+  "select",
+  "separator",
+  "sheet",
+  "skeleton",
+  "slider",
+  "sonner",
+  "switch",
+  "tabs",
+  "textarea",
+  "toast",
+  "toggle",
+  "toggle-group",
+  "tooltip",
+];
+
+export function findComponentFiles(config, originalFiles) {
+  const registryDependencies = [];
+  const compDir = config.ui.replace("@/", config.isSrcDir ? "src/" : "");
+  for (const { path: filePath } of originalFiles) {
+    if (filePath.startsWith(compDir)) {
+      const fileExtension = path.extname(filePath);
+      const fileName = path.basename(filePath, fileExtension);
+      if (
+        (fileExtension === ".tsx" || fileExtension === ".jsx") &&
+        WHITELISTED_COMPONENTS.includes(fileName)
+      ) {
+        registryDependencies.push(path.basename(filePath, fileExtension));
+      }
+    }
+  }
+  return registryDependencies;
+}
+
+export function readComponentsManifest(dir) {
+  const manifestPath = path.join(dir, "./components.json");
+  if (fs.existsSync(manifestPath)) {
+    const config = JSON.parse(fs.readFileSync(manifestPath, "utf-8")).aliases;
+    return config;
+  } else {
+    console.error("Components manifest not found");
+    process.exit(1);
+  }
+}
+
+export function getAliasedPaths(config) {
+  return [
+    config.components.replace("@/", ""),
+    config.utils.replace("@/", ""),
+    config.ui.replace("@/", ""),
+    config.lib.replace("@/", ""),
+    config.hooks.replace("@/", ""),
+  ];
+}
+
+export function isBuiltinComponent(config, filePath) {
+  if (filePath.startsWith(config.ui.replace("@/", ""))) {
+    const component = path.basename(filePath, path.extname(filePath));
+    return WHITELISTED_COMPONENTS.includes(component);
+  }
+  return false;
+}

package/dist/src/create-diff.mjs

@@ -0,0 +1,96 @@
+import {
+  findComponentFiles,
+  getAliasedPaths,
+  isBuiltinComponent,
+} from "./components.mjs";
+import { parseFilePath } from "./parse-file-path.mjs";
+
+function addFile(output, config, inSrcDir, relativeFilePath, content) {
+  if (!isBuiltinComponent(config, relativeFilePath)) {
+    output.files.push(
+      parseFilePath(inSrcDir, config, `./${relativeFilePath}`, content)
+    );
+  }
+}
+
+function addDependencies(
+  output,
+  initialPackageContents,
+  currentPackageContents
+) {
+  const initialPackageJson = JSON.parse(initialPackageContents);
+  const currentPackageJson = JSON.parse(currentPackageContents);
+
+  const initialDependencies = initialPackageJson.dependencies ?? {};
+  const currentDependencies = currentPackageJson.dependencies ?? {};
+  const initialDevDependencies = initialPackageJson.devDependencies ?? {};
+  const currentDevDependencies = currentPackageJson.devDependencies ?? {};
+
+  output.dependencies = Object.keys(currentDependencies).filter(
+    (dep) => !Object.prototype.hasOwnProperty.call(initialDependencies, dep)
+  );
+  output.devDependencies = Object.keys(currentDevDependencies).filter(
+    (dep) => !Object.prototype.hasOwnProperty.call(initialDevDependencies, dep)
+  );
+}
+
+function scanWithSrcDir(output, config, alteredFiles) {
+  for (const { path, content } of alteredFiles) {
+    if (path.startsWith("src/")) {
+      addFile(output, config, true, path.replace("src/", ""), content);
+    } else {
+      addFile(output, config, false, path, content);
+    }
+  }
+}
+
+function isInAppDir(path) {
+  return path.startsWith("app/");
+}
+
+function scanWithoutSrcDir(output, config, alteredFiles) {
+  const aliasedPaths = getAliasedPaths(config);
+
+  for (const { path, content } of alteredFiles) {
+    addFile(
+      output,
+      config,
+      aliasedPaths.includes(path) || isInAppDir(path),
+      path,
+      content
+    );
+  }
+}
+
+export function createDiff({
+  name,
+  config,
+  alteredFiles,
+  specificFiles,
+  currentFiles,
+  currentPackageJson,
+}) {
+  const output = {
+    name,
+    type: "registry:block",
+    dependencies: [],
+    devDependencies: [],
+    registryDependencies: [],
+    files: [],
+    tailwind: {},
+    cssVars: {},
+    meta: {},
+  };
+
+  if (config.isSrcDir) {
+    scanWithSrcDir(output, config, alteredFiles);
+  } else {
+    scanWithoutSrcDir(output, config, alteredFiles);
+  }
+
+  output.registryDependencies = findComponentFiles(config, currentFiles);
+
+  addDependencies(output, specificFiles["./package.json"], currentPackageJson);
+
+  return output;
+}

package/dist/src/git.mjs

@@ -0,0 +1,141 @@
+import fs from "node:fs";
+import path from "node:path";
+import { execSync } from "node:child_process";
+import ignore from "ignore";
+import { start } from "node:repl";
+
+const INITIAL_DIR = "_initial";
+
+const EXCLUDE_DIRS = [
+  "node_modules",
+  "dist",
+  "fonts",
+  "build",
+  "public",
+  "static",
+  ".next",
+  ".git",
+  INITIAL_DIR,
+];
+
+const EXCLUDE_FILES = [
+  ".DS_Store",
+  "next-env.d.ts",
+  "package-lock.json",
+  "yarn.lock",
+  "pnpm-lock.yaml",
+  "bun.lockb",
+  "package.json",
+  "tailwind.config.ts",
+  "tailwind.config.js",
+  "components.json",
+  "favicon.ico",
+];
+
+function cloneInitialCommit() {
+  deleteInitialDir();
+
+  try {
+    // Get the initial commit hash
+    const initialCommit = execSync("git rev-list --max-parents=0 HEAD")
+      .toString()
+      .trim();
+
+    // Clone the initial commit quietly
+    execSync(`git worktree add -f ${INITIAL_DIR} ${initialCommit}`, {
+      stdio: "ignore",
+    });
+  } catch (error) {
+    console.error("Error cloning initial commit:", error.message);
+    process.exit(1);
+  }
+}
+
+function deleteInitialDir() {
+  if (fs.existsSync(INITIAL_DIR)) {
+    fs.rmSync(INITIAL_DIR, { recursive: true });
+
+    try {
+      execSync("git worktree prune", { stdio: "ignore" });
+    } catch (error) {
+      console.error("Error pruning git worktree:", error.message);
+    }
+  }
+}
+
+function checkIfFileIsChanged(relativeFilePath) {
+  const initialFilePath = path.join(INITIAL_DIR, relativeFilePath);
+  const fullPath = path.join(process.cwd(), relativeFilePath);
+  if (!fs.existsSync(initialFilePath)) {
+    return true; // New file
+  }
+  const currentContent = fs.readFileSync(fullPath, "utf-8");
+  const initialContent = fs.readFileSync(initialFilePath, "utf-8");
+  return currentContent !== initialContent;
+}
+
+export function scanForFiles(startDir, checkFile = false) {
+  const foundFiles = [];
+
+  let ignorer = () => false;
+  if (fs.existsSync(path.join(startDir, ".gitignore"))) {
+    const gitIgnore = ignore().add(
+      fs.readFileSync(path.join(startDir, ".gitignore")).toString()
+    );
+    ignorer = (relativeFilePath) => {
+      return gitIgnore.ignores(relativeFilePath);
+    };
+  }
+
+  function scanDirectory(dir, relativePath = "") {
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      const fullPath = path.join(dir, entry.name);
+      const relativeFilePath = path.join(relativePath, entry.name);
+
+      if (entry.isDirectory()) {
+        if (!EXCLUDE_DIRS.includes(entry.name)) {
+          scanDirectory(path.join(dir, entry.name), relativeFilePath);
+        }
+      } else if (
+        !checkFile ||
+        (checkFile && checkIfFileIsChanged(relativeFilePath))
+      ) {
+        if (!EXCLUDE_FILES.includes(entry.name) && !ignorer(relativeFilePath)) {
+          foundFiles.push({
+            path: relativeFilePath,
+            content: fs.readFileSync(fullPath, "utf-8"),
+          });
+        }
+      }
+    }
+  }
+
+  scanDirectory(startDir);
+
+  return foundFiles.sort((a, b) => a.path.localeCompare(b.path));
+}
+
+export function scanForAlteredFiles(specificFilesToReturn = []) {
+  cloneInitialCommit();
+
+  const alteredFiles = scanForFiles(process.cwd(), true);
+
+  const specificFiles = specificFilesToReturn.reduce((out, file) => {
+    const fullPath = path.join(process.cwd(), INITIAL_DIR, file);
+    out[file] = fs.readFileSync(fullPath, "utf-8");
+    return out;
+  }, {});
+
+  deleteInitialDir();
+
+  return {
+    alteredFiles,
+    specificFiles,
+  };
+}
+
+export function hasSrcDir(dir) {
+  return fs.existsSync(path.join(dir, "src"));
+}

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

@@ -0,0 +1,32 @@
+function fixAlias(alias) {
+  return alias.replace("@", ".");
+}
+
+export function parseFilePath(wasInSrcDir, config, filePath, content) {
+  const out = {
+    path: filePath,
+    content,
+    type: "registry:example",
+    target: wasInSrcDir ? filePath : `~/${filePath.replace("./", "")}`,
+  };
+
+  if (filePath.startsWith(fixAlias(config.ui))) {
+    out.type = "registry:ui";
+    out.target = undefined;
+  } else if (filePath.startsWith(fixAlias(config.components))) {
+    out.type = "registry:block";
+    out.target = undefined;
+  } else if (filePath.startsWith(fixAlias(config.hooks))) {
+    out.type = "registry:hook";
+    out.target = undefined;
+  } else if (filePath.startsWith(fixAlias(config.lib))) {
+    out.type = "registry:lib";
+    out.target = undefined;
+  }
+
+  if (out.type === "registry:example") {
+    out.path = filePath;
+  }
+
+  return out;
+}