@olegkuibar/plunk 0.2.0-canary.04ff96f

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 plunk contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,95 @@
+<p align="center">
+  <img src="plunk_logo.png" width="200" alt="plunk logo" />
+</p>
+
+# plunk
+
+Modern local package development tool. Smart file copying into `node_modules` — no symlinks, no git contamination.
+
+```bash
+npx plunk init       # set up your app
+plunk add my-lib     # link a package
+plunk push --watch   # continuous dev mode
+```
+
+## Why not symlinks?
+
+`npm link` creates symlinks that break module resolution: duplicate React instances, peer dep mismatches, bundlers that can't follow links outside the project root. `yalc` improves on this but [still has issues](https://github.com/wclr/yalc/issues) with pnpm, git contamination, and watch mode.
+
+**plunk** just copies built files directly into `node_modules/`. It works.
+
+## How it works
+
+```mermaid
+graph LR
+    A["my-lib/"] -- "plunk publish" --> B["~/.plunk/store/<br/>my-lib@1.0.0"]
+    B -- "plunk add" --> C["app/node_modules/<br/>my-lib/"]
+    B -- "plunk push" --> D["app-2/node_modules/<br/>my-lib/"]
+
+    style A fill:#2e7d32,stroke:#66bb6a,color:#e8f5e9
+    style B fill:#1565c0,stroke:#64b5f6,color:#e3f2fd
+    style C fill:#e65100,stroke:#ffb74d,color:#fff3e0
+    style D fill:#e65100,stroke:#ffb74d,color:#fff3e0
+```
+
+1. `publish` copies built files to a local store at `~/.plunk/store/`
+2. `add` copies from store into your app's `node_modules/`
+3. `push` = publish + copy to all consumers
+4. `--watch` = file change → build → push loop
+
+> Uses CoW reflinks for instant copy-on-write on APFS/btrfs/ReFS, with automatic fallback. Reflink support is probed once per volume and cached — no wasted syscalls. Only changed files are re-copied (xxhash-based diffing).
+
+## Quick start
+
+```bash
+# In your app — one-time setup
+cd my-app
+npx plunk init
+
+# In your library — build and publish to plunk store
+cd my-lib
+pnpm build
+plunk publish
+
+# Back in your app — link the library
+cd my-app
+plunk add my-lib
+
+# Continuous dev: watch → build → push
+cd my-lib
+plunk push --watch --build "pnpm build"
+```
+
+## At a glance
+
+| | npm link | yalc | plunk |
+|---|---|---|---|
+| Module resolution | Broken (dual instances) | Works | Works |
+| Git contamination | None | package.json + .yalc/ | None |
+| Bundler HMR | Often broken | Fragile | Works |
+| pnpm support | Fragile | Broken since v7.10 | Works |
+| Watch mode | None | External | Built-in |
+| Survives `npm install` | No | No | `plunk restore` |
+
+## Install
+
+```bash
+pnpm add -g plunk       # or npm, yarn, bun
+npx plunk init          # set up a consumer project
+```
+
+## Documentation
+
+| | |
+|---|---|
+| [Getting Started](docs/getting-started.md) | Install, first publish/add cycle, watch mode |
+| [Commands](docs/commands.md) | Every command, every flag |
+| [How It Works](docs/how-it-works.md) | Store format, injection, CoW copies |
+| [Bundler Guide](docs/bundlers.md) | Vite, Webpack, esbuild, Turbopack setup |
+| [Comparison](docs/comparison.md) | npm link vs yalc vs plunk |
+| [Examples](examples/) | Try it yourself with real packages |
+| [Contributing](CONTRIBUTING.md) | Dev setup and guidelines |
+
+## License
+
+[MIT](LICENSE)

package/dist/add-5ZRFUL6Z.mjs

