magicpath-ai 1.3.0-beta.2 → 1.3.0-beta.4

package/dist/commands/init.js

@@ -0,0 +1,280 @@
+import path from 'path';
+import fs from 'fs-extra';
+import { isJsonMode, jsonResult } from '../util/output.js';
+import { GREEN_CHECK } from '../util/ui.js';
+// ── Shared content (editor-agnostic) ──────────────────────────────────
+const DESCRIPTION = 'MagicPath is an external platform where the user builds and stores UI components. Use this when the user mentions "magicpath", wants to find/browse/search their MagicPath components, add a MagicPath component, preview a MagicPath component, or integrate one into their project. MagicPath components are NOT in the local git repo — they live on the MagicPath platform and must be fetched via the CLI.';
+const SHARED_BODY = `# MagicPath
+
+A platform for building, sharing, and installing UI components via AI. Components are added as source code to the user's project via the \`magicpath-ai\` CLI.
+
+## Getting Started
+
+Run \`magicpath-ai info\` to check auth status and project context. If not authenticated, run \`magicpath-ai login\` (interactive) or \`magicpath-ai login --code <code>\` (non-interactive).
+
+**In non-interactive contexts (agents, CI), NEVER run \`magicpath-ai login\` without \`--code\` — it opens a browser and hangs waiting for interactive input.**
+
+## Workflow
+
+1. **Check auth** — run \`magicpath-ai whoami\` to verify authentication.
+2. **Find components** — use \`magicpath-ai search <query>\` to search across all projects, or \`list-projects\` then \`list-components <projectId>\` to browse.
+3. **Confirm with the user (STOP and wait)** — unless the user specified an exact generatedName, tell the user what you found (name, generatedName, project), open a browser preview with \`magicpath-ai view <generatedName>\`, and ask if it's the right component. If multiple matches, list them all and ask which one. **This is a STOP point — end your response here and wait for the user to reply. Do NOT proceed to steps 4-7 until the user explicitly confirms.** Do not run \`add\` or \`add --inspect\` yet.
+4. **Inspect source** — only after the user confirms in step 3, use \`magicpath-ai add <generatedName> --inspect\` to see the component's source code without installing. Decide how it needs to be adapted (props to add, behavior to wire up).
+5. **Add to project** — use \`magicpath-ai add <generatedName> -y\` to install component files. Always pass \`-y\` in non-interactive contexts.
+6. **Use the component** — after adding, import the component from \`@/components/magicpath/<name>/\` using the \`importStatement\` from the add output. Edit the component file to add props as needed, then render it from the parent.
+7. **Integrate** — use the \`integrate\` CLI command to wire a component into an existing file via AI.
+
+## Critical Rules
+
+- **\`add\` means install-to-use.** Only run \`add\` when you intend to import and render the installed component. If you just want to read the source code, use \`add --inspect\` instead.
+- **After \`add\`, always import the component.** The whole point of \`add\` is to get source files you then import. Never add a component and then copy its styles/markup into another file — import and render the component directly.
+- **MagicPath components are source code you own.** After \`add\`, the component files live in your project at \`src/components/magicpath/<name>/\`. You can and should edit them directly to add props, change behavior, adjust styles, or integrate with your app's state. This is the intended workflow — not copying code out of them.
+- **When a component needs integration:** (1) \`add\` the component, (2) edit the component file to accept the props you need (e.g., \`onSubmit\`, \`placeholder\`, \`className\`), (3) import it from the parent and pass those props. Do NOT copy the component's JSX/styles into the parent file.
+- **\`add --inspect\` for read-only inspection.** Shows full source code without writing any files. Use this when deciding whether a component fits your needs before committing to install.
+- **Never run \`view\` commands in parallel.** The \`view\` command opens a browser window for the user to look at. Only open one preview at a time, and always tell the user what you're opening before running the command.
+
+## Quick Reference
+
+\`\`\`bash
+# Auth
+magicpath-ai login --code <code>     # non-interactive login
+magicpath-ai whoami                   # check auth status
+magicpath-ai info                     # full project context
+
+# Find components
+magicpath-ai search "input box"       # search across all projects
+magicpath-ai list-projects            # list all projects
+magicpath-ai list-components <id>     # list components in a project
+
+# Inspect components
+magicpath-ai view <generatedName>           # preview in browser
+magicpath-ai add <generatedName> --inspect  # show source code (no install)
+magicpath-ai add <generatedName> --dry-run  # show what would be installed
+
+# Install and use components
+magicpath-ai add <generatedName> -y   # add to project (no prompts)
+magicpath-ai integrate <name> <file>  # AI-powered integration
+\`\`\`
+
+## Key Concepts
+
+- Each component has a **generatedName** (e.g., \`wispy-river-5234\`) — this is the identifier for all operations
+- Components are added as source code to \`src/components/magicpath/<name>/\`
+- The \`add\` command returns \`importStatement\` and \`usage\` — use these in code
+- The \`integrate\` command returns modified file contents but does NOT write them — the agent must write the files
+- Use \`add --inspect\` to inspect source code without installing — don't use \`add\` just to read code`;
+const CLI_REFERENCE = `# MagicPath CLI Reference
+
+> **IMPORTANT:** Always pass \`-y\` to skip interactive prompts when running from an agent context. Use \`-o json\` for structured output.
+
+## Commands
+
+### \`info\` — Project and auth context
+
+\`\`\`bash
+magicpath-ai info              # human-readable
+magicpath-ai info -o json      # structured JSON
+\`\`\`
+
+Returns auth status, user info, projects, and CLI version.
+
+### \`login\` — Authenticate
+
+\`\`\`bash
+magicpath-ai login                    # interactive (opens browser)
+magicpath-ai login --code <code>      # non-interactive (exchange auth code)
+\`\`\`
+
+**WARNING:** \`magicpath-ai login\` without \`--code\` opens a browser and waits for interactive input. Never use this in an agent/CI context.
+
+| Flag | Description |
+|------|-------------|
+| \`--code <code>\` | Exchange a browser authorization code non-interactively |
+
+### \`whoami\` — Check authentication
+
+\`\`\`bash
+magicpath-ai whoami
+magicpath-ai whoami -o json
+\`\`\`
+
+### \`search\` — Search components across all projects
+
+\`\`\`bash
+magicpath-ai search "input"
+magicpath-ai search "button" -o json
+magicpath-ai search "card" --limit 5
+\`\`\`
+
+Fuzzy searches component names across all projects. Returns matches with project context.
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| \`--limit <n>\` | Max results | 20 |
+
+### \`list-projects\` — List all projects
+
+\`\`\`bash
+magicpath-ai list-projects
+magicpath-ai list-projects -o json
+\`\`\`
+
+### \`list-components\` — List components in a project
+
+\`\`\`bash
+magicpath-ai list-components <projectId>
+magicpath-ai list-components <projectId> -o json
+\`\`\`
+
+### \`view\` — Preview a component
+
+\`\`\`bash
+magicpath-ai view <generatedName>
+magicpath-ai view-component <generatedName>    # alias
+\`\`\`
+
+Opens the component preview URL in the default browser. In JSON mode, returns the URL without opening.
+
+### \`add\` — Add a component to your project
+
+> **IMPORTANT:** Only use \`add\` when you intend to import the component afterward. To inspect source code without installing, use \`add --inspect\`. After adding, always import and use the component — never add and then manually replicate its styles.
+
+\`\`\`bash
+magicpath-ai add <generatedName>
+magicpath-ai add <generatedName> -y              # skip prompts
+magicpath-ai add <generatedName> --inspect       # show source code (no install)
+magicpath-ai add <generatedName> --dry-run       # preview file list only
+magicpath-ai add <generatedName> -y --overwrite  # replace existing
+\`\`\`
+
+| Flag | Short | Description | Default |
+|------|-------|-------------|---------|
+| \`--yes\` | \`-y\` | Skip confirmation prompts | false |
+| \`--overwrite\` | \`-o\` | Overwrite existing files | false |
+| \`--path <path>\` | \`-p\` | Custom component path | src/components/magicpath |
+| \`--dry-run\` | | Preview file list without writing | false |
+| \`--inspect\` | | Show full source code without installing (implies --dry-run) | false |
+| \`--debug\` | \`-d\` | Enable debug logging | false |
+
+**\`--inspect\` vs \`--dry-run\`:** \`--dry-run\` shows file paths and dependencies. \`--inspect\` also shows the full source code of each file. Use \`--inspect\` when deciding whether a component fits your needs. In JSON mode, both include file contents.
+
+**JSON output** (\`-o json\`) automatically implies \`-y\` (no prompts).
+
+### \`integrate\` — AI-powered component integration
+
+\`\`\`bash
+magicpath-ai integrate <generatedName> <targetFile>
+\`\`\`
+
+Uses AI to integrate a component into a target file. Returns modified file contents — does NOT write files directly.
+
+### \`init\` — Set up for AI agents
+
+\`\`\`bash
+magicpath-ai init     # writes rules for Claude Code, Cursor, and GitHub Copilot
+\`\`\`
+
+### \`schema\` — Output JSON schemas
+
+\`\`\`bash
+magicpath-ai schema            # list available schemas
+magicpath-ai schema add        # schema for add command
+\`\`\``;
+// ── Editor-specific content ───────────────────────────────────────────
+function buildClaudeSkill() {
+    // Claude Code uses triple-escaped backticks in template literals since
+    // the content is embedded in a JS string in init.ts. But when we write
+    // the file directly, we use normal backticks.
+    return `---
+name: magicpath
+description: ${DESCRIPTION} Also triggers for magicpath-ai CLI usage.
+user-invocable: false
+allowed-tools: Bash(magicpath-ai *)
+---
+
+${SHARED_BODY}
+
+## Current Project Context
+
+\`\`\`json
+!\`magicpath-ai info --json 2>/dev/null || echo '{"error": "magicpath-ai not found. Run: npx magicpath-ai info --json"}'\`
+\`\`\`
+
+The JSON above contains auth status, projects, and CLI version. If auth.authenticated is false, the user needs to log in before any other operations.
+
+## Detailed References
+
+- [cli.md](./cli.md) — Full CLI command reference with all flags
+`;
+}
+function buildCursorRule() {
+    // Use single quotes to avoid escaping double quotes in YAML
+    const yamlDesc = DESCRIPTION.replace(/'/g, "''");
+    return `---
+description: '${yamlDesc}'
+alwaysApply: false
+---
+
+${SHARED_BODY}
+
+## CLI Reference
+
+${CLI_REFERENCE}
+`;
+}
+function buildCopilotInstructions() {
+    return `---
+applyTo: "**"
+---
+
+${SHARED_BODY}
+
+## CLI Reference
+
+${CLI_REFERENCE}
+`;
+}
+function getFileTargets() {
+    return [
+        // Claude Code
+        { path: '.claude/skills/magicpath/SKILL.md', content: buildClaudeSkill() },
+        { path: '.claude/skills/magicpath/cli.md', content: CLI_REFERENCE + '\n' },
+        // Cursor
+        { path: '.cursor/rules/magicpath.mdc', content: buildCursorRule() },
+        // GitHub Copilot
+        {
+            path: '.github/instructions/magicpath.instructions.md',
+            content: buildCopilotInstructions(),
+        },
+    ];
+}
+// ── Command ───────────────────────────────────────────────────────────
+export function registerInitCommand(program) {
+    program
+        .command('init')
+        .description('Set up MagicPath for AI agents (Claude Code, Cursor, GitHub Copilot)')
+        .action(async () => {
+        const cwd = process.cwd();
+        const json = isJsonMode();
+        const created = [];
+        // Write all editor rule files
+        for (const target of getFileTargets()) {
+            const absPath = path.join(cwd, target.path);
+            fs.ensureDirSync(path.dirname(absPath));
+            fs.writeFileSync(absPath, target.content, 'utf8');
+            created.push(target.path);
+            if (!json)
+                console.log(`${GREEN_CHECK} Created ${target.path}`);
+        }
+        if (json) {
+            jsonResult({ created });
+        }
+        if (created.length === 0) {
+            console.log('\nNothing to do — MagicPath is already configured.');
+        }
+        else {
+            console.log('\nMagicPath is ready for AI agents (Claude Code, Cursor, GitHub Copilot).');
+        }
+    });
+}
+//# sourceMappingURL=init.js.map

package/dist/commands/init.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.js","sourceRoot":"","sources":["../../src/commands/init.ts"],"names":[],"mappings":"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"}