node-link-local 1.0.0-alpha.2

package/README.md

@@ -0,0 +1,88 @@
+# node-link-local
+
+Sync a local npm package into another project via staged tarballs.  
+Works with **pnpm**, **yarn**, and **npm** in any combination (e.g. library uses pnpm, app uses yarn).
+
+Replaces the need for `npm link` / `yarn link` with a workspace-safe flow: the library is packed into a tarball, staged in the app’s `.local-packages/`, and installed from that file. No symlinks, no cross-workspace protocol issues.
+
+**Run commands from your app directory.** The app is always the current directory (cwd).
+
+### Why node-link-local instead of yalc?
+
+[Yalc](https://github.com/wclr/yalc) is a popular “local package” tool, but it relies on symlinks (with `yalc link`) or on copying into `.yalc/` and `file:` references. That can cause real pain when developing and running tests locally:
+
+- **Symlinks and test runners**  
+  When the consumer’s `node_modules` contains symlinks into your local package, tools like Jest can resolve the same module via two paths (symlink path vs. real path). That can lead to duplicate module instances, flaky tests, or the need for `--preserve-symlinks` and extra config. With node-link-local, the app gets a normal install from a tarball—no symlinks—so test runners see a single, consistent module tree.
+
+- **File watchers and memory**  
+  Dev servers and test runners often watch `node_modules`. If they follow symlinks, they can end up watching the entire linked package repo (including its own `node_modules` and build artifacts). That can mean thousands of extra files, high memory use, and slow or crashing processes. Node-link-local installs a plain directory from a tarball, so watchers don’t follow a link into another repo.
+
+- **Bundlers and frameworks**  
+  Webpack 5 and Next.js have known issues with symlinked packages (e.g. [Next.js #35110](https://github.com/vercel/next.js/issues/35110), [yalc #188](https://github.com/wclr/yalc/issues/188)): symlinked ESM packages can be bundled as internal instead of external, or resolution can break. Node-link-local avoids that by not using symlinks at all.
+
+- **Nested dependencies**  
+  Yalc does not resolve “dependencies of dependencies” when using `file:` refs; nested `.yalc` paths can break. Node-link-local uses a single packed tarball, so the app’s package manager does normal dependency resolution for the installed package.
+
+Trade-off: with node-link-local you run `node-link-local add` again after changing the library (no live “push” like yalc). In return you get a normal install, no symlink-related test or tooling surprises, and behavior that matches a real publish.
+
+## Install
+
+```bash
+npm install -g node-link-local
+```
+
+Or run without installing:
+
+```bash
+npx node-link-local add /path/to/lib
+```
+
+## Commands
+
+| Command | Description |
+|--------|-------------|
+| `node-link-local add <path-to-lib>` | Add the local package at `<path-to-lib>` into the current directory (build, pack, install from staged tarball). |
+| `node-link-local remove` | Remove all packages linked via node-link-local and delete `.local-packages/` if empty. |
+| `node-link-local remove <name-or-path>` | Remove one package (by package name or path). If it was the last one, removes `.local-packages/`. |
+
+## Examples
+
+```bash
+# From your app directory
+node-link-local add ../packages/my-lib
+
+# Remove all linked packages and clean bindings
+node-link-local remove
+
+# Remove one package by name
+node-link-local remove my-lib
+
+# Remove one package by path (same as used in add)
+node-link-local remove ../packages/my-lib
+```
+
+Paths are relative to the current directory. Both the library and app must contain a `package.json`. The app’s lockfile is used to detect pnpm/yarn/npm.
+
+## How it works
+
+1. **add &lt;path-to-lib&gt;**  
+   Detects package manager in lib and app (cwd). If the lib has no `dist/`, runs `build`. Copies the lib into a temp dir, normalizes `package.json` (e.g. `workspace:*` → `*`, strips prepare/prepack/postpack), runs `pack`, copies the `.tgz` into the app’s `.local-packages/`, and installs from that tarball.
+
+2. **remove** (no args)  
+   Finds all dependencies in the app’s `package.json` that reference `file:.local-packages/`, uninstalls each via the app’s package manager, deletes the staged tarballs, and removes `.local-packages/` if empty.
+
+3. **remove &lt;name-or-path&gt;**  
+   Uninstalls that one package and deletes its tarball. If no `file:.local-packages/` dependencies remain, removes the `.local-packages/` directory.
+
+## Requirements
+
+- Node.js ≥ 18
+- Library and app each have a `package.json`; library has a `name` (and ideally a build that produces `dist/` if you rely on it).
+
+## Platform
+
+Works on **Windows, macOS, and Linux**. Uses only Node built-ins (`path`, `fs`, `os`, `child_process`) and the system `PATH` to run pnpm/yarn/npm, so no shell-specific or platform-specific code.
+
+## License
+
+MIT

package/bin/node-link-local.js

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+/** node-link-local — sync a local package into current app via staged tarballs. */
+import { add, remove } from '../lib/sync.js';
+
+const [cmd, arg1] = process.argv.slice(2);
+const usage = () => {
+  console.error('Usage: node-link-local add <path-to-lib>');
+  console.error('       node-link-local remove              # remove all linked packages');
+  console.error('       node-link-local remove <name|path>  # remove one package');
+};
+
+if (!cmd || (cmd !== 'add' && cmd !== 'remove')) {
+  console.error('❌ Command must be "add" or "remove".');
+  usage();
+  process.exit(1);
+}
+
+if (cmd === 'add') {
+  if (!arg1) {
+    console.error('❌ add requires <path-to-lib>.');
+    usage();
+    process.exit(1);
+  }
+}
+
+try {
+  if (cmd === 'add') {
+    add({ libPath: arg1 });
+  } else {
+    remove({ packageNameOrPath: arg1 });
+  }
+} catch (err) {
+  console.error('❌', err instanceof Error ? err.message : String(err));
+  process.exit(1);
+}

package/lib/detect-pm.js

@@ -0,0 +1,9 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+/** Detect package manager from lockfile. Returns 'pnpm' | 'yarn' | 'npm'. */
+export function detectPackageManager(dir) {
+  if (fs.existsSync(path.join(dir, 'pnpm-lock.yaml'))) return 'pnpm';
+  if (fs.existsSync(path.join(dir, 'yarn.lock'))) return 'yarn';
+  return 'npm';
+}

package/lib/sync.js

@@ -0,0 +1,229 @@
+/**
+ * Local package sync via staged tarballs. Cross-platform: uses only Node path/fs/os
+ * and spawns package-manager binaries (pnpm/yarn/npm) via PATH.
+ */
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import { spawnSync } from 'child_process';
+import { detectPackageManager } from './detect-pm.js';
+
+const CACHE_DIR = '.local-packages';
+
+function resolvePath(p) {
+  const resolved = path.resolve(p);
+  try {
+    return fs.realpathSync(resolved);
+  } catch {
+    return resolved;
+  }
+}
+
+function readPackageInfo(dir) {
+  const pkgPath = path.join(dir, 'package.json');
+  if (!fs.existsSync(pkgPath)) throw new Error(`No package.json in: ${dir}`);
+  const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+  return { name: pkg.name, version: pkg.version || '0.0.0' };
+}
+
+/** Run cmd with args in cwd. Uses shell so Windows finds pnpm.cmd / yarn.cmd / npm.cmd. */
+function run(cwd, cmd, args, opts = {}) {
+  const env = { ...process.env, COREPACK_ENABLE_STRICT: '0' };
+  const result = spawnSync(cmd, args, {
+    cwd,
+    env,
+    stdio: opts.quiet ? 'pipe' : 'inherit',
+    shell: true,
+    windowsHide: true,
+  });
+  if (result.status !== 0) {
+    throw new Error(`Command failed: ${cmd} ${args.join(' ')} (exit ${result.status})`);
+  }
+}
+
+/** Tarball basename for scoped packages: @scope/pkg -> scope-pkg-1.0.0.tgz */
+function tarballBasename(pkgName) {
+  return pkgName.startsWith('@') ? pkgName.slice(1).replace('/', '-') : pkgName;
+}
+
+function normalizePackageJson(dir) {
+  const pkgPath = path.join(dir, 'package.json');
+  const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+
+  const fixWorkspace = (deps) => {
+    if (!deps) return;
+    for (const k of Object.keys(deps)) {
+      if (deps[k] === 'workspace:*') deps[k] = '*';
+    }
+  };
+  fixWorkspace(pkg.dependencies);
+  fixWorkspace(pkg.devDependencies);
+  fixWorkspace(pkg.peerDependencies);
+
+  pkg.scripts = pkg.scripts || {};
+  delete pkg.scripts.prepare;
+  delete pkg.scripts.prepack;
+  delete pkg.scripts.postpack;
+
+  if (Array.isArray(pkg.files) && !pkg.files.includes('dist')) pkg.files.push('dist');
+  fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2));
+}
+
+function findLatestTarball(dir) {
+  const files = fs.readdirSync(dir).filter((f) => f.endsWith('.tgz'));
+  if (files.length === 0) return null;
+  const withTime = files.map((f) => ({ name: f, mtime: fs.statSync(path.join(dir, f)).mtimeMs }));
+  withTime.sort((a, b) => b.mtime - a.mtime);
+  return withTime[0].name;
+}
+
+function deleteStagedTarballs(cacheDir, pkgName) {
+  if (!fs.existsSync(cacheDir)) return;
+  const prefix = tarballBasename(pkgName) + '-';
+  for (const f of fs.readdirSync(cacheDir)) {
+    if (f.startsWith(prefix) && f.endsWith('.tgz')) {
+      fs.unlinkSync(path.join(cacheDir, f));
+    }
+  }
+}
+
+/** Package names in app that are linked via file:.local-packages/ */
+function getLocalPackageNames(appDir) {
+  const pkgPath = path.join(appDir, 'package.json');
+  if (!fs.existsSync(pkgPath)) return [];
+  const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+  const ref = 'file:.local-packages/';
+  const names = [];
+  for (const deps of [pkg.dependencies, pkg.devDependencies]) {
+    if (!deps) continue;
+    for (const [name, value] of Object.entries(deps)) {
+      if (typeof value === 'string' && value.startsWith(ref)) names.push(name);
+    }
+  }
+  return [...new Set(names)];
+}
+
+/** True if arg looks like a path (not a bare package name). */
+function isPathArg(arg) {
+  return arg.includes(path.sep) || arg.startsWith('.') || /^[A-Za-z]:/.test(arg);
+}
+
+/** Resolve package name: if path, read from lib package.json; else return as name. */
+function resolvePackageName(appDir, nameOrPath) {
+  if (!isPathArg(nameOrPath)) return nameOrPath;
+  const libDir = resolvePath(path.resolve(appDir, nameOrPath));
+  return readPackageInfo(libDir).name;
+}
+
+function removeOnePackage(appDir, pkgName, log) {
+  const pm = detectPackageManager(appDir);
+  log(`🧹 Removing ${pkgName}...`);
+  run(appDir, pm, pm === 'npm' ? ['uninstall', pkgName] : ['remove', pkgName]);
+  deleteStagedTarballs(path.join(appDir, CACHE_DIR), pkgName);
+  log(`✅ Removed ${pkgName}`);
+}
+
+/** Remove .local-packages dir if empty (clean bindings). */
+function cleanBindingsDir(appDir) {
+  const cacheDir = path.join(appDir, CACHE_DIR);
+  if (!fs.existsSync(cacheDir)) return;
+  const files = fs.readdirSync(cacheDir);
+  if (files.length === 0) {
+    fs.rmSync(cacheDir, { recursive: true });
+  }
+}
+
+export function remove(opts, log = console.log) {
+  const appDir = resolvePath(opts.appPath || process.cwd());
+  if (!fs.existsSync(path.join(appDir, 'package.json'))) {
+    throw new Error(`No package.json in destination: ${appDir}`);
+  }
+
+  const nameOrPath = opts.packageNameOrPath;
+
+  if (nameOrPath === undefined || nameOrPath === '') {
+    const names = getLocalPackageNames(appDir);
+    if (names.length === 0) {
+      log('No node-link-local packages in this app.');
+      cleanBindingsDir(appDir);
+      return;
+    }
+    for (const pkgName of names) {
+      removeOnePackage(appDir, pkgName, log);
+    }
+    cleanBindingsDir(appDir);
+    return;
+  }
+
+  const pkgName = resolvePackageName(appDir, nameOrPath);
+  removeOnePackage(appDir, pkgName, log);
+  if (getLocalPackageNames(appDir).length === 0) {
+    cleanBindingsDir(appDir);
+  }
+}
+
+export function add(opts, log = console.log) {
+  const sourceDir = resolvePath(opts.libPath);
+  const destDir = resolvePath(opts.appPath || process.cwd());
+  if (!fs.existsSync(path.join(sourceDir, 'package.json'))) {
+    throw new Error(`No package.json in source: ${sourceDir}`);
+  }
+  if (!fs.existsSync(path.join(destDir, 'package.json'))) {
+    throw new Error(`No package.json in destination: ${destDir}`);
+  }
+
+  const { name: pkgName, version } = readPackageInfo(sourceDir);
+  const srcPm = detectPackageManager(sourceDir);
+  const destPm = detectPackageManager(destDir);
+  log(`📦 ${pkgName}@${version}  (source: ${srcPm}, app: ${destPm})`);
+
+  const distPath = path.join(sourceDir, 'dist');
+  if (!fs.existsSync(distPath)) {
+    log('🛠️  Building (no dist/)...');
+    run(sourceDir, srcPm, ['run', 'build']);
+  } else {
+    log('✨ dist/ present');
+  }
+
+  // mkdtempSync: use path.join so prefix is correct on Windows (path separators)
+  const tempPrefix = path.join(os.tmpdir(), 'node-link-local-');
+  const tempDir = fs.mkdtempSync(tempPrefix);
+  try {
+    log('📂 Snapshot + pack...');
+    fs.cpSync(sourceDir, tempDir, { recursive: true });
+    normalizePackageJson(tempDir);
+    run(tempDir, srcPm, ['pack'], { quiet: true });
+
+    const tarball = findLatestTarball(tempDir);
+    if (!tarball) throw new Error('Pack produced no tarball');
+
+    const cacheDir = path.join(destDir, CACHE_DIR);
+    fs.mkdirSync(cacheDir, { recursive: true });
+    fs.copyFileSync(path.join(tempDir, tarball), path.join(cacheDir, tarball));
+
+    const fileRef = `file:.local-packages/${tarball}`;
+    log(`🚀 Installing from staged tarball...`);
+
+    if (destPm === 'yarn') {
+      const pkgPath = path.join(destDir, 'package.json');
+      const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+      pkg.dependencies = pkg.dependencies || {};
+      pkg.dependencies[pkgName] = fileRef;
+      fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2));
+      run(destDir, 'yarn', ['install', '--mode=skip-build']);
+    } else if (destPm === 'pnpm') {
+      run(destDir, 'pnpm', [
+        'add',
+        `${pkgName}@${fileRef}`,
+        '--workspace=false',
+        '--no-link-workspace-packages',
+        '--resolve-workspace-protocol=false',
+      ]);
+    } else {
+      run(destDir, 'npm', ['install', fileRef]);
+    }
+    log(`✅ Installed ${pkgName}`);
+  } finally {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  }
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "node-link-local",
+  "version": "1.0.0-alpha.2",
+  "description": "Sync a local npm package into another project via staged tarballs (pnpm/yarn/npm agnostic). No symlinks.",
+  "type": "module",
+  "bin": {
+    "node-link-local": "./bin/node-link-local.js"
+  },
+  "files": [
+    "bin",
+    "lib"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/andrewmkhoury/node-link-local.git"
+  },
+  "homepage": "https://github.com/andrewmkhoury/node-link-local#readme",
+  "scripts": {
+    "start": "node bin/node-link-local.js",
+    "test": "node test/run.js"
+  },
+  "keywords": [
+    "local",
+    "link",
+    "npm",
+    "pnpm",
+    "yarn",
+    "workspace",
+    "tarball",
+    "monorepo"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  }
+}