@makerkit/cli 1.3.18 → 2.0.0

package/README.md

@@ -2,9 +2,7 @@
 
 The CLI is a set of commands that help you manage your Makerkit SaaS Starter Kits.
 
-The CLI is currently in beta.
-
-NB: the CLI uses SSH to connect to GitHub. If you are not using SSH on your local machine, it will not work. In that case, please use the manual git commands instead.
+The CLI auto-detects whether you have SSH access to GitHub. If SSH is not available, it falls back to HTTPS URLs automatically.
 
 ## Installation
 
@@ -14,6 +12,12 @@ You can run commands using `npx`:
 npx @makerkit/cli@latest <command>
 ```
 
+If you use PNPM, use:
+
+```
+pnpm dlx @makerkit/cli@latest <command>
+```
+
 This ensures that you always run the latest version of the CLI.
 
 ### Some commands require a Makerkit repository
@@ -37,32 +41,11 @@ Options:
 
 Commands:
   new                         Initialize a new Makerkit project
-  plugins                     List and install plugins.
-  i18n                        Manage and translate your i18n files
-  license                     Manage Licenses
-  blog                        Manage and generate your blog posts
+  plugins                     Manage MakerKit plugins.
+  project                     Manage your MakerKit project.
   help [command]              display help for command
 ```
 
-### Adding an OpenAI Key (optional)
-
-To use the generative AI features of the CLI, you will need to add an OpenAI 
-key. 
-
-To do so, create a `.env.local` file if it does not exist yet, and add the
-following environment variable:
-
-```
-OPENAI_API_KEY=<your-key>
-```
-
-This key will be used to generate the prompts for your blog posts. It
-remains locally on your computer and is not shared with anyone.
-
-At the moment of writing, the CLI only uses the OpenAI API to generate:
-1. Translations for your i18n files
-2. Blog Posts
-
 ## Creating a new Makerkit project
 
 To create a new Makerkit project, you can use the `new` command:
@@ -77,67 +60,186 @@ pulling the starter kit from GitHub.
 
 The command will also install the dependencies.
 
+## Project
+
+The `project` command group helps you manage your MakerKit project.
+
+### Pulling upstream updates
+
+```
+makerkit project update
+```
+
+This command pulls the latest changes from the official MakerKit repository into your project. It:
+
+1. Detects which kit variant you're using (Next.js Supabase, Next.js Drizzle, etc.)
+2. Checks for SSH access to GitHub and falls back to HTTPS if unavailable
+3. Configures the `upstream` git remote if it doesn't exist (prompts for confirmation)
+4. Warns if the existing `upstream` remote points to the wrong repository
+5. Runs `git fetch upstream` followed by `git merge upstream/main`
+6. Reports success, already-up-to-date, or merge conflicts with resolution instructions
+
+| Variant | Upstream Repository |
+|---------|-------------------|
+| Next.js Supabase | `makerkit/next-supabase-saas-kit-turbo` |
+| Next.js Drizzle | `makerkit/next-drizzle-saas-kit-turbo` |
+| Next.js Prisma | `makerkit/next-prisma-saas-kit-turbo` |
+| React Router Supabase | `makerkit/react-router-supabase-saas-kit-turbo` |
+
 ## Plugins
 
-The CLI can help you manage plugins in your project. You can list the available plugins, install them, and update them.
+The CLI can help you manage plugins in your project. You can list, install, update, and diff plugins.
 
-### Listing plugins
+| Command | Description |
+|---------|-------------|
+| `plugins list` | List available and installed plugins |
+| `plugins add [id...]` | Install one or more plugins |
+| `plugins update [id...]` | Update installed plugins to the latest version |
+| `plugins outdated` | Check which installed plugins have updates |
+| `plugins diff [id]` | Show a git-style diff against the latest version |
+| `plugins init` | Set up your GitHub username for registry access |
 
-To list the available plugins, you can use the `plugins list` command:
+### Listing plugins
 
 ```
-> npx @makerkit/cli@latest plugins list
-
-Available plugins:
-  - cookie-banner
+makerkit plugins list
 ```
 
 ### Installing plugins
 
-To install a plugin, you can use the `plugins install` command:
+```
+makerkit plugins add feedback
+```
+
+Install multiple at once:
 
 ```
-> npx @makerkit/cli@latest plugins install
+makerkit plugins add umami posthog feedback
 ```
 
-This command will prompt you to select a plugin to install. Once selected, the plugin will be installed in your project.
+Running `plugins add` with no arguments shows a multi-select list of available plugins.
 
 ### Updating plugins
 
-To update a plugin, you can use the `plugins update` command:
+```
+makerkit plugins update
+```
+
+Or specify plugin IDs directly:
+
+```
+makerkit plugins update umami feedback
+```
+
+If your local files differ from the registry, the command lists the modified files and asks for confirmation before overwriting.
+
+### Checking for updates
 
 ```
-> npx @makerkit/cli@latest plugins update
+makerkit plugins outdated
 ```
 
-This command will prompt you to select a plugin to update. Once selected, the plugin will be updated in your project.
+### Diffing plugins
+
+```
+makerkit plugins diff umami
+```
+
+Running `plugins diff` with no arguments prompts you to select an installed plugin. Shows a colored unified diff (via `git diff`) between your local files and the latest registry version.
+
+## MCP Server
 