@@ -0,0 +1,258 @@
+#!/usr/bin/env node
+import{createRequire as __cr}from"node:module";globalThis.require=__cr(import.meta.url);
+import {
+  addToTranspilePackages
+} from "./chunk-WSECI6M7.mjs";
+import {
+  backupExisting,
+  checkMissingDeps,
+  inject
+} from "./chunk-CZM4TNAI.mjs";
+import {
+  ensureConsumerInit
+} from "./chunk-ZQCGJUBJ.mjs";
+import {
+  detectBundler,
+  detectPackageManager,
+  detectYarnNodeLinker,
+  hasYarnrcYml
+} from "./chunk-34UXZ622.mjs";
+import {
+  addLink,
+  registerConsumer
+} from "./chunk-GAAB2TLH.mjs";
+import {
+  publish
+} from "./chunk-4O2QOKVO.mjs";
+import {
+  errorWithSuggestion
+} from "./chunk-S4HJSJ32.mjs";
+import {
+  findStoreEntry
+} from "./chunk-W3C72UKC.mjs";
+import {
+  Timer
+} from "./chunk-XZK5T4GK.mjs";
+import "./chunk-PUSXMPOF.mjs";
+import {
+  getConsumerStatePath
+} from "./chunk-EDUXIQ5W.mjs";
+import {
+  output,
+  suppressHumanOutput
+} from "./chunk-ZOYNYK5Y.mjs";
+import {
+  defineCommand
+} from "./chunk-CSMZ6DZA.mjs";
+import {
+  exists
+} from "./chunk-HKNM3UWU.mjs";
+import {
+  consola,
+  isJsonOutput,
+  verbose
+} from "./chunk-I6SN7BBN.mjs";
+import "./chunk-KYDBD2KQ.mjs";
+
+// src/commands/add.ts
+import { spawn } from "child_process";
+import { platform } from "os";
+import { resolve, basename } from "path";
+var add_default = defineCommand({
+  meta: {
+    name: "add",
+    description: "Link a package from the plunk store into this project"
+  },
+  args: {
+    package: {
+      type: "positional",
+      description: "Package name to add",
+      required: true
+    },
+    from: {
+      type: "string",
+      description: "Path to package source (will publish first)"
+    },
+    yes: {
+      type: "boolean",
+      alias: "y",
+      description: "Auto-accept prompts (install missing deps, etc.)",
+      default: false
+    }
+  },
+  async run({ args }) {
+    suppressHumanOutput();
+    const timer = new Timer();
+    const consumerPath = resolve(".");
+    const packageName = args.package;
+    if (args.from) {
+      const fromPath = resolve(args.from);
+      consola.info(`Publishing from ${fromPath}...`);
+      await publish(fromPath);
+    }
+    const entry = await findStoreEntry(packageName);
+    if (!entry) {
+      errorWithSuggestion(
+        `Package "${packageName}" not found in store. Run 'plunk publish' in the package directory first, or use --from <path>.`
+      );
+      process.exit(1);
+    }
+    const needsInit = !await exists(getConsumerStatePath(consumerPath));
+    const pm = await detectPackageManager(consumerPath);
+    if (needsInit) {
+      await ensureConsumerInit(consumerPath, pm);
+      consola.success("Auto-initialized plunk (consumer mode)");
+    }
+    verbose(`[add] Detected package manager: ${pm}`);
+    consola.info(`Detected package manager: ${pm}`);
+    if (pm === "yarn") {
+      const linker = await detectYarnNodeLinker(consumerPath);
+      if (linker === "pnp" || linker === null && await hasYarnrcYml(consumerPath)) {
+        consola.error(
+          `Yarn PnP mode is not compatible with plunk.
+
+plunk works by copying files into node_modules/, but PnP eliminates
+node_modules/ entirely. To use plunk with Yarn Berry, add this to
+.yarnrc.yml:
+
+  nodeLinker: node-modules
+
+Then run: yarn install`
+        );
+        process.exit(1);
+      }
+    }
+    const hasBackup = await backupExisting(consumerPath, packageName, pm);
+    if (hasBackup) {
+      consola.info(`Backed up existing ${packageName} installation`);
+    }
+    const result = await inject(entry, consumerPath, pm);
+    consola.success(
+      `Linked ${packageName}@${entry.version} \u2192 node_modules/${packageName} (${result.copied} files copied, ${result.skipped} unchanged)`
+    );
+    if (result.binLinks > 0) {
+      consola.info(`Created ${result.binLinks} bin link(s)`);
+    }
+    const linkEntry = {
+      version: entry.version,
+      contentHash: entry.meta.contentHash,
+      linkedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      sourcePath: entry.meta.sourcePath,
+      backupExists: hasBackup,
+      packageManager: pm,
+      buildId: entry.meta.buildId ?? ""
+    };
+    await addLink(consumerPath, packageName, linkEntry);
+    await registerConsumer(packageName, consumerPath);
+    const missing = await checkMissingDeps(entry, consumerPath);
+    if (missing.length > 0) {
+      if (isJsonOutput()) {
+        verbose(`[add] Missing transitive deps (json mode): ${missing.join(", ")}`);
+      } else if (args.yes) {
+        const cmd = buildInstallCommand(pm, missing);
+        consola.info(`Installing missing dependencies: ${missing.join(", ")}`);
+        const ok = await runInstallCommand(cmd, consumerPath);
+        if (ok) {
+          consola.success("Installed missing dependencies");
+        } else {
+          consola.warn(`Install failed. Run manually: ${cmd}`);
+        }
+      } else {
+        const confirm = await consola.prompt(
+          `Install ${missing.length} missing dependencies? (${missing.join(", ")})`,
+          { type: "confirm", initial: true }
+        );
+        if (confirm) {
+          const cmd = buildInstallCommand(pm, missing);
+          const ok = await runInstallCommand(cmd, consumerPath);
+          if (ok) {
+            consola.success("Installed missing dependencies");
+          } else {
+            consola.warn(`Install failed. Run manually: ${cmd}`);
+          }
+        } else {
+          consola.warn(
+            `Missing transitive dependencies: ${missing.join(", ")}
+  Run: ${buildInstallCommand(pm, missing)}`
+          );
+        }
+      }
+    }
+    const bundler = await detectBundler(consumerPath);
+    if (bundler.type === "next" && bundler.configFile) {
+      const configResult = await addToTranspilePackages(
+        bundler.configFile,
+        packageName
+      );
+      if (configResult.modified) {
+        consola.success(
+          `Added ${packageName} to transpilePackages in ${basename(bundler.configFile)}`
+        );
+      } else if (configResult.error) {
+        consola.info(
+          `Add to next.config manually: transpilePackages: ['${packageName}']`
+        );
+      }
+    } else if (bundler.type === "vite" && bundler.configFile) {
+      const { addPlunkVitePlugin } = await import("./vite-config-BAK67JHB.mjs");
+      const viteResult = await addPlunkVitePlugin(bundler.configFile);
+      if (viteResult.modified) {
+        consola.success(`Added plunk plugin to ${basename(bundler.configFile)}`);
+      } else if (viteResult.error) {
+        consola.info(
+          `Add manually:
+  import plunk from "@olegkuibar/plunk/vite"
+  plugins: [plunk()]`
+        );
+      }
+    }
+    const { findTailwindCss, addTailwindSource } = await import("./tailwind-source-JBBEIXIJ.mjs");
+    const tailwindCss = await findTailwindCss(consumerPath);
+    if (tailwindCss) {
+      const twResult = await addTailwindSource(tailwindCss, packageName, consumerPath);
+      if (twResult.modified) {
+        consola.success(`Added @source for ${packageName} to ${basename(tailwindCss)}`);
+      } else if (twResult.error) {
+        consola.info(`Add to your CSS manually: @source "../node_modules/${packageName}";`);
+      }
+    }
+    consola.info(`Done in ${timer.elapsed()}`);
+    output({
+      package: packageName,
+      version: entry.version,
+      copied: result.copied,
+      skipped: result.skipped,
+      binLinks: result.binLinks,
+      elapsed: timer.elapsedMs()
+    });
+  }
+});
+function buildInstallCommand(pm, deps) {
+  const joined = deps.join(" ");
+  switch (pm) {
+    case "pnpm":
+      return `pnpm add ${joined}`;
+    case "yarn":
+      return `yarn add ${joined}`;
+    case "bun":
+      return `bun add ${joined}`;
+    default:
+      return `npm install ${joined}`;
+  }
+}
+function runInstallCommand(cmd, cwd) {
+  return new Promise((resolve2) => {
+    const isWin = platform() === "win32";
+    const shell = isWin ? "cmd" : "sh";
+    const shellFlag = isWin ? "/c" : "-c";
+    const child = spawn(shell, [shellFlag, cmd], {
+      cwd,
+      stdio: "inherit"
+    });
+    child.on("close", (code) => resolve2(code === 0));
+    child.on("error", () => resolve2(false));
+  });
+}
+export {
+  add_default as default
+};