@ahmednawaz/crank 0.2.0 → 0.2.3

package/AGENTS.md

@@ -105,33 +105,30 @@ See **[REPLIT.md](./REPLIT.md)** and `.crank/replit.md` (URLs after first run).
 
 ## Panel injection (Retune pattern)
 
-**Preferred for React apps** — install the package and mount once:
+**Preferred** — CLI inject (no manual edits):
 
 ```bash
-pnpm add -D @ahmednawaz/crank
-# or: npm i -D @ahmednawaz/crank
+npx @ahmednawaz/crank@latest setup
+npx @ahmednawaz/crank inject
+npx @ahmednawaz/crank start
 ```
 
+`inject` finds `main.tsx` / `createRoot` / `ReactDOM.render`, adds:
+
 ```tsx
 import { Crank } from '@ahmednawaz/crank/react'
-
-// main.tsx
-<App />
+// ...
 <Crank />
 ```
 
-Keep companion running: `npx @ahmednawaz/crank start`
-
-On Replit set public companion URL if needed: `window.__CRANK_URL__`, `<Crank companionUrl="…" />`, or `VITE_CRANK_URL`.
+Same idea as Sentry/Clerk setup CLIs. See `.crank/react-mount.md` after setup.
 
 | Stack | Integration |
 |-------|-------------|
-| **React + Vite** | `<Crank />` from `@ahmednawaz/crank/react` (bundled like Retune — **no Vite plugin**) |
-| **Next.js** | `<Crank />` from `@ahmednawaz/crank/next` |
-| **Vue / Svelte / vanilla Vite** | Optional `@ahmednawaz/crank/vite` plugin |
-| **Any** | Bookmarklet from companion URL |
-
-Agents: do **not** invent Vite-plugin path workarounds for React apps. See `.crank/react-mount.md` / `.crank/injection.md` after setup.
+| **React** | `npx @ahmednawaz/crank inject` |
+| **Next.js** | same inject, or `import { Crank } from '@ahmednawaz/crank/next'` |
+| **Non-React Vite** | Optional `@ahmednawaz/crank/vite` plugin |
+| **Fallback** | Companion bookmarklet |
 
 ---
 

package/README.md

@@ -102,35 +102,18 @@ No external sibling tool required. Crank ships:
 
 Optional: `CRANK_ASSET_ROOT` overrides where packaged UI assets are loaded from (defaults to this install).
 
-### Panel injection (Retune-style React)
-
-**Preferred** — install and mount like Retune:
+### Panel injection (Retune-style)
 
 ```bash
-pnpm add -D @ahmednawaz/crank
+npx @ahmednawaz/crank@latest setup
+npx @ahmednawaz/crank inject    # patches main.tsx — no manual edits
+npx @ahmednawaz/crank start
 ```
 
-```tsx
-import { Crank } from '@ahmednawaz/crank/react'
-
-createRoot(document.getElementById('root')!).render(
-  <>
-    <App />
-    <Crank />
-  </>
-)
-```
+`inject` installs the package and adds `import { Crank }` + `<Crank />` (Sentry/Clerk-style).
 
-Companion: `npx @ahmednawaz/crank start`  
 Replit public URL: `window.__CRANK_URL__` or `<Crank companionUrl="https://3344-….replit.dev" />` or `VITE_CRANK_URL`.
 
-| Stack | Integration |
-|-------|-------------|
-| **React** | `<Crank />` — bundled by Vite, **no plugin** |
-| **Next.js** | `import { Crank } from '@ahmednawaz/crank/next'` |
-| **Non-React Vite** | Optional `import { crank } from '@ahmednawaz/crank/vite'` |
-| **Fallback** | Companion bookmarklet |
-
 Useful variants:
 
 ```bash

package/bin/crank.js

@@ -31,6 +31,7 @@ const {
   readRuntimeManifest
 } = require('../lib/urls');
 const { resolveProjectRoot, describeEnvironment } = require('../lib/resolve-project');
+const { injectCrank } = require('../lib/wire-react');
 
 const LOG_FILE = env('LOG', '/tmp/crank-companion.log');
 const PID_FILE = env('PID_FILE', '/tmp/crank-companion.pid');
@@ -39,11 +40,12 @@ function printHelp() {
   process.stdout.write(`Usage: crank [command] [project-root]
 
 Commands:
