bun-ready 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,16 @@
+bun-ready
+Copyright (c) Pas7 Studio
+
+This product includes software developed by Pas7 Studio (https://pas7.com.ua/).
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,61 @@
+# bun-ready
+
+[![Ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/pas7studio)  
+PayPal: https://www.paypal.com/ncp/payment/KDSSNKK8REDM8
+
+CLI that estimates whether a repository will "survive" migrating to **Bun** — quickly.  
+It inspects `package.json`, lockfiles, scripts, and can run `bun install --dry-run` in a temp directory. It then generates a **green / yellow / red** Markdown report with reasons.
+
+## Why
+Bun moves fast. People need a fast risk signal before they try to migrate a repo.
+
+## Install
+### Run without installing (recommended)
+```bash
+bunx bun-ready scan .
+```
+
+### Install globally
+```bash
+bun install -g bun-ready
+bun-ready scan .
+```
+
+## Usage
+```bash
+bun-ready scan <path> [--format md|json] [--out <file>] [--no-install] [--no-test] [--verbose]
+```
+
+## Examples:
+```bash
+bun-ready scan .
+bun-ready scan . --out bun-ready.md
+bun-ready scan ./packages/api --format json
+bun-ready scan . --no-install --no-test
+```
+
+## Exit codes
+- 0 → GREEN
+- 2 → YELLOW
+- 3 → RED
+
+## What it checks (MVP)
+- package.json presence & shape
+- lockfiles (npm/yarn/pnpm/bun)
+- scripts (postinstall/prepare, npm-specific patterns)
+- heuristics for native addons / node-gyp risk
+- optional: bun install --dry-run in a temp dir
+- optional: bun test if tests appear Bun-compatible
+
+## Contributing
+See CONTRIBUTING.md. For security issues, see SECURITY.md.
+
+## Support
+If this tool saves you time, consider supporting:
+- Ko-fi: https://ko-fi.com/pas7studio
+- PayPal: https://www.paypal.com/ncp/payment/KDSSNKK8REDM8
+
+## Attribution
+Created and maintained by Pas7 Studio
+Website: https://pas7.com.ua/
+LinkedIn: https://www.linkedin.com/company/pas7-studio

package/TRADEMARKS.md

@@ -0,0 +1,5 @@
+# Trademarks
+
+"Pas7 Studio" and related marks are trademarks of Pas7 Studio.
+
+This project is an open-source tool and is not affiliated with, endorsed by, or sponsored by Bun or Oven (Bun's creators). All third-party trademarks are the property of their respective owners.

package/dist/cli.js

@@ -0,0 +1,513 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { promises as fs3 } from "node:fs";
+import path3 from "node:path";
+
+// src/analyze.ts
+import path2 from "node:path";
+import os from "node:os";
+import { promises as fs2 } from "node:fs";
+
+// src/spawn.ts
+import { spawn } from "node:child_process";
+var runNodeSpawn = async (cmd, args, cwd) => {
+  return await new Promise((resolve) => {
+    const child = spawn(cmd, args, { cwd, stdio: ["ignore", "pipe", "pipe"] });
+    let out = "";
+    let err = "";
+    child.stdout.on("data", (d) => out += String(d));
+    child.stderr.on("data", (d) => err += String(d));
+    child.on("close", (code) => resolve({ code: code ?? 1, stdout: out, stderr: err }));
+  });
+};
+var runBunSpawn = async (cmd, args, cwd) => {
+  const BunAny = globalThis;
+  const bun = BunAny.Bun;
+  if (!bun)
+    return await runNodeSpawn(cmd, args, cwd);
+  const proc = bun.spawn([cmd, ...args], { cwd, stdout: "pipe", stderr: "pipe" });
+  const readAll = async (s) => {
+    const r = s.getReader();
+    const chunks = [];
+    while (true) {
+      const { done, value } = await r.read();
+      if (done)
+        break;
+      if (value)
+        chunks.push(value);
+    }
+    const total = chunks.reduce((n, c) => n + c.length, 0);
+    const buf = new Uint8Array(total);
+    let off = 0;
+    for (const c of chunks) {
+      buf.set(c, off);
+      off += c.length;
+    }
+    return new TextDecoder().decode(buf);
+  };
+  const [stdout, stderr, code] = await Promise.all([readAll(proc.stdout), readAll(proc.stderr), proc.exited]);
+  return { code, stdout, stderr };
+};
+var exec = async (cmd, args, cwd) => {
+  return await runBunSpawn(cmd, args, cwd);
+};
+
+// src/util.ts
+import { promises as fs } from "node:fs";
+import path from "node:path";
+var stableSort = (arr, key) => {
+  return [...arr].sort((a, b) => key(a).localeCompare(key(b), "en"));
+};
+var readJsonFile = async (p) => {
+  const raw = await fs.readFile(p, "utf8");
+  return JSON.parse(raw);
+};
+var fileExists = async (p) => {
+  try {
+    await fs.access(p);
+    return true;
+  } catch {
+    return false;
+  }
+};
+var normalizeRepoPath = (p) => {
+  return path.resolve(process.cwd(), p);
+};
+var truncateLines = (lines, max) => {
+  if (lines.length <= max)
+    return lines;
+  return [...lines.slice(0, max), `… (${lines.length - max} more lines)`];
+};
+
+// src/heuristics.ts
+var NATIVE_SUSPECTS = [
+  "node-gyp",
+  "node-pre-gyp",
+  "prebuild-install",
+  "bindings",
+  "nan",
+  "node-addon-api",
+  "node-sass",
+  "sharp",
+  "canvas",
+  "better-sqlite3",
+  "sqlite3",
+  "bcrypt",
+  "argon2",
+  "bufferutil",
+  "utf-8-validate",
+  "fsevents"
+];
+var includesAny = (s, needles) => {
+  const lower = s.toLowerCase();
+  return needles.some((n) => lower.includes(n));
+};
+var maxSeverity = (a, b) => {
+  if (a === "red" || b === "red")
+    return "red";
+  if (a === "yellow" || b === "yellow")
+    return "yellow";
+  return "green";
+};
+var detectScriptRisks = (repo) => {
+  const findings = [];
+  const scriptNames = Object.keys(repo.scripts);
+  const lifecycle = ["preinstall", "install", "postinstall", "preprepare", "prepare", "postprepare"];
+  const hits = stableSort(scriptNames.filter((s) => lifecycle.includes(s)), (x) => x);
+  if (hits.length > 0) {
+    const details = hits.map((k) => `${k}: ${repo.scripts[k] ?? ""}`.trim());
+    findings.push({
+      id: "scripts.lifecycle",
+      title: "Lifecycle scripts in the root project",
+      severity: "yellow",
+      details,
+      hints: [
+        "Bun runs your project lifecycle scripts during install. Verify they don't rely on npm-specific behavior.",
+        "If scripts compile native deps, expect migration friction."
+      ]
+    });
+  }
+  const npmSpecificNeedles = ["npm ", "npx ", "pnpm ", "yarn ", "npm_config_", "corepack", "npm ci"];
+  const npmish = stableSort(scriptNames.filter((k) => includesAny(repo.scripts[k] ?? "", npmSpecificNeedles)), (x) => x);
+  if (npmish.length > 0) {
+    findings.push({
+      id: "scripts.npm_specific",
+      title: "Scripts reference npm/yarn/pnpm-specific commands or env",
+      severity: "yellow",
+      details: npmish.map((k) => `${k}: ${repo.scripts[k] ?? ""}`.trim()),
+      hints: [
+        "Consider rewriting scripts to be runner-agnostic, or provide a Bun path.",
+        "If using npm-only flags/behavior, verify equivalence on Bun."
+      ]
+    });
+  }
+  return findings;
+};
+var detectNativeAddonRisk = (repo) => {
+  const allDeps = {
+    ...repo.dependencies,
+    ...repo.devDependencies,
+    ...repo.optionalDependencies
+  };
+  const names = Object.keys(allDeps);
+  const suspects = stableSort(names.filter((n) => NATIVE_SUSPECTS.includes(n) || includesAny(n, ["napi", "node-gyp", "prebuild", "ffi"])), (x) => x);
+  if (suspects.length === 0)
+    return [];
+  const hardRed = suspects.some((n) => n === "node-gyp" || n === "node-sass");
+  const severity = hardRed ? "red" : "yellow";
+  return [
+    {
+      id: "deps.native_addons",
+      title: "Potential native addons / node-gyp toolchain risk",
+      severity,
+      details: suspects.map((n) => `${n}@${allDeps[n] ?? ""}`.trim()),
+      hints: [
+        "Native addons often require toolchains and can be sensitive to runtime differences.",
+        "If you see install/build failures, try upgrading these packages or switching to pure-JS alternatives."
+      ]
+    }
+  ];
+};
+var detectLockfileSignals = (repo) => {
+  const { bunLock, bunLockb, npmLock, yarnLock, pnpmLock } = repo.lockfiles;
+  if (bunLock || bunLockb)
+    return [];
+  const anyOther = npmLock || yarnLock || pnpmLock;
+  if (!anyOther) {
+    return [
+      {
+        id: "lockfile.missing",
+        title: "No lockfile found",
+        severity: "yellow",
+        details: ["No bun.lock/bun.lockb, package-lock.json, yarn.lock, or pnpm-lock.yaml detected."],
+        hints: [
+          "Lockfiles improve reproducibility. Consider committing one before migration.",
+          "If you migrate to Bun, generate bun.lock and verify installs are stable."
+        ]
+      }
+    ];
+  }
+  const present = [];
+  if (npmLock)
+    present.push("package-lock.json");
+  if (yarnLock)
+    present.push("yarn.lock");
+  if (pnpmLock)
+    present.push("pnpm-lock.yaml");
+  return [
+    {
+      id: "lockfile.migration",
+      title: "Non-Bun lockfile detected (Bun will likely migrate on first install)",
+      severity: "yellow",
+      details: [`Detected: ${present.join(", ")}`],
+      hints: [
+        "Run bun install once on a branch and review the generated bun.lock.",
+        "Compare resolved versions and run your test suite."
+      ]
+    }
+  ];
+};
+var summarizeSeverity = (findings, installOk, testOk) => {
+  let sev = "green";
+  for (const f of findings)
+    sev = maxSeverity(sev, f.severity);
+  if (installOk === false)
+    sev = "red";
+  if (testOk === false)
+    sev = "red";
+  return sev;
+};
+
+// src/analyze.ts
+var readRepoInfo = async (repoPath) => {
+  const packageJsonPath = path2.join(repoPath, "package.json");
+  const pkg = await readJsonFile(packageJsonPath);
+  const scripts = pkg.scripts ?? {};
+  const dependencies = pkg.dependencies ?? {};
+  const devDependencies = pkg.devDependencies ?? {};
+  const optionalDependencies = pkg.optionalDependencies ?? {};
+  const hasWorkspaces = Boolean(pkg.workspaces);
+  const lockfiles = {
+    bunLock: await fileExists(path2.join(repoPath, "bun.lock")),
+    bunLockb: await fileExists(path2.join(repoPath, "bun.lockb")),
+    npmLock: await fileExists(path2.join(repoPath, "package-lock.json")),
+    yarnLock: await fileExists(path2.join(repoPath, "yarn.lock")),
+    pnpmLock: await fileExists(path2.join(repoPath, "pnpm-lock.yaml"))
+  };
+  return { packageJsonPath, lockfiles, scripts, dependencies, devDependencies, optionalDependencies, hasWorkspaces };
+};
+var copyIfExists = async (from, to) => {
+  try {
+    await fs2.copyFile(from, to);
+  } catch {
+    return;
+  }
+};
+var runBunInstallDryRun = async (repoPath) => {
+  const base = await fs2.mkdtemp(path2.join(os.tmpdir(), "bun-ready-"));
+  const cleanup = async () => {
+    try {
+      await fs2.rm(base, { recursive: true, force: true });
+    } catch {
+      return;
+    }
+  };
+  try {
+    await copyIfExists(path2.join(repoPath, "package.json"), path2.join(base, "package.json"));
+    await copyIfExists(path2.join(repoPath, "bun.lock"), path2.join(base, "bun.lock"));
+    await copyIfExists(path2.join(repoPath, "bun.lockb"), path2.join(base, "bun.lockb"));
+    await copyIfExists(path2.join(repoPath, "package-lock.json"), path2.join(base, "package-lock.json"));
+    await copyIfExists(path2.join(repoPath, "yarn.lock"), path2.join(base, "yarn.lock"));
+    await copyIfExists(path2.join(repoPath, "pnpm-lock.yaml"), path2.join(base, "pnpm-lock.yaml"));
+    const res = await exec("bun", ["install", "--dry-run"], base);
+    const combined = [...res.stdout ? res.stdout.split(`
+`) : [], ...res.stderr ? res.stderr.split(`
+`) : []].filter((l) => l.trim().length > 0);
+    const logs = truncateLines(combined, 60);
+    return res.code === 0 ? { ok: true, summary: "bun install --dry-run succeeded", logs } : { ok: false, summary: `bun install --dry-run failed (exit ${res.code})`, logs };
+  } finally {
+    await cleanup();
+  }
+};
+var shouldRunBunTest = (repo) => {
+  const t = repo.scripts["test"];
+  if (!t)
+    return false;
+  return t.toLowerCase().includes("bun test") || t.toLowerCase().trim() === "bun test";
+};
+var runBunTest = async (repoPath) => {
+  const res = await exec("bun", ["test"], repoPath);
+  const combined = [...res.stdout ? res.stdout.split(`
+`) : [], ...res.stderr ? res.stderr.split(`
+`) : []].filter((l) => l.trim().length > 0);
+  const logs = truncateLines(combined, 120);
+  return res.code === 0 ? { ok: true, summary: "bun test succeeded", logs } : { ok: false, summary: `bun test failed (exit ${res.code})`, logs };
+};
+var analyzeRepo = async (opts) => {
+  const repoPath = normalizeRepoPath(opts.repoPath);
+  const packageJsonPath = path2.join(repoPath, "package.json");
+  const hasPkg = await fileExists(packageJsonPath);
+  if (!hasPkg) {
+    return {
+      severity: "red",
+      summaryLines: ["package.json not found"],
+      findings: [
+        {
+          id: "repo.no_package_json",
+          title: "Missing package.json",
+          severity: "red",
+          details: [`Expected at: ${packageJsonPath.replace(/\\/g, "/")}`],
+          hints: ["Run bun-ready in a Node.js project root (where package.json exists)."]
+        }
+      ],
+      install: null,
+      test: null,
+      repo: {
+        packageJsonPath,
+        lockfiles: { bunLock: false, bunLockb: false, npmLock: false, yarnLock: false, pnpmLock: false },
+        scripts: {},
+        dependencies: {},
+        devDependencies: {},
+        optionalDependencies: {},
+        hasWorkspaces: false
+      }
+    };
+  }
+  const repo = await readRepoInfo(repoPath);
+  const findings = [
+    ...detectLockfileSignals(repo),
+    ...detectScriptRisks(repo),
+    ...detectNativeAddonRisk(repo)
+  ];
+  const install = opts.runInstall ? await runBunInstallDryRun(repoPath) : null;
+  const allowTest = opts.runTest && shouldRunBunTest(repo);
+  const test = allowTest ? await runBunTest(repoPath) : null;
+  const installOk = install ? install.ok : null;
+  const testOk = test ? test.ok : null;
+  const severity = summarizeSeverity(findings, installOk, testOk);
+  const summaryLines = [];
+  summaryLines.push(`Lockfiles: ${repo.lockfiles.bunLock || repo.lockfiles.bunLockb ? "bun" : "non-bun or missing"}`);
+  summaryLines.push(`Lifecycle scripts: ${Object.keys(repo.scripts).some((k) => ["postinstall", "prepare", "preinstall", "install"].includes(k)) ? "present" : "none"}`);
+  summaryLines.push(`Native addon risk: ${findings.some((f) => f.id === "deps.native_addons") ? "yes" : "no"}`);
+  summaryLines.push(`bun install dry-run: ${install ? install.ok ? "ok" : "failed" : "skipped"}`);
+  summaryLines.push(`bun test: ${test ? test.ok ? "ok" : "failed" : allowTest ? "running" : "skipped"}`);
+  return { severity, summaryLines, findings, install, test, repo };
+};
+
+// src/report_md.ts
+var badge = (s) => {
+  if (s === "green")
+    return "\uD83D\uDFE2 GREEN";
+  if (s === "yellow")
+    return "\uD83D\uDFE1 YELLOW";
+  return "\uD83D\uDD34 RED";
+};
+var renderMarkdown = (r) => {
+  const lines = [];
+  lines.push(`# bun-ready report`);
+  lines.push(``);
+  lines.push(`**Overall:** ${badge(r.severity)}`);
+  lines.push(``);
+  lines.push(`## Summary`);
+  for (const l of r.summaryLines)
+    lines.push(`- ${l}`);
+  lines.push(``);
+  lines.push(`## Repo`);
+  lines.push(`- Path: \`${r.repo.packageJsonPath.replace(/\\/g, "/")}\``);
+  lines.push(`- Workspaces: ${r.repo.hasWorkspaces ? "yes" : "no"}`);
+  const lock = [];
+  if (r.repo.lockfiles.bunLock)
+    lock.push("bun.lock");
+  if (r.repo.lockfiles.bunLockb)
+    lock.push("bun.lockb");
+  if (r.repo.lockfiles.npmLock)
+    lock.push("package-lock.json");
+  if (r.repo.lockfiles.yarnLock)
+    lock.push("yarn.lock");
+  if (r.repo.lockfiles.pnpmLock)
+    lock.push("pnpm-lock.yaml");
+  lines.push(`- Lockfiles: ${lock.length === 0 ? "none" : lock.join(", ")}`);
+  lines.push(``);
+  if (r.install) {
+    lines.push(`## bun install (dry-run)`);
+    lines.push(`- Result: ${r.install.ok ? "ok" : "failed"}`);
+    lines.push(`- Summary: ${r.install.summary}`);
+    if (r.install.logs.length > 0) {
+      lines.push(``);
+      lines.push("```text");
+      for (const l of r.install.logs)
+        lines.push(l);
+      lines.push("```");
+    }
+    lines.push(``);
+  }
+  if (r.test) {
+    lines.push(`## bun test`);
+    lines.push(`- Result: ${r.test.ok ? "ok" : "failed"}`);
+    lines.push(`- Summary: ${r.test.summary}`);
+    if (r.test.logs.length > 0) {
+      lines.push(``);
+      lines.push("```text");
+      for (const l of r.test.logs)
+        lines.push(l);
+      lines.push("```");
+    }
+    lines.push(``);
+  }
+  lines.push(`## Findings`);
+  if (r.findings.length === 0) {
+    lines.push(`No findings. Looks good.`);
+    lines.push(``);
+    return lines.join(`
+`);
+  }
+  const findings = stableSort(r.findings, (f) => `${f.severity}:${f.id}`);
+  for (const f of findings) {
+    lines.push(`### ${f.title} (${badge(f.severity)})`);
+    lines.push(``);
+    for (const d of f.details)
+      lines.push(`- ${d}`);
+    if (f.hints.length > 0) {
+      lines.push(``);
+      lines.push(`**Hints:**`);
+      for (const h of f.hints)
+        lines.push(`- ${h}`);
+    }
+    lines.push(``);
+  }
+  return lines.join(`
+`);
+};
+
+// src/report_json.ts
+var renderJson = (r) => {
+  return JSON.stringify(r, null, 2);
+};
+
+// src/cli.ts
+var usage = () => {
+  return [
+    "bun-ready",
+    "",
+    "Usage:",
+    "  bun-ready scan <path> [--format md|json] [--out <file>] [--no-install] [--no-test] [--verbose]",
+    "",
+    "Exit codes:",
+    "  0 green, 2 yellow, 3 red"
+  ].join(`
+`);
+};
+var parseArgs = (argv) => {
+  const args = argv.slice(2);
+  const cmd = args[0] ?? "";
+  if (cmd !== "scan") {
+    return {
+      cmd,
+      opts: { repoPath: ".", format: "md", outFile: null, runInstall: true, runTest: true, verbose: false }
+    };
+  }
+  const repoPath = args[1] && !args[1].startsWith("-") ? args[1] : ".";
+  let format = "md";
+  let outFile = null;
+  let runInstall = true;
+  let runTest = true;
+  let verbose = false;
+  for (let i = 2;i < args.length; i++) {
+    const a = args[i] ?? "";
+    if (a === "--format") {
+      const v = args[i + 1] ?? "";
+      if (v === "md" || v === "json")
+        format = v;
+      i++;
+      continue;
+    }
+    if (a === "--out") {
+      outFile = args[i + 1] ?? null;
+      i++;
+      continue;
+    }
+    if (a === "--no-install") {
+      runInstall = false;
+      continue;
+    }
+    if (a === "--no-test") {
+      runTest = false;
+      continue;
+    }
+    if (a === "--verbose") {
+      verbose = true;
+      continue;
+    }
+  }
+  return { cmd, opts: { repoPath, format, outFile, runInstall, runTest, verbose } };
+};
+var exitCode = (sev) => {
+  if (sev === "green")
+    return 0;
+  if (sev === "yellow")
+    return 2;
+  return 3;
+};
+var main = async () => {
+  const { cmd, opts } = parseArgs(process.argv);
+  if (cmd !== "scan") {
+    process.stderr.write(usage() + `
+`);
+    process.exit(1);
+  }
+  const res = await analyzeRepo(opts);
+  const out = opts.format === "json" ? renderJson(res) : renderMarkdown(res);
+  const target = opts.outFile ?? (opts.format === "json" ? "bun-ready.json" : "bun-ready.md");
+  const resolved = path3.resolve(process.cwd(), target);
+  await fs3.writeFile(resolved, out, "utf8");
+  process.stdout.write(`Wrote ${opts.format.toUpperCase()} report to ${resolved}
+`);
+  process.exit(exitCode(res.severity));
+};
+main().catch((e) => {
+  const msg = e instanceof Error ? e.message : String(e);
+  process.stderr.write(`bun-ready failed: ${msg}
+`);
+  process.exit(3);
+});

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "bun-ready",
+  "version": "0.1.0",
+  "description": "CLI that estimates how painful migrating a Node.js repo to Bun might be. Generates a green/yellow/red Markdown report with reasons.",
+  "author": "Pas7 Studio",
+  "license": "Apache-2.0",
+  "homepage": "https://pas7.com.ua/",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/pas7studio/bun-ready"
+  },
+  "bugs": {
+    "url": "https://github.com/pas7studio/bun-ready/issues"
+  },
+  "keywords": [
+    "bun",
+    "migration",
+    "audit",
+    "cli",
+    "nodejs",
+    "package-manager"
+  ],
+  "type": "module",
+  "bin": {
+    "bun-ready": "dist/cli.js"
+  },
+  "files": [
+    "dist/",
+    "README.md",
+    "LICENSE",
+    "NOTICE",
+    "TRADEMARKS.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "bun test",
+    "check": "bunx --yes tsc -p tsconfig.json --noEmit",
+    "build": "bun build ./src/cli.ts --outdir ./dist --target=node",
+    "dev": "bun run ./src/cli.ts scan . --no-install --no-test --format md",
+    "prepack": "bun run build"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.3",
+    "@types/node": "^22.0.0",
+    "bun-types": "^1.2.22"
+  }
+}