-## i18n
+The CLI ships an MCP server (`makerkit-cli-mcp`) that exposes plugin management and project operations as tools for AI agents. This enables AI-powered workflows such as installing plugins, checking for updates, **three-way merge conflict resolution** when updating plugins with local customizations, and **pulling upstream kit updates with AI-assisted conflict resolution**.
 
-The CLI can help you manage your i18n files. 
+> **Warning:** AI conflict merging is non-deterministic. Merged output can contain mistakes — always review the result and run your test suite before committing.
 
-You can translate from a locale 
-to another (requires an OpenAI key), and verify that your translations are 
-in sync between each other.
+### Available tools
 
-### Translating
+| Tool | Description |
+|------|-------------|
+| `makerkit_status` | Project introspection: variant, git status, registry config, installed plugins |
+| `makerkit_list_plugins` | List available plugins with install status and metadata |
+| `makerkit_add_plugin` | Install a plugin (codemod, env vars, base version storage) |
+| `makerkit_init_registry` | Cache your GitHub username for registry auth |
+| `makerkit_check_update` | Three-way diff analysis (base/local/remote) with per-file status and content |
+| `makerkit_apply_update` | Write AI-resolved files to disk and update base versions |
+| `makerkit_project_pull` | Pull upstream kit updates, returning conflict details (base/ours/theirs) for AI resolution |
+| `makerkit_project_resolve_conflicts` | Write AI-resolved conflict files, stage them, and complete the merge commit |
 
-To translate your i18n files, you can use the `i18n translate` command:
+### Installation
+
+Install the package globally (or use `npx`/`pnpm dlx`):
 
 ```
-> npx @makerkit/cli@latest i18n translate en es
+npm i -g @makerkit/cli@latest
 ```
 
-This command will translate all the keys in your `en/*.json` file to `es/*.
-json`. It will use the OpenAI API to translate the keys. You will need to 
-add a valid OpenAI API key in the `.env.local` file of your Makerkit repository.
+Then configure your AI client to use the MCP server.
+
+**Claude Desktop** (`~/.claude/claude_desktop_config.json`):
 
-### Verifying
+```json
+{
+  "mcpServers": {
+    "makerkit-cli": {
+      "command": "makerkit-cli-mcp"
+    }
+  }
+}
+```
 
-To verify that your i18n files are in sync, you can use the `i18n verify` command:
+**Cursor** (`.cursor/mcp.json` in your project root):
 
+```json
+{
+  "mcpServers": {
+    "makerkit-cli": {
+      "command": "makerkit-cli-mcp"
+    }
+  }
+}
 ```
-> npx @makerkit/cli@latest i18n verify <base-locale>
+
+If you haven't installed the package globally, use `npx` instead:
+
+```json
+{
+  "mcpServers": {
+    "makerkit-cli": {
+      "command": "npx",
+      "args": ["-y", "@makerkit/cli@latest", "makerkit-cli-mcp"]
+    }
+  }
+}
 ```
 
-If you omit the `base-locale` argument, the command will use `en` as the base.
+### Three-way merge workflow
+
+When a plugin is installed or updated, the CLI stores the original registry files as **base versions** in `./node_modules/.cache/makerkit/bases/`. On the next update, the `makerkit_check_update` tool computes a three-way diff (base vs. local vs. remote) for each file and returns one of these statuses:
+
+| Status | Meaning |
+|--------|---------|
+| `unchanged` | Local matches remote — nothing to do |
+| `updated` | Only the registry changed — safe to auto-apply |
+| `conflict` | Both sides changed — AI merge needed |
+| `no_base` | Legacy install (no stored base) — two-way diff |
+| `added` | New file from registry |
+| `deleted_locally` | You deleted the file, but registry still ships it |
+
+The AI agent reads the base, local, and remote content for `conflict` files, produces a merged version, then calls `makerkit_apply_update` to write the resolved files.
+
+Base versions are stored in `node_modules/.cache/makerkit/bases/` — already gitignored by default. They get cleared on `npm ci` or deleting `node_modules/`, in which case plugins fall back to two-way diff (`no_base`) until the next apply restores them.
+
+### Upstream pull workflow
+
+The `makerkit_project_pull` and `makerkit_project_resolve_conflicts` tools automate pulling updates from the official MakerKit repository with AI-assisted conflict resolution.
+
+**How it works:**
+
+1. The agent calls `makerkit_project_pull` with the project path
+2. The tool detects the kit variant, configures the `upstream` remote (SSH or HTTPS), fetches, and attempts a merge
+3. If the merge succeeds, it returns a success response
+4. If merge conflicts occur, it returns the **base**, **ours** (local), and **theirs** (upstream) content for each conflicting file
+5. The agent reviews the three versions, produces resolved content, and asks the user for guidance when the intent behind local changes is unclear
+6. The agent calls `makerkit_project_resolve_conflicts` with the resolved files to write them, stage them, and complete the merge commit
+7. If some conflicts remain unresolved, the tool reports them so the agent can resolve them in another round