-  (default)     Init + start everything (companion, MCP, dev server when present)
-  setup         Same as init — Retune-style one-time config (alias for init)
-  init          Only write IDE / Vite / MCP setup into the project
-  mcp           Start stdio MCP server (used by npx crank mcp in IDE configs)
-  start         Start companion (assumes init already done)
+  (default)     Init + start companion (and npm run dev when present)
+  setup         One-time config (MCP, skill, package.json) — alias for init
+  init          Same as setup
+  inject        Patch main.tsx / entry with import { Crank } + <Crank /> (Retune-style)
+  mcp           Start stdio MCP server (used by IDE MCP configs)
+  start         Start companion (assumes setup already done)
   stop          Stop daemon companion + HTTP MCP listeners
   doctor        Print detected environment + runtime URLs
   status        Print whether companion /health responds
@@ -60,11 +62,16 @@ Flags:
   --http-mcp    Force HTTP MCP (Replit auto-enables this)
   -h, --help    Show help
 
+First run (React / Retune-style):
+  npx @ahmednawaz/crank@latest setup
+  npx @ahmednawaz/crank inject
+  npx @ahmednawaz/crank start
+
 Examples:
-  cd ~/code/my-app && npx crank setup && npx crank
-  npx crank
-  npx crank mcp
-  npx crank stop
+  cd ~/code/my-app && npx @ahmednawaz/crank setup && npx @ahmednawaz/crank inject
+  npx @ahmednawaz/crank
+  npx @ahmednawaz/crank mcp
+  npx @ahmednawaz/crank stop
 `);
 }
 
@@ -113,7 +120,7 @@ function parseArgs(argv) {
   }
   let command = 'run';
   let projectRoot = process.cwd();
-  const cmds = new Set(['init', 'setup', 'start', 'doctor', 'stop', 'status', 'mcp']);
+  const cmds = new Set(['init', 'setup', 'start', 'doctor', 'stop', 'status', 'mcp', 'inject']);
   if (positional[0] === 'setup') {
     command = 'init';
   } else if (cmds.has(positional[0])) {
@@ -617,6 +624,41 @@ async function main() {
     return;
   }
 
+  if (command === 'inject') {
+    if (!fs.existsSync(projectRoot) || !fs.statSync(projectRoot).isDirectory()) {
+      console.error(`Project root not found: ${projectRoot}`);
+      process.exit(1);
+    }
+    console.log(`[Crank] Injecting <Crank /> into ${projectRoot}`);
+    const result = injectCrank(projectRoot, { install: true });
+    if (result.installed) {
+      console.log(`[Crank] Installed package (${result.installCommand})`);
+    } else if (result.installError) {
+      console.warn(`[Crank] Package install warning: ${result.installError}`);
+      if (result.installHint) {
+        console.warn(`[Crank] Run manually:\n  ${result.installHint}`);
+      } else {
+        console.warn('[Crank] Try: pnpm add -D @ahmednawaz/crank');
+      }
+    }
+    if (result.reactWire?.wired) {
+      console.log(`[Crank] Patched ${result.reactWire.file}`);
+      console.log('[Crank] Added: import { Crank } from \'@ahmednawaz/crank/react\' + <Crank />');
+      console.log('[Crank] Next: npx @ahmednawaz/crank start');
+      process.exit(0);
+    }
+    if (result.reactWire?.reason === 'already-present') {
+      console.log(`[Crank] Already injected in ${result.reactWire.file}`);
+      process.exit(0);
+    }
+    console.error(
+      `[Crank] Could not inject (${result.reactWire?.reason || 'unknown'}).` +
+        (result.reactWire?.file ? ` Looked at ${result.reactWire.file}.` : '') +
+        ' Add manually:\n\n  import { Crank } from \'@ahmednawaz/crank/react\'\n  <Crank />\n'
+    );
+    process.exit(1);
+  }
+
   if (!fs.existsSync(projectRoot) || !fs.statSync(projectRoot).isDirectory()) {
     console.error(`Project root not found: ${projectRoot}`);
     process.exit(1);

package/lib/init.js

@@ -12,6 +12,7 @@ const {
 
 const PACKAGE_ROOT = path.resolve(__dirname, '..');
 const { resolveUrls } = require('./urls');
+const { installCrankPackage } = require('./wire-react');
 
 function ensureGitignore(projectRoot) {
   const file = path.join(projectRoot, '.gitignore');
@@ -527,9 +528,7 @@ function initProject(projectRoot, options = {}) {
 
   // MCP + skill (Retune-style: global IDE config, automatic skill sync)
   if (options.mcp !== false) {
-    if (!env.isReplit) {
-      ensureCrankDependency(projectRoot, results);
-    }
+    ensureCrankDependency(projectRoot, results);
     configureMcpRetuneStyle(env, projectRoot, results, options);
   }
 
@@ -537,9 +536,10 @@ function initProject(projectRoot, options = {}) {
     installCrankSkill(projectRoot, results);
   }
 
-  // Retune-style: React apps mount <Crank /> — do not rely on Vite plugin path hacks.
+  // React apps: install dep + write out inject (Sentry/Clerk-style). Do not patch source here.
   if (env.hasReact && options.react !== false) {
     writeReactMountHint(projectRoot, env, results);
+    results.reactMount = true;
   } else if (env.hasVite && options.vite !== false) {
     const viteResult = patchViteConfig(projectRoot);
     results.vite = viteResult;
@@ -563,7 +563,7 @@ function initProject(projectRoot, options = {}) {
     const pkg = readJson(pkgPath, {});
     pkg.scripts = pkg.scripts || {};
     if (!pkg.scripts.crank) {
-      pkg.scripts.crank = 'crank';
+      pkg.scripts.crank = 'npx @ahmednawaz/crank';
       writeJson(pkgPath, pkg);
       results.wrote.push('package.json#scripts.crank');
     }
@@ -573,14 +573,9 @@ function initProject(projectRoot, options = {}) {
     writeReplitPlatformGuide(projectRoot, results);
   }
 
-  if (results.crankDependencyAdded && options.install !== false && !env.isReplit) {
-    try {
-      const { execSync } = require('child_process');
-      execSync('npm install', { cwd: projectRoot, stdio: 'inherit' });
-      results.installed = true;
-    } catch (err) {
-      results.installError = err.message;
-    }
+  if (options.install !== false && results.crankDependencyAdded) {
+    const install = installCrankPackage(projectRoot);
+    Object.assign(results, install);
   }
 
   return results;
@@ -717,27 +712,21 @@ function writeReactMountHint(projectRoot, env, results) {
     [
       '# Mount Crank (Retune-style)',
       '',
-      '1. Install (from the app package in a monorepo):',
+      'Run (preferred — no manual edits):',
       '',
       '```bash',
