@rahul_ur/devlink 1.0.0

package/README.md

@@ -0,0 +1,168 @@
+# devlink
+
+Click any element in your browser → jump to its source code → edit it → UI updates live.
+
+Works with **Vite**, **Next.js**, and **CRA**. Fully local — no cloud, no API keys.
+
+---
+
+## Install
+
+```bash
+npm install @rahul_ur/devlink
+npm install -D @rahul_ur/devlink-babel-plugin @rahul_ur/devlink-vite-plugin
+```
+
+---
+
+## Setup (one command)
+
+```bash
+npx devlink setup
+```
+
+This automatically:
+- Detects your framework (Vite / Next.js / CRA)
+- Patches your `vite.config.ts` or `.babelrc`
+- Creates `devlink.config.ts` with your project paths
+- Adds `devlink:bridge` script to `package.json`
+
+---
+
+## Add to your app entry
+
+```tsx
+// src/main.tsx (Vite) or pages/_app.tsx (Next.js)
+import { DevlinkBridge } from '@rahul_ur/devlink-bridge'
+import { DevlinkStudio } from '@rahul_ur/devlink-studio'
+import { devlinkConfig } from '../devlink.config'
+
+const bridge = new DevlinkBridge()
+
+function Root() {
+  return (
+    <DevlinkStudio bridge={bridge} {...devlinkConfig}>
+      <App />
+    </DevlinkStudio>
+  )
+}
+```
+
+---
+
+## Start the bridge server
+
+Open a separate terminal and keep it running:
+
+```bash
+npm run devlink:bridge
+```
+
+---
+
+## Use it
+
+Start your app normally (`npm run dev`) then:
+
+| Action | How |
+|--------|-----|
+| Toggle inspect mode | `Alt+D` |
+| Click element → open source | Click any element |
+| Box select multiple | `⬚ Box` button then drag |
+| Area capture | Hold `+` and drag |
+| Save file | `Ctrl+S` |
+| Exit inspect mode | `Esc` or right-click |
+
+---
+
+## Vite config (manual)
+
+If auto-setup didn't patch your config:
+
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+import { devlinkBabelConfig } from '@rahul_ur/devlink-vite-plugin'
+
+export default defineConfig({
+  plugins: [
+    react({
+      babel: {
+        plugins: [
+          devlinkBabelConfig({ root: process.cwd() }),
+        ].filter(Boolean),
+      },
+    }),
+  ],
+})
+```
+
+---
+
+## Next.js config (manual)
+
+```json
+// .babelrc
+{
+  "presets": ["next/babel"],
+  "env": {
+    "development": {
+      "plugins": [
+        ["@rahul_ur/devlink-babel-plugin", { "root": ".", "envs": ["development"] }]
+      ]
+    }
+  }
+}
+```
+
+---
+
+## DevlinkStudio props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `bridge` | `DevlinkBridge` | required | Bridge instance |
+| `projectRoot` | `string` | required | Absolute path to your project root |
+| `rootPath` | `string` | required | Path shown in file tree (usually `projectRoot/src`) |
+| `defaultDocked` | `boolean` | `false` | Start editor docked to the right |
+| `dockedWidth` | `number` | `460` | Width of docked panel in px |
+| `enabled` | `boolean` | `NODE_ENV=development` | Disable entirely in production |
+
+---
+
+## Packages
+
+This package installs all of these automatically:
+
+| Package | Purpose |
+|---------|---------|
+| `@rahul_ur/devlink-bridge` | WebSocket tunnel between browser and local filesystem |
+| `@rahul_ur/devlink-studio` | Floating Monaco editor + inspector + terminal + AI bar |
+| `@rahul_ur/devlink-babel-plugin` | Stamps `data-source` on every JSX element at build time |
+| `@rahul_ur/devlink-vite-plugin` | Wires babel plugin into Vite + React automatically |
+
+---
+
+## How it works
+
+```
+Your browser app
+  → clicks element
+  → reads data-source="src/Button.tsx:9:4" (stamped by babel plugin)
+  → sends to bridge over local WebSocket
+  → bridge reads file from disk
+  → editor opens file, highlights lines
+  → you edit + Ctrl+S
+  → bridge writes to disk
+  → HMR reloads your app
+  → UI updates
+```
+
+Everything stays on your machine. No cloud. No uploads.
+
+---
+
+## License
+
+MIT

package/bin/cli.mjs

@@ -0,0 +1,285 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import { execSync } from 'node:child_process';
+
+const projectRoot = process.cwd();
+const args = process.argv.slice(2);
+const command = args[0] || 'setup';
+
+const log  = (msg) => console.log(`\x1b[36m[devlink]\x1b[0m ${msg}`);
+const ok   = (msg) => console.log(`\x1b[32m[devlink] ✓\x1b[0m ${msg}`);
+const warn = (msg) => console.warn(`\x1b[33m[devlink] ⚠\x1b[0m ${msg}`);
+const err  = (msg) => console.error(`\x1b[31m[devlink] ✗\x1b[0m ${msg}`);
+
+function exists(p) { return fs.existsSync(p); }
+function readJson(p) { return JSON.parse(fs.readFileSync(p, 'utf8')); }
+function writeJson(p, v) { fs.writeFileSync(p, `${JSON.stringify(v, null, 2)}\n`); }
+
+// ─── Detect framework ─────────────────────────────────────────────────────────
+
+function detectFramework() {
+  const pkgPath = path.join(projectRoot, 'package.json');
+  if (!exists(pkgPath)) return 'unknown';
+  const pkg = readJson(pkgPath);
+  const all = { ...pkg.dependencies, ...pkg.devDependencies };
+  if (all['react-scripts'])        return 'cra';
+  if (all['next'])                 return 'next';
+  if (all['vite'] || all['@vitejs/plugin-react']) return 'vite';
+  return 'unknown';
+}
+
+// ─── Add npm scripts ──────────────────────────────────────────────────────────
+
+function addScripts() {
+  const pkgPath = path.join(projectRoot, 'package.json');
+  if (!exists(pkgPath)) return;
+  const pkg = readJson(pkgPath);
+  pkg.scripts = pkg.scripts || {};
+  let changed = false;
+  if (!pkg.scripts['devlink:bridge']) {
+    pkg.scripts['devlink:bridge'] = 'node node_modules/@rahul_ur/devlink-bridge/server.mjs';
+    changed = true;
+  }
+  if (changed) { writeJson(pkgPath, pkg); ok('added devlink:bridge script to package.json'); }
+}
+
+// ─── Setup Vite ───────────────────────────────────────────────────────────────
+
+function setupVite() {
+  const candidates = ['vite.config.ts', 'vite.config.js', 'vite.config.mts', 'vite.config.mjs'];
+  const configFile = candidates.find(f => exists(path.join(projectRoot, f)));
+
+  if (!configFile) {
+    // Create vite.config.ts from scratch
+    const content = `import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import { devlinkBabelConfig } from '@rahul_ur/devlink-vite-plugin';
+
+export default defineConfig({
+  plugins: [
+    react({
+      babel: {
+        plugins: [
+          devlinkBabelConfig({ root: process.cwd() }),
+        ].filter(Boolean),
+      },
+    }),
+  ],
+});
+`;
+    fs.writeFileSync(path.join(projectRoot, 'vite.config.ts'), content);
+    ok('created vite.config.ts with devlink config');
+    return;
+  }
+
+  const configPath = path.join(projectRoot, configFile);
+  let src = fs.readFileSync(configPath, 'utf8');
+
+  if (src.includes('@rahul_ur/devlink-vite-plugin') || src.includes('@rahul_ur/devlink-babel-plugin')) {
+    ok(`${configFile} already has devlink config`);
+    return;
+  }
+
+  // Add import line after last import
+  const importLine = `import { devlinkBabelConfig } from '@rahul_ur/devlink-vite-plugin';\n`;
+  const lastImport = src.lastIndexOf('\nimport ');
+  const insertAt = lastImport === -1 ? 0 : src.indexOf('\n', lastImport) + 1;
+  src = src.slice(0, insertAt) + importLine + src.slice(insertAt);
+
+  // Patch react() call
+  if (src.includes('react()')) {
+    src = src.replace(
+      'react()',
+      `react({\n    babel: {\n      plugins: [devlinkBabelConfig({ root: process.cwd() })].filter(Boolean),\n    },\n  })`
+    );
+    ok(`patched ${configFile} — react() updated`);
+  } else if (src.match(/react\s*\(\s*\{/)) {
+    warn(`Could not auto-patch ${configFile}. Add manually:\n\n  react({ babel: { plugins: [devlinkBabelConfig({ root: process.cwd() })] } })\n`);
+  }
+
+  fs.writeFileSync(configPath, src);
+  ok(`updated ${configFile}`);
+}
+
+// ─── Setup Next.js ────────────────────────────────────────────────────────────
+
+function setupNext() {
+  const babelRcPath = path.join(projectRoot, '.babelrc');
+  const plugin = ['@rahul_ur/devlink-babel-plugin', { root: '.', envs: ['development'] }];
+
+  if (exists(babelRcPath)) {
+    const babelRc = readJson(babelRcPath);
+    babelRc.env = babelRc.env || {};
+    babelRc.env.development = babelRc.env.development || {};
+    babelRc.env.development.plugins = babelRc.env.development.plugins || [];
+    const already = babelRc.env.development.plugins.some(p =>
+      (Array.isArray(p) ? p[0] : p) === '@rahul_ur/devlink-babel-plugin'
+    );
+    if (!already) {
+      babelRc.env.development.plugins.push(plugin);
+      writeJson(babelRcPath, babelRc);
+      ok('patched .babelrc for Next.js');
+    } else {
+      ok('.babelrc already has devlink config');
+    }
+  } else {
+    writeJson(babelRcPath, {
+      presets: ['next/babel'],
+      env: { development: { plugins: [plugin] } }
+    });
+    ok('created .babelrc for Next.js');
+    warn('Adding .babelrc disables Next.js SWC compiler in development.');
+  }
+}
+
+// ─── Setup CRA ────────────────────────────────────────────────────────────────
+
+function setupCra() {
+  const configPath = path.join(projectRoot, 'node_modules', 'react-scripts', 'config', 'webpack.config.js');
+  if (!exists(configPath)) {
+    warn('CRA webpack config not found. Run npm install first then run devlink setup again.');
+    return;
+  }
+  let src = fs.readFileSync(configPath, 'utf8');
+  if (src.includes('@rahul_ur/devlink-babel-plugin')) { ok('CRA already patched'); return; }
+
+  const marker = "const createEnvironmentHash = require('./webpack/persistentCache/createEnvironmentHash');";
+  if (src.includes(marker)) {
+    src = src.replace(marker, `${marker}\nconst devlinkPlugin = require.resolve('@rahul_ur/devlink-babel-plugin');`);
+  }
+  const refreshLine = "isEnvDevelopment &&\n                    shouldUseReactRefresh &&\n                    require.resolve('react-refresh/babel'),";
+  if (src.includes(refreshLine)) {
+    src = src.replace(refreshLine,
+      `isEnvDevelopment && [devlinkPlugin, { root: paths.appPath, envs: ['development'] }],\n                  ${refreshLine}`
+    );
+  }
+  fs.writeFileSync(configPath, src);
+  ok('patched CRA webpack config');
+}
+
+// ─── Generate devlink.config.ts ───────────────────────────────────────────────
+
+function generateConfig() {
+  const configPath = path.join(projectRoot, 'devlink.config.ts');
+  if (exists(configPath)) { ok('devlink.config.ts already exists'); return; }
+
+  const root = projectRoot.replace(/\\/g, '/');
+  const srcDir = exists(path.join(projectRoot, 'src')) ? `${root}/src` : root;
+
+  fs.writeFileSync(configPath, `// devlink.config.ts — edit projectRoot and rootPath for your project
+export const devlinkConfig = {
+  projectRoot: '${root}',
+  rootPath: '${srcDir}',
+  defaultDocked: true,
+  dockedWidth: 460,
+};
+`);
+  ok('created devlink.config.ts');
+}
+
+// ─── Print main.tsx instructions ──────────────────────────────────────────────
+
+function printInstructions(framework) {
+  const isNext = framework === 'next';
+  console.log('\n\x1b[36m─────────────────────────────────────────────────\x1b[0m');
+  console.log('\x1b[36m devlink setup complete — final step:\x1b[0m');
+  console.log('\x1b[36m─────────────────────────────────────────────────\x1b[0m\n');
+
+  if (isNext) {
+    console.log('Add to pages/_app.tsx:\n');
+    console.log(`  import { DevlinkBridge } from '@rahul_ur/devlink-bridge'
+  import { DevlinkStudio } from '@rahul_ur/devlink-studio'
+  import { devlinkConfig } from '../devlink.config'
+
+  const bridge = new DevlinkBridge()
+
+  export default function App({ Component, pageProps }) {
+    return (
+      <DevlinkStudio bridge={bridge} {...devlinkConfig}>
+        <Component {...pageProps} />
+      </DevlinkStudio>
+    )
+  }`);
+  } else {
+    console.log('Add to src/main.tsx:\n');
+    console.log(`  import { DevlinkBridge } from '@rahul_ur/devlink-bridge'
+  import { DevlinkStudio } from '@rahul_ur/devlink-studio'
+  import { devlinkConfig } from '../devlink.config'
+
+  const bridge = new DevlinkBridge()
+
+  function Root() {
+    return (
+      <DevlinkStudio bridge={bridge} {...devlinkConfig}>
+        <App />
+      </DevlinkStudio>
+    )
+  }
+
+  ReactDOM.createRoot(document.getElementById('root')!).render(
+    <React.StrictMode><Root /></React.StrictMode>
+  )`);
+  }
+
+  console.log('\nThen start the bridge server:\n');
+  console.log('  npm run devlink:bridge\n');
+  console.log('Press \x1b[36mAlt+D\x1b[0m in the browser to activate inspect mode.\n');
+  console.log('\x1b[36m─────────────────────────────────────────────────\x1b[0m\n');
+}
+
+// ─── Commands ─────────────────────────────────────────────────────────────────
+
+function runSetup() {
+  log(`setting up devlink in ${projectRoot}`);
+  const framework = detectFramework();
+  log(`detected framework: ${framework}`);
+
+  addScripts();
+
+  if (framework === 'vite')        setupVite();
+  else if (framework === 'next')   setupNext();
+  else if (framework === 'cra')    setupCra();
+  else {
+    warn('Could not detect framework. Supported: Vite, Next.js, CRA.');
+    warn('Add @rahul_ur/devlink-babel-plugin manually to your build config.');
+  }
+
+  generateConfig();
+  printInstructions(framework);
+}
+
+function runHelp() {
+  console.log(`
+\x1b[36mdevlink\x1b[0m — click any element in your browser, jump to source, edit, UI updates live.
+
+\x1b[1mCommands:\x1b[0m
+  devlink setup    Auto-configure your project (Vite / Next.js / CRA)
+  devlink help     Show this help message
+
+\x1b[1mQuick start:\x1b[0m
+  npm install @rahul_ur/devlink
+  npx devlink setup
+  npm run devlink:bridge
+
+\x1b[1mKeyboard shortcuts:\x1b[0m
+  Alt+D            Toggle inspect mode
+  Esc              Exit inspect mode
+  + drag           Area selection
+  Ctrl+S           Save + format
+
+\x1b[1mPackages installed:\x1b[0m
+  @rahul_ur/devlink-bridge         WebSocket tunnel
+  @rahul_ur/devlink-studio         Floating editor + inspector
+  @rahul_ur/devlink-babel-plugin   Stamps data-source at build time
+  @rahul_ur/devlink-vite-plugin    Wires plugin into Vite automatically
+
+\x1b[1mDocs:\x1b[0m https://github.com/rahul_ur/devlink
+`);
+}
+
+// ─── Run ──────────────────────────────────────────────────────────────────────
+
+if (command === 'setup' || command === '') runSetup();
+else if (command === 'help' || command === '--help' || command === '-h') runHelp();
+else { err(`Unknown command: ${command}`); runHelp(); }

package/index.d.ts

@@ -0,0 +1,5 @@
+// @rahul_ur/devlink — type declarations
+
+export { DevlinkBridge } from '@rahul_ur/devlink-bridge';
+export { DevlinkStudio, FloatingWindow, useDeleteElement, useScreenCapture } from '@rahul_ur/devlink-studio';
+export { devlinkVitePlugin, devlinkBabelConfig } from '@rahul_ur/devlink-vite-plugin';

package/index.js

@@ -0,0 +1,6 @@
+// @rahul_ur/devlink
+// Convenience re-exports — import from here or directly from each package
+
+export { DevlinkBridge } from '@rahul_ur/devlink-bridge';
+export { DevlinkStudio, FloatingWindow, useDeleteElement, useScreenCapture } from '@rahul_ur/devlink-studio';
+export { devlinkVitePlugin, devlinkBabelConfig } from '@rahul_ur/devlink-vite-plugin';

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@rahul_ur/devlink",
+  "version": "1.0.0",
+  "description": "Click any element in your browser → jump to source code → edit → UI updates live. One command setup for Vite, Next.js and CRA.",
+  "main": "index.js",
+  "bin": {
+    "devlink": "./bin/cli.mjs",
+    "devlink-setup": "./bin/cli.mjs"
+  },
+  "files": [
+    "bin",
+    "templates",
+    "index.js",
+    "index.d.ts",
+    "README.md"
+  ],
+  "scripts": {
+    "prepublishOnly": "npm pack --dry-run"
+  },
+  "keywords": [
+    "devlink",
+    "devtools",
+    "react",
+    "vite",
+    "nextjs",
+    "inspector",
+    "source-map",
+    "live-reload",
+    "monaco",
+    "editor",
+    "babel-plugin"
+  ],
+  "author": "Rahul <your@email.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/rahul_ur/devlink"
+  },
+  "bugs": {
+    "url": "https://github.com/rahul_ur/devlink/issues"
+  },
+  "homepage": "https://github.com/rahul_ur/devlink#readme",
+  "dependencies": {
+    "@rahul_ur/devlink-bridge": "^1.0.0",
+    "@rahul_ur/devlink-studio": "^1.0.0",
+    "@rahul_ur/devlink-babel-plugin": "^1.0.0",
+    "@rahul_ur/devlink-vite-plugin": "^1.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}