magicpath-ai 1.3.0-beta.1 → 1.3.0-beta.11

package/README.md

@@ -1,96 +1,207 @@
 # MagicPath CLI
 
-( Instantly bring your MagicPath AI projects to your local development environment. Edit, remix, and create in your own vibe.
+A component platform for AI agents. Search, add, and integrate UI components from MagicPath directly into your projects — works with Claude Code, Cursor, and GitHub Copilot.
 
 ## Quick Start
 
 ```bash
-npx magicpath-ai@latest clone -k <your-access-key>
+npm install -g magicpath-ai@beta
+magicpath-ai login
+magicpath-ai init          # run in your project directory
 ```
 
-## Installation
+After `init`, Claude Code, Cursor, and GitHub Copilot automatically pick up MagicPath skills — just mention MagicPath in conversation and your agent knows what to do.
 
-### Using npx (Recommended)
+## Commands
 
-No installation required! Just run:
+### Auth
+
+#### `login`
+
+Log in to your MagicPath account. Opens your browser for one-click authentication.
 
 ```bash
-npx magicpath-ai@latest clone -k <access-key>
+magicpath-ai login
+magicpath-ai login --code <code>   # headless fallback
 ```
 
-### Global Installation
+#### `logout`
 
 ```bash
-npm install -g magicpath-ai
-magicpath-ai clone -k <access-key>
+magicpath-ai logout
 ```
 
-### Local Installation
+#### `whoami`
+
+Show the currently authenticated user.
 
 ```bash
-npm install magicpath-ai
-npx magicpath-ai clone -k <access-key>
+magicpath-ai whoami
 ```
 
-## Usage
+### Discovery
 
-### Clone Command
+#### `search`
 
-Download and set up a MagicPath project locally:
+Search component names across all your projects.
 
 ```bash
-npx magicpath-ai@latest clone -k <access-key> [options]
+magicpath-ai search "button"
+magicpath-ai search "nav" --limit 5
 ```
 
-**Options:**
-- `-k, --key <accessKey>` (required): = One-time magic access key to unlock and download your project
-- `-d, --debug`: Get verbose debug logs in the CLI
+| Option | Description |
+|--------|-------------|
+| `--limit <n>` | Max results (default: 20) |
+
+#### `list-projects`
+
+List all projects for the current user.
 
-**Example:**
 ```bash
-npx magicpath-ai@latest clone -k mp_1234567890abcdef
+magicpath-ai list-projects
+magicpath-ai list-projects --limit 10 --offset 0
 ```
 
-The CLI will:
-1. =� Download your project using the access key
-2. =� Prompt you to name your project (default: `magicpath-project`)
-3. =� Unpack the project to a local directory
-4. <� Your project is ready to go!
+| Option | Description |
+|--------|-------------|
+| `--limit <n>` | Max results |
+| `--offset <n>` | Skip first N results (default: 0) |
 
-## What You Get
+#### `list-components`
 
-When you clone a MagicPath project, you'll get a complete local copy with:
-- All project files and assets
-- Configuration files
-- Dependencies and setup instructions
-- Ready-to-run codebase
+List components in a project. Supports cursor-based pagination.
 
-## Requirements
+```bash
+magicpath-ai list-components <projectId>
+magicpath-ai list-components <projectId> --limit 20
+magicpath-ai list-components <projectId> --after <lastId>
+```
 
-- Node.js >=16.0.0
-- npm or yarn
+| Option | Description |
+|--------|-------------|
+| `--limit <n>` | Max results per page (default: 100) |
+| `--after <id>` | Fetch components after this ID |
+| `--sort-by <field>` | Sort by `name` or `createdAt` (default: name) |
+| `--order <dir>` | Sort direction: `asc` or `desc` (default: asc) |
+
+#### `view`
+
+Open a component preview in the browser.
+
+```bash
+magicpath-ai view <generatedName>
+```
+
+### Components
+
+#### `add`
+
+Add a MagicPath component to your project. Fetches the component files, writes them to your project, and installs any required dependencies.
+
+```bash
+magicpath-ai add <generatedName>
+magicpath-ai add wispy-river-5234 --path src/components/ui
+magicpath-ai add wispy-river-5234 --inspect    # view source without installing
+magicpath-ai add wispy-river-5234 --dry-run    # preview file list only
+```
+
+| Option | Description |
+|--------|-------------|
+| `-p, --path <path>` | Custom component path (default: `src/components/magicpath`) |
+| `--inspect` | Show full source code without installing |
+| `--dry-run` | Preview file list without writing |
+| `-y, --yes` | Skip confirmation prompts |
+| `--overwrite` | Overwrite existing files |
+| `-d, --debug` | Enable debug logging |
+
+#### `integrate`
+
+Integrate a MagicPath component into your project using AI. Offers two modes: integrate into a specific file, or retheme your entire project to match the component.
+
+```bash
+magicpath-ai integrate <generatedName>
+magicpath-ai integrate wispy-river-5234 --target src/app/page.tsx
+magicpath-ai integrate wispy-river-5234 --dry-run
+```
+
+| Option | Description |
+|--------|-------------|
+| `-t, --target <file>` | Target file to integrate into (skips interactive prompt) |
+| `--no-review` | Apply changes without review |
+| `--dry-run` | Show what would happen without writing |
+| `-d, --debug` | Enable debug logging |
+
+### AI Agent Setup
 
-## How It Works
+#### `init`
 
-1. **Access Key**: Each MagicPath project comes with a unique, one-time access key
-2. **Secure Download**: The CLI securely downloads your project from MagicPath servers
-3. **Local Setup**: Projects are extracted and set up in your chosen directory
-4. **Ready to Code**: Start editing, remixing, and building immediately
+Set up MagicPath skills for AI agents. Creates rule/skill files for Claude Code, Cursor, and GitHub Copilot in your project.
 
-## Troubleshooting
+```bash
+magicpath-ai init
+```
+
+#### `info`
+
+Show project and auth context. Useful for agent context injection.
+
+```bash
+magicpath-ai info
+```
+
+#### `schema`
+
+Show JSON Schema for a command's input/output.
+
+```bash
+magicpath-ai schema add
+magicpath-ai schema --all
+```
+
+#### `clone`
+
+Download and unpack a full MagicPath project using a one-time access key.
 
-### Invalid Access Key
-- Ensure your access key is correct and hasn't been used before
-- Access keys are single-use for security
+```bash
+magicpath-ai clone -k <accessKey>
+```
+
+| Option | Description |
+|--------|-------------|
+| `-k, --key <accessKey>` | Access key (required) |
+| `-i, --ide <ide>` | Open in IDE (cursor, antigravity, vscode, webstorm) |
+| `--dir <directory>` | Target directory (non-interactive) |
+| `--name <projectName>` | Project name (non-interactive) |
+
+## Global Options
+
+| Option | Description |
+|--------|-------------|
+| `-o json` | Structured JSON output (also skips interactive prompts) |
+
+The `-d, --debug` flag is available on `add`, `clone`, and `integrate` for verbose logging.
+
+## Environment Variables
 
-### Download Issues
-- Check your internet connection
-- Verify the access key hasn't expired
-- Use `--debug` flag for detailed error information
+| Variable | Description |
+|----------|-------------|
+| `MAGICPATH_TOKEN` | Auth token (bypasses login flow) |
 
-### Permission Errors
-- Ensure you have write permissions in the current directory
-- Try running from a different directory
+## AI Agent Integration
+
+Running `magicpath-ai init` in your project creates skill files that teach AI agents how to use MagicPath:
+
+- **Claude Code** — `.claude/skills/magicpath/SKILL.md`
+- **Cursor** — `.cursor/rules/magicpath.mdc`
+- **GitHub Copilot** — `.github/instructions/magicpath.instructions.md`
+
+Once set up, agents automatically know how to search for components, add them to your project, and integrate them into specific files.
+
+## Requirements
+
+- Node.js >= 16.0.0
+- npm or yarn
 
 ## Support
 
@@ -100,8 +211,8 @@ When you clone a MagicPath project, you'll get a complete local copy with:
 
 ## License
 
-MIT � Jack Beoris
+MIT - Jack Beoris
 
 ---
 
-Made with ( by the MagicPath team
+Made with love by the MagicPath team

package/dist/cli.js

@@ -1,13 +1,40 @@
 #!/usr/bin/env node
 import { program } from 'commander';
+import { setJsonMode } from './util/output.js';
 import { registerCloneCommand } from './commands/clone.js';
 import { registerAddCommand } from './commands/add.js';
 import { registerIntegrateCommand } from './commands/integrate.js';
+// import { registerRethemeCommand } from './commands/retheme.js';
 import { registerAuthCommands } from './commands/auth.js';
-program.name('magicpath').description('CLI for MagicPath AI').version('1.2.0');
+import { registerWhoamiCommand } from './commands/whoami.js';
+import { registerListCommands } from './commands/list.js';
+import { registerSchemaCommand } from './commands/schema.js';
+import { registerInitCommand } from './commands/init.js';
+import { registerViewCommand } from './commands/view.js';
+import { registerInfoCommand } from './commands/info.js';
+import { registerSearchCommand } from './commands/search.js';
+program
+    .name('magicpath')
+    .description('CLI for MagicPath AI')
+    .version('1.3.0')
+    .option('-o, --output <format>', 'Output format: json')
+    .hook('preAction', (thisCommand) => {
+    const opts = thisCommand.optsWithGlobals();
+    if (opts.output === 'json') {
+        setJsonMode(true);
+    }
+});
 registerCloneCommand(program);
 registerAddCommand(program);
 registerIntegrateCommand(program);
+// registerRethemeCommand(program);
 registerAuthCommands(program);
+registerWhoamiCommand(program);
+registerListCommands(program);
+registerSchemaCommand(program);
+registerInitCommand(program);
+registerViewCommand(program);
+registerInfoCommand(program);
+registerSearchCommand(program);
 program.parse();
 //# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,wBAAwB,EAAE,MAAM,yBAAyB,CAAC;AACnE,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAE1D,OAAO,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,WAAW,CAAC,sBAAsB,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;AAE/E,oBAAoB,CAAC,OAAO,CAAC,CAAC;AAC9B,kBAAkB,CAAC,OAAO,CAAC,CAAC;AAC5B,wBAAwB,CAAC,OAAO,CAAC,CAAC;AAClC,oBAAoB,CAAC,OAAO,CAAC,CAAC;AAE9B,OAAO,CAAC,KAAK,EAAE,CAAC"}
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,wBAAwB,EAAE,MAAM,yBAAyB,CAAC;AACnE,kEAAkE;AAClE,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAE7D,OAAO;KACJ,IAAI,CAAC,WAAW,CAAC;KACjB,WAAW,CAAC,sBAAsB,CAAC;KACnC,OAAO,CAAC,OAAO,CAAC;KAChB,MAAM,CAAC,uBAAuB,EAAE,qBAAqB,CAAC;KACtD,IAAI,CAAC,WAAW,EAAE,CAAC,WAAW,EAAE,EAAE;IACjC,MAAM,IAAI,GAAG,WAAW,CAAC,eAAe,EAAE,CAAC;IAC3C,IAAI,IAAI,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC;QAC3B,WAAW,CAAC,IAAI,CAAC,CAAC;IACpB,CAAC;AACH,CAAC,CAAC,CAAC;AAEL,oBAAoB,CAAC,OAAO,CAAC,CAAC;AAC9B,kBAAkB,CAAC,OAAO,CAAC,CAAC;AAC5B,wBAAwB,CAAC,OAAO,CAAC,CAAC;AAClC,mCAAmC;AACnC,oBAAoB,CAAC,OAAO,CAAC,CAAC;AAC9B,qBAAqB,CAAC,OAAO,CAAC,CAAC;AAC/B,oBAAoB,CAAC,OAAO,CAAC,CAAC;AAC9B,qBAAqB,CAAC,OAAO,CAAC,CAAC;AAC/B,mBAAmB,CAAC,OAAO,CAAC,CAAC;AAC7B,mBAAmB,CAAC,OAAO,CAAC,CAAC;AAC7B,mBAAmB,CAAC,OAAO,CAAC,CAAC;AAC7B,qBAAqB,CAAC,OAAO,CAAC,CAAC;AAE/B,OAAO,CAAC,KAAK,EAAE,CAAC"}

package/dist/commands/add.d.ts

@@ -1,2 +1,51 @@
 import type { Command } from 'commander';
+import { z } from 'zod';
+export declare const addOptionsSchema: z.ZodObject<{
+    yes: z.ZodDefault<z.ZodBoolean>;
+    overwrite: z.ZodDefault<z.ZodBoolean>;
+    path: z.ZodOptional<z.ZodString>;
+    debug: z.ZodDefault<z.ZodBoolean>;
+    dryRun: z.ZodDefault<z.ZodBoolean>;
+    inspect: z.ZodDefault<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    debug: boolean;
+    yes: boolean;
+    overwrite: boolean;
+    dryRun: boolean;
+    inspect: boolean;
+    path?: string | undefined;
+}, {
+    debug?: boolean | undefined;
+    path?: string | undefined;
+    yes?: boolean | undefined;
+    overwrite?: boolean | undefined;
+    dryRun?: boolean | undefined;
+    inspect?: boolean | undefined;
+}>;
+export type AddOptions = z.infer<typeof addOptionsSchema>;
+export declare const addOutputSchema: z.ZodObject<{
+    component: z.ZodString;
+    generatedName: z.ZodString;
+    filesWritten: z.ZodArray<z.ZodString, "many">;
+    dependenciesInstalled: z.ZodArray<z.ZodString, "many">;
+    importStatement: z.ZodOptional<z.ZodString>;
+    usage: z.ZodOptional<z.ZodString>;
+    dryRun: z.ZodBoolean;
+}, "strip", z.ZodTypeAny, {
+    generatedName: string;
+    component: string;
+    dryRun: boolean;
+    filesWritten: string[];
+    dependenciesInstalled: string[];
+    importStatement?: string | undefined;
+    usage?: string | undefined;
+}, {
+    generatedName: string;
+    component: string;
+    dryRun: boolean;
+    filesWritten: string[];
+    dependenciesInstalled: string[];
+    importStatement?: string | undefined;
+    usage?: string | undefined;
+}>;
 export declare function registerAddCommand(program: Command): void;

package/dist/commands/add.js

@@ -6,14 +6,26 @@ import { enableDebugLogger, logger } from '../util/logger.js';
 import { MagicPathError } from '../util/error.js';
 import { AuthRequiredError } from '../util/authError.js';
 import { brandSpinner } from '../util/ui.js';
+import { isJsonMode, jsonResult, jsonError } from '../util/output.js';
 import { fetchComponent, checkExistingFiles, writeComponentFiles, checkUtilsExists, writeUtilsFile, resolveComponentsPath, resolveUtilsPath, sanitizeComponentFolderName, extractComponentExports, generateImportStatement, generateUsageExample, writeUsageFile, DEFAULT_COMPONENTS_PATH, } from '../util/component.js';
 import { installPackages } from '../util/dependencies.js';
 import { runLoginFlow } from './auth.js';
-const addOptionsSchema = z.object({
+export const addOptionsSchema = z.object({
     yes: z.boolean().default(false),
     overwrite: z.boolean().default(false),
     path: z.string().optional(),
     debug: z.boolean().default(false),
+    dryRun: z.boolean().default(false),
+    inspect: z.boolean().default(false),
+});
+export const addOutputSchema = z.object({
+    component: z.string(),
+    generatedName: z.string(),
+    filesWritten: z.array(z.string()),
+    dependenciesInstalled: z.array(z.string()),
+    importStatement: z.string().optional(),
+    usage: z.string().optional(),
+    dryRun: z.boolean(),
 });
 export function registerAddCommand(program) {
     program
@@ -21,9 +33,11 @@ export function registerAddCommand(program) {
         .description('Add a MagicPath component to your project')
         .argument('<generatedName>', 'The generated name of the component (e.g., wispy-river-5234)')
         .option('-y, --yes', 'Skip confirmation prompts', false)
-        .option('-o, --overwrite', 'Overwrite existing files', false)
+        .option('--overwrite', 'Overwrite existing files', false)
         .option('-p, --path <path>', `Custom path for components (default: ${DEFAULT_COMPONENTS_PATH})`)
         .option('-d, --debug', 'Enable debug logging', false)
+        .option('--dry-run', 'Show what would happen without writing files', false)
+        .option('--inspect', 'Show component source code without installing (implies --dry-run)', false)
         .action(async (generatedName, options) => {
         try {
             let addOptions;
@@ -35,23 +49,43 @@ export function registerAddCommand(program) {
             }
             if (addOptions.debug)
                 enableDebugLogger();
+            // --inspect implies --dry-run and --yes (no prompts, no writing)
+            if (addOptions.inspect) {
+                addOptions.dryRun = true;
+                addOptions.yes = true;
+            }
+            // In JSON mode, imply --yes (skip prompts)
+            const json = isJsonMode();
+            if (json)
+                addOptions.yes = true;
             logger.debug({ generatedName, options: addOptions });
             const cwd = process.cwd();
             // Check if we're in a valid project directory
             const packageJsonPath = path.join(cwd, 'package.json');
             if (!fs.existsSync(packageJsonPath)) {
-                throw new MagicPathError('No package.json found. Please run this command from the root of your project.');
+                throw new MagicPathError('No package.json found. Please run this command from the root of your React project.', {
+                    code: 'MISSING_PACKAGE_JSON',
+                    suggestion: 'Run this command from the root of your project where package.json is located.',
+                });
             }
             // Step 1: Fetch component from registry
-            const fetchSpinner = brandSpinner(`Fetching component "${generatedName}"...`).start();
+            const fetchSpinner = json
+                ? null
+                : brandSpinner(`Fetching component "${generatedName}"...`).start();
             let componentData;
             try {
                 componentData = await fetchComponent(generatedName);
-                fetchSpinner.succeed(`Found component: ${componentData.name}`);
+                fetchSpinner?.succeed(`Found component: ${componentData.name}`);
             }
             catch (err) {
                 if (err instanceof AuthRequiredError) {
-                    fetchSpinner.fail('Not logged in');
+                    fetchSpinner?.fail('Not logged in');
+                    if (json) {
+                        throw new MagicPathError('Not authenticated. Set MAGICPATH_TOKEN or run `magicpath-ai login`.', {
+                            code: 'NOT_AUTHENTICATED',
+                            suggestion: 'Run `magicpath-ai login` or set the MAGICPATH_TOKEN environment variable.',
+                        });
+                    }
                     const { shouldLogin } = await prompts({
                         type: 'confirm',
                         name: 'shouldLogin',
@@ -82,7 +116,7 @@ export function registerAddCommand(program) {
                     }
                 }
                 else {
-                    fetchSpinner.fail('Failed to fetch component');
+                    fetchSpinner?.fail('Failed to fetch component');
                     if (err instanceof MagicPathError) {
                         throw err;
                     }
@@ -103,8 +137,10 @@ export function registerAddCommand(program) {
             // Step 2: Check for existing files
             const existingFiles = checkExistingFiles(componentData.files, componentsPath);
             if (existingFiles.length > 0 && !addOptions.overwrite) {
-                console.log('\nThe following files already exist:');
-                existingFiles.forEach((file) => console.log(`  - ${file}`));
+                if (!json) {
+                    console.log('\nThe following files already exist:');
+                    existingFiles.forEach((file) => console.log(`  - ${file}`));
+                }
                 if (!addOptions.yes) {
                     const { shouldOverwrite } = await prompts({
                         type: 'confirm',
@@ -118,6 +154,12 @@ export function registerAddCommand(program) {
                     }
                 }
                 else {
+                    if (json) {
+                        throw new MagicPathError(`Files already exist: ${existingFiles.join(', ')}. Use --overwrite to replace.`, {
+                            code: 'FILES_EXIST',
+                            suggestion: 'Pass `--overwrite` to replace existing files.',
+                        });
+                    }
                     console.log('Use --overwrite to replace existing files.');
                     return;
                 }
@@ -139,35 +181,100 @@ export function registerAddCommand(program) {
                     return;
                 }
             }
+            // Build result data for JSON output
+            const filesWritten = componentData.files.map((f) => path.relative(cwd, path.join(componentsPath, f.path)));
+            // Extract import info
+            const mainFile = componentData.files[0];
+            let importStatement;
+            let usageStr;
+            if (mainFile) {
+                const fileName = mainFile.name.replace(/\.tsx?$/, '');
+                const importPath = addOptions.path
+                    ? `@/${addOptions.path}/${componentFolderName}/${fileName}`
+                    : `@/components/magicpath/${componentFolderName}/${fileName}`;
+                const exportInfo = extractComponentExports(mainFile.content);
+                if (exportInfo) {
+                    importStatement = generateImportStatement(exportInfo, importPath);
+                    usageStr = generateUsageExample(exportInfo);
+                }
+                else {
+                    importStatement = `import { ${fileName} } from '${importPath}';`;
+                }
+            }
+            // Dry run: return what would happen without writing
+            if (addOptions.dryRun) {
+                const fileContents = addOptions.inspect || json
+                    ? componentData.files.map((f) => ({
+                        path: f.path,
+                        name: f.name,
+                        content: f.content,
+                    }))
+                    : undefined;
+                if (json) {
+                    jsonResult({
+                        component: componentData.name,
+                        generatedName: componentData.generatedName,
+                        filesWritten,
+                        files: fileContents,
+                        dependenciesInstalled: componentData.dependencies,
+                        importStatement,
+                        usage: usageStr,
+                        dryRun: true,
+                    });
+                }
+                console.log('\n[Dry run] Would install:');
+                console.log(`  Component: ${componentData.name}`);
+                console.log(`  Files: ${filesWritten.join(', ')}`);
+                console.log(`  Dependencies: ${componentData.dependencies.join(', ') || 'none'}`);
+                if (importStatement)
+                    console.log(`  Import: ${importStatement}`);
+                // --inspect: show file contents
+                if (addOptions.inspect) {
+                    for (const f of componentData.files) {
+                        console.log(`\n${'─'.repeat(60)}`);
+                        console.log(`  ${f.path}`);
+                        console.log(`${'─'.repeat(60)}`);
+                        console.log(f.content);
+                    }
+                }
+                return;
+            }
             // Step 4: Write component files
-            const writeSpinner = brandSpinner('Writing component files...').start();
+            const writeSpinner = json
+                ? null
+                : brandSpinner('Writing component files...').start();
             try {
                 writeComponentFiles(componentData.files, componentsPath, true);
-                writeSpinner.succeed(`Wrote ${componentData.files.length} file(s) to ${path.relative(cwd, componentsPath) || '.'}`);
+                writeSpinner?.succeed(`Wrote ${componentData.files.length} file(s) to ${path.relative(cwd, componentsPath) || '.'}`);
             }
             catch (err) {
-                writeSpinner.fail('Failed to write component files');
+                writeSpinner?.fail('Failed to write component files');
                 throw new MagicPathError('Failed to write component files. Please check permissions and try again.');
             }
             // Step 5: Install utils if needed
             const utilsExists = checkUtilsExists(utilsPath);
             if (!utilsExists && componentData.utils.content) {
-                const utilsSpinner = brandSpinner('Installing utilities...').start();
+                const utilsSpinner = json
+                    ? null
+                    : brandSpinner('Installing utilities...').start();
                 try {
                     writeUtilsFile(componentData.utils.content, utilsPath);
-                    utilsSpinner.succeed(`Wrote utils.ts to ${path.relative(cwd, utilsPath) || '.'}`);
+                    utilsSpinner?.succeed(`Wrote utils.ts to ${path.relative(cwd, utilsPath) || '.'}`);
                 }
                 catch (err) {
-                    utilsSpinner.fail('Failed to write utils file');
+                    utilsSpinner?.fail('Failed to write utils file');
                     logger.debug({ err });
-                    // Non-fatal - continue with installation
-                    console.log('  Warning: Could not write utils.ts. You may need to create it manually.');
+                    if (!json) {
+                        console.log('  Warning: Could not write utils.ts. You may need to create it manually.');
+                    }
                 }
             }
             // Step 6: Install dependencies
+            const installedDeps = [];
             if (componentData.dependencies.length > 0) {
                 try {
                     const { installed, skipped } = installPackages(componentData.dependencies, cwd);
+                    installedDeps.push(...installed);
                     if (skipped.length > 0) {
                         logger.debug({
                             message: 'Skipped already installed packages',
@@ -177,39 +284,44 @@ export function registerAddCommand(program) {
                 }
                 catch (err) {
                     if (err instanceof MagicPathError) {
-                        // Non-fatal - show warning but don't fail
-                        console.log(`\n⚠️  ${err.message}`);
+                        if (!json)
+                            console.log(`\n⚠️  ${err.message}`);
                     }
                 }
             }
+            // JSON output
+            if (json) {
+                jsonResult({
+                    component: componentData.name,
+                    generatedName: componentData.generatedName,
+                    filesWritten,
+                    dependenciesInstalled: installedDeps,
+                    importStatement,
+                    usage: usageStr,
+                    dryRun: false,
+                });
+            }
             // Step 7: Show success message and write usage file
             console.log(`\n✅ Successfully added "${componentData.name}" to your project!`);
             console.log(`\nUsage:`);
-            // Show import and usage example
-            const mainFile = componentData.files[0];
             if (mainFile) {
                 const fileName = mainFile.name.replace(/\.tsx?$/, '');
                 const importPath = addOptions.path
                     ? `@/${addOptions.path}/${componentFolderName}/${fileName}`
                     : `@/components/magicpath/${componentFolderName}/${fileName}`;
-                // Try to extract actual export info from the component source
                 const exportInfo = extractComponentExports(mainFile.content);
                 if (exportInfo) {
-                    // Show accurate import statement based on actual exports
                     console.log(`  ${generateImportStatement(exportInfo, importPath)}`);
                     console.log('');
                     console.log(`  ${generateUsageExample(exportInfo)}`);
-                    // Show required props hint if there are any
                     if (exportInfo.requiredProps.length > 0) {
                         console.log('');
                         console.log(`  Required props: ${exportInfo.requiredProps.join(', ')}`);
                     }
                 }
                 else {
-                    // Fallback to simple named export assumption
                     console.log(`  import { ${fileName} } from '${importPath}';`);
                 }
-                // Write usage.md file to the component folder
                 try {
                     writeUsageFile(componentsPath, {
                         componentName: componentData.name,
@@ -221,11 +333,12 @@ export function registerAddCommand(program) {
                 }
                 catch (err) {
                     logger.debug({ err });
-                    // Non-fatal - just skip writing the usage file
                 }
             }
         }
         catch (err) {
+            if (isJsonMode())
+                jsonError(err);
             if (err instanceof MagicPathError) {
                 console.error(`\n${err.message}`);
                 process.exit(1);