-      'pnpm add -D @ahmednawaz/crank',
-      '# or: npm i -D @ahmednawaz/crank',
+      'npx @ahmednawaz/crank inject',
       '```',
       '',
-      '2. Mount once near your app root (e.g. `main.tsx` / `App.tsx`):',
+      'That installs `@ahmednawaz/crank` and patches your entry file with:',
       '',
       '```tsx',
       "import { Crank } from '@ahmednawaz/crank/react'",
       '',
-      'createRoot(document.getElementById("root")!).render(',
-      '  <>',
-      '    <App />',
-      '    <Crank />',
-      '  </>',
-      ')',
+      '<Crank />',
       '```',
       '',
-      '3. Keep the companion running:',
+      'Then start the companion:',
       '',
       '```bash',
       'npx @ahmednawaz/crank start',
@@ -765,25 +754,23 @@ function writeInjectionGuide(projectRoot, env, results) {
   const lines = [
     '# Crank panel injection',
     '',
-    '## Preferred — React component (Retune pattern)',
+    '## Preferred — `npx @ahmednawaz/crank inject`',
     '',
-    'Crank ships a normal npm React export. Vite bundles it like any other dependency.',
-    '**No Vite plugin. No npx-cache paths.**',
+    'Patches your entry file automatically (Sentry/Clerk-style). No manual edits.',
     '',
     '```bash',
-    'pnpm add -D @ahmednawaz/crank',
+    'npx @ahmednawaz/crank@latest setup',
+    'npx @ahmednawaz/crank inject',
+    'npx @ahmednawaz/crank start',
     '```',
     '',
+    'Adds:',
+    '',
     '```tsx',
     "import { Crank } from '@ahmednawaz/crank/react'",
-    '',
-    '// main.tsx — mount once',
-    '<App />',
     '<Crank />',
     '```',
     '',
-    'Companion must be running: `npx @ahmednawaz/crank start`',
-    '',
     'URL resolution (first match):',
     '1. `window.__CRANK_URL__`',
     '2. `<Crank companionUrl="…" />` / `url` prop',
@@ -794,9 +781,8 @@ function writeInjectionGuide(projectRoot, env, results) {
     '',
     '## Next.js',
     '',
-    '```tsx',
-    "import { Crank } from '@ahmednawaz/crank/next'",
-    '<Crank />',
+    '```bash',
+    'npx @ahmednawaz/crank inject',
     '```',
     '',
     '## Non-React Vite (Vue / Svelte / vanilla)',
@@ -830,14 +816,15 @@ function printSetupNextSteps(env, runtime, results) {
     console.log('    • Skill crank-apply-changes installed (auto-syncs on start)');
   }
   if (results?.reactMount || env.hasReact) {
-    console.log('    • React: mount <Crank /> from @ahmednawaz/crank/react (see .crank/react-mount.md)');
+    console.log('    • Next: npx @ahmednawaz/crank inject   # patches main.tsx with <Crank />');
   } else if (results?.vite?.patched) {
     console.log('    • Vite plugin patched (non-React stack)');
   } else if (env.hasVite) {
     console.log('    • Vite detected — see .crank/injection.md');
   } else if (env.hasNext) {
-    console.log('    • Next.js — mount <Crank /> from @ahmednawaz/crank/next');
+    console.log('    • Next.js — run: npx @ahmednawaz/crank inject');
   }
+  console.log('    • Then: npx @ahmednawaz/crank start');
   console.log('    • Injection guide: .crank/injection.md');
   if (env.isReplit) {
     console.log('    • Workflow command: npx @ahmednawaz/crank start');

package/lib/wire-react.js

@@ -0,0 +1,408 @@
+'use strict';
+
+/**
+ * Auto-wire Retune-style <Crank /> into the app entry file (Sentry/Clerk-style inject).
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { exists } = require('./detect');
+
+const ENTRY_CANDIDATES = [
+  'src/main.tsx',
+  'src/main.jsx',
+  'src/main.ts',
+  'src/main.js',
+  'src/index.tsx',
+  'src/index.jsx',
+  'src/index.ts',
+  'src/index.js',
+  'client/src/main.tsx',
+  'client/src/main.jsx',
+  'client/src/index.tsx',
+  'app/main.tsx',
+  'src/App.tsx',
+  'src/App.jsx',
+  'App.tsx',
+  'App.jsx',
+  'main.tsx',
+  'main.jsx',
+  'index.tsx',
+  'index.jsx'
+];
+
+const SKIP_DIRS = new Set([
+  'node_modules',
+  '.git',
+  'dist',
+  'build',
+  '.next',
+  'coverage',
+  '.turbo',
+  '.cache',
+  '.crank'
+]);
+
+function findEntryByCreateRoot(projectRoot) {
+  const queue = [{ dir: path.resolve(projectRoot), depth: 0 }];
+  const hits = [];
+  while (queue.length) {
+    const { dir, depth } = queue.shift();
+    if (depth > 3) continue;
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (!SKIP_DIRS.has(entry.name) && !entry.name.startsWith('.')) {
+          queue.push({ dir: full, depth: depth + 1 });
+        }
+        continue;
+      }
+      if (!/\.(tsx|jsx|ts|js)$/.test(entry.name)) continue;
+      let src;
+      try {
+        src = fs.readFileSync(full, 'utf8');
+      } catch {
+        continue;
+      }
+      if (
+        /createRoot\s*\(/.test(src) ||
+        /ReactDOM\.render\s*\(/.test(src) ||
+        /hydrateRoot\s*\(/.test(src)
+      ) {
+        hits.push(full);
+      }
+    }
+  }
+  // Prefer main/index over App
+  hits.sort((a, b) => {
+    const score = (p) => {
+      const base = path.basename(p).toLowerCase();
+      if (base.startsWith('main')) return 0;
+      if (base.startsWith('index')) return 1;
+      return 2;
+    };
+    return score(a) - score(b);
+  });
+  return hits[0] || null;
+}
+
+function findEntry(projectRoot) {
+  for (const rel of ENTRY_CANDIDATES) {
+    const full = path.join(projectRoot, rel);
+    if (exists(full)) {
+      return full;
+    }
+  }
+  return findEntryByCreateRoot(projectRoot);
+}
+
+function alreadyWired(source) {
+  return (
+    /@ahmednawaz\/crank\/react/.test(source) ||
+    /from ['"]@ahmednawaz\/crank['"]/.test(source) ||
+    /<Crank[\s/>]/.test(source)
+  );
+}
+
+function insertImport(source) {
+  const importLine = `import { Crank } from '@ahmednawaz/crank/react';`;
+  const matches = [...source.matchAll(/^import\s.+;?\s*$/gm)];
+  if (matches.length) {
+    const last = matches[matches.length - 1];
+    const idx = last.index + last[0].length;
+    return source.slice(0, idx) + `\n${importLine}` + source.slice(idx);
+  }
+  return `${importLine}\n${source}`;
+}
+
+function insertCrankJsx(source) {
+  if (/<Crank[\s/>]/.test(source)) {
+    return { source, patched: true };
+  }
+
+  if (/<StrictMode>/.test(source)) {
+    return {
+      source: source.replace(/(<StrictMode>\s*)/, '$1\n    <Crank />\n    '),
+      patched: true
+    };
+  }
+
+  if (/\.render\s*\(\s*<>/.test(source) || /\.render\s*\(\s*<React\.Fragment>/.test(source)) {
+    return {
+      source: source.replace(/(<>\s*|<React\.Fragment>\s*)/, '$1\n    <Crank />\n    '),
+      patched: true
+    };
+  }
+
+  // createRoot(...).render(<App />) or multi-line JSX root
+  if (/\.render\s*\(/.test(source)) {
+    // Single-line: .render(<App />)
+    let next = source.replace(
+      /\.render\s*\(\s*(<(?!>)[^]*?>)\s*\)/m,
+      '.render(\n  <>\n    $1\n    <Crank />\n  </>\n)'
+    );
+    if (next !== source && /<Crank[\s/>]/.test(next)) {
+      return { source: next, patched: true };
+    }
+
+    // Multi-line root starting with <Something
+    next = source.replace(
+      /(\.render\s*\(\s*\n\s*)(<[A-Za-z/])/,
+      '$1<>\n    <Crank />\n    $2'
+    );
+    if (next !== source) {
+      // close fragment before the render's closing paren — best effort
+      next = next.replace(
+        /(\.render\s*\([\s\S]*?)(\n\s*\))/,
+        (match, body, close) => {
+          if (body.includes('<Crank') && !body.includes('</>')) {
+            return `${body}\n  </>${close}`;
+          }
+          return match;
+        }
+      );
+      if (/<Crank[\s/>]/.test(next)) {
+        return { source: next, patched: true };
+      }
+    }
+  }
+
+  if (/ReactDOM\.render\s*\(/.test(source)) {
+    const next = source.replace(
+      /ReactDOM\.render\s*\(\s*(<(?!>)[^]*?>)\s*,/,
+      'ReactDOM.render(\n  <>\n    $1\n    <Crank />\n  </>,'
+    );
+    if (next !== source && /<Crank[\s/>]/.test(next)) {
+      return { source: next, patched: true };
+    }
+  }
+
+  if (/<App\b[^/]*?\/>/.test(source)) {
+    return {
+      source: source.replace(/(<App\b[^/]*?\/>)/, '<Crank />\n      $1'),
+      patched: true
+    };
+  }
+  if (/<App\b[^>]*>/.test(source)) {
+    return {
+      source: source.replace(/(<App\b[^>]*>)/, '<Crank />\n      $1'),
+      patched: true
+    };
+  }
+
+  return { source, patched: false };
+}
+
+/**
+ * Patch the React entry to mount <Crank />. Idempotent.
+ * @returns {{ wired: boolean, reason?: string, file?: string }}
+ */
+function wireReactEntry(projectRoot) {
+  const entryPath = findEntry(projectRoot);
+  if (!entryPath) {
+    return { wired: false, reason: 'no-entry' };
+  }
+
+  let source = fs.readFileSync(entryPath, 'utf8');
+  if (alreadyWired(source)) {
+    return { wired: false, reason: 'already-present', file: entryPath };
+  }
+
+  source = insertImport(source);
+  const { source: next, patched } = insertCrankJsx(source);
+  source = next;
+
+  if (!patched) {
+    return { wired: false, reason: 'unrecognized-entry-shape', file: entryPath };
+  }
+
+  fs.writeFileSync(entryPath, source);
+  return { wired: true, file: entryPath };
+}
+
+function findPnpmWorkspaceRoot(startDir) {
+  let dir = path.resolve(startDir);
+  for (let i = 0; i < 12; i++) {
+    if (
+      exists(path.join(dir, 'pnpm-workspace.yaml')) ||
+      exists(path.join(dir, 'pnpm-workspace.yml'))
+    ) {
+      return dir;
+    }
+    // lockfile alone can mean pnpm without workspaces
+    if (exists(path.join(dir, 'pnpm-lock.yaml')) && i === 0) {
+      return dir;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  // Prefer ancestor with lockfile if no workspace file
+  dir = path.resolve(startDir);
+  for (let i = 0; i < 12; i++) {
+    if (exists(path.join(dir, 'pnpm-lock.yaml'))) {
+      return dir;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+function readPackageName(projectRoot) {
+  try {
+    const pkg = JSON.parse(
+      fs.readFileSync(path.join(projectRoot, 'package.json'), 'utf8')
+    );
+    return pkg.name || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Build install attempts for this project (pnpm monorepo-aware).
+ * Never uses npm as a fallback inside a pnpm workspace.
+ */
+function detectInstallAttempts(projectRoot) {
+  const root = path.resolve(projectRoot);
+  const pnpmRoot = findPnpmWorkspaceRoot(root);
+  const attempts = [];
+
+  if (pnpmRoot) {
+    const isWorkspace = exists(path.join(pnpmRoot, 'pnpm-workspace.yaml')) ||
+      exists(path.join(pnpmRoot, 'pnpm-workspace.yml'));
+    const pkgName = readPackageName(root);
+    const relFilter = path.relative(pnpmRoot, root).replace(/\\/g, '/') || '.';
+
+    // 1) From the package directory (works when cwd is the workspace package)
+    attempts.push({
+      cmd: 'pnpm',
+      args: ['add', '-D', '@ahmednawaz/crank'],
+      cwd: root,
+      label: `pnpm add -D @ahmednawaz/crank (in ${relFilter})`
+    });
+
+    if (isWorkspace && pnpmRoot !== root) {
+      // 2) From monorepo root with --filter by package name
+      if (pkgName) {
+        attempts.push({
+          cmd: 'pnpm',
+          args: ['add', '-D', '@ahmednawaz/crank', '--filter', pkgName],
+          cwd: pnpmRoot,
+          label: `pnpm add -D @ahmednawaz/crank --filter ${pkgName}`
+        });
+      }
+      // 3) From monorepo root with --filter by path
+      attempts.push({
+        cmd: 'pnpm',
+        args: ['add', '-D', '@ahmednawaz/crank', '--filter', `./${relFilter}`],
+        cwd: pnpmRoot,
+        label: `pnpm add -D @ahmednawaz/crank --filter ./${relFilter}`
+      });
+    }
+
+    return attempts;
+  }
+
+  if (exists(path.join(root, 'yarn.lock'))) {
+    return [
+      {
+        cmd: 'yarn',
+        args: ['add', '-D', '@ahmednawaz/crank'],
+        cwd: root,
+        label: 'yarn add -D @ahmednawaz/crank'
+      }
+    ];
+  }
+
+  return [
+    {
+      cmd: 'npm',
+      args: ['install', '-D', '@ahmednawaz/crank'],
+      cwd: root,
+      label: 'npm install -D @ahmednawaz/crank'
+    }
+  ];
+}
+
+function detectInstallCommand(projectRoot) {
+  const attempts = detectInstallAttempts(projectRoot);
+  const first = attempts[0];
+  return { cmd: first.cmd, args: first.args, cwd: first.cwd };
+}
+
+function installCrankPackage(projectRoot) {
+  const { execFileSync } = require('child_process');
+  const attempts = detectInstallAttempts(projectRoot);
+  const result = {
+    installed: false,
+    installCommand: attempts[0]?.label || '',
+    installAttempts: []
+  };
+
+  for (const attempt of attempts) {
+    result.installAttempts.push(attempt.label);
+    try {
+      execFileSync(attempt.cmd, attempt.args, {
+        cwd: attempt.cwd,
+        stdio: 'inherit',
+        env: process.env
+      });
+      result.installed = true;
+      result.installCommand = attempt.label;
+      delete result.installError;
+      return result;
+    } catch (err) {
+      result.installError = err.message;
+    }
+  }
+
+  // Hint for humans / agents — do not npm-install into a pnpm monorepo
+  const pkgName = readPackageName(projectRoot);
+  if (findPnpmWorkspaceRoot(projectRoot)) {
+    result.installHint = pkgName
+      ? `pnpm add -D @ahmednawaz/crank --filter ${pkgName}`
+      : `pnpm add -D @ahmednawaz/crank --filter ${path.basename(projectRoot)}`;
+  }
+
+  return result;
+}
+
+/**
+ * Full inject flow: ensure dep → install → patch entry.
+ */
+function injectCrank(projectRoot, options = {}) {
+  const results = {
+    projectRoot,
+    wrote: []
+  };
+
+  if (options.install !== false) {
+    Object.assign(results, installCrankPackage(projectRoot));
+  }
+
+  const wire = wireReactEntry(projectRoot);
+  results.reactWire = wire;
+  if (wire.wired && wire.file) {
+    results.wrote.push(path.relative(projectRoot, wire.file));
+  }
+  return results;
+}
+
+module.exports = {
+  wireReactEntry,
+  installCrankPackage,
+  injectCrank,
+  findEntry,
+  detectInstallCommand,
+  detectInstallAttempts,
+  findPnpmWorkspaceRoot
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ahmednawaz/crank",
-  "version": "0.2.0",
+  "version": "0.2.3",
   "description": "Internal Motive UX copy iteration: select UI text → Glean variants → MCP apply. Cursor, Replit, Claude.",
   "repository": {
     "type": "git",

package/skill/SKILL.md

@@ -33,7 +33,7 @@ When the user asks to start Crank:
    ```
    `start` skips setup/init — companion on **3344** (+ HTTP MCP on **3345** on Replit). Add `CRANK_TEAM_TOKEN` in Secrets first.
 4. Call **`crank_get_environment`** after the companion is up.
-5. **Panel (React):** `pnpm add -D @ahmednawaz/crank` then mount `<Crank />` from `@ahmednawaz/crank/react` in `main.tsx` (Retune pattern — no Vite plugin). Keep companion Workflow running. See `.crank/react-mount.md`.
+5. **Panel:** `npx @ahmednawaz/crank inject` patches `main.tsx` with `<Crank />` (no manual edits). Then keep companion Workflow running with `npx @ahmednawaz/crank start`.
 
 ## When the user says "start Crank" or pastes `npx crank`