@ngocsangairvds/vsaf 5.5.2 → 5.6.0

package/README.md

@@ -62,6 +62,7 @@ Every release is verified by the [Install Matrix CI](.github/workflows/install-m
 | Requirement | Version | Check |
 |---|---|---|
 | Node.js | >= 20.0.0 | `node -v` |
+| Bun | >= 1.3.0 | `bun --version` |
 | npm | >= 9.0.0 | `npm -v` |
 | Python | >= 3.10 | `python --version` |
 | git | any | `git --version` |
@@ -70,6 +71,8 @@ Every release is verified by the [Install Matrix CI](.github/workflows/install-m
 
 **Claude Code CLI** is required for prompt and command nodes. **GitHub CLI** is required only for workflows that interact with GitHub (e.g., `fix-issue` uses `gh issue view`); on Windows install it with `winget install GitHub.cli` or the MSI from [github.com/cli/cli/releases](https://github.com/cli/cli/releases). **Python ≥ 3.10** is required by `vsaf install sdlc` (pipx installs graphify + markitdown). On Windows the Visual C++ Redistributable is auto-installed by `vsaf install sdlc` when missing; run `vsaf doctor` any time to see which prerequisites are present.
 
+> **Bun is required to run `vsaf`** (the CLI executes under Bun). `npm install -g @ngocsangairvds/vsaf` auto-installs Bun via the official [bun.sh](https://bun.sh) installer when it is missing — the install is announced, best-effort (never fails your `npm install`), and skipped in CI. Opt out with `VSAF_SKIP_BUN_INSTALL=1` and install Bun yourself. After an auto-install, open a **new terminal** so `~/.bun/bin` is on your `PATH`.
+
 ### Option 1: Global Install (Recommended)
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngocsangairvds/vsaf",
-  "version": "5.5.2",
+  "version": "5.6.0",
   "description": "logging step",
   "main": "packages/core/dist/index.js",
   "types": "packages/core/dist/index.d.ts",

package/scripts/bun-bootstrap.js

@@ -0,0 +1,127 @@
+'use strict';
+
+// Bun bootstrap decision logic (pure) + orchestrator.
+// Runs under plain `node` during `npm install` (postinstall) → CommonJS on purpose.
+
+const os = require('os');
+const path = require('path');
+
+const BUN_INSTALL_SH = 'https://bun.sh/install';
+const BUN_INSTALL_PS1 = 'https://bun.sh/install.ps1';
+
+/** Default location the bun.sh installer drops the binary. */
+function wellKnownBunPath(platform, env) {
+  if (platform === 'win32') {
+    const home = env.USERPROFILE || env.HOME || os.homedir();
+    return path.join(home, '.bun', 'bin', 'bun.exe');
+  }
+  const home = env.HOME || os.homedir();
+  return path.join(home, '.bun', 'bin', 'bun');
+}
+
+/**
+ * Is Bun already available? Checks PATH first, then the well-known install dir,
+ * so a prior install whose PATH has not been reloaded this session is still detected.
+ */
+function detectBun({ platform, env, exists, probe }) {
+  if (probe('bun')) return { present: true, onPath: true };
+  const p = wellKnownBunPath(platform, env);
+  if (exists(p)) return { present: true, onPath: false, path: p };
+  return { present: false, onPath: false };
+}
+
+function manualInstructions(platform) {
+  if (platform === 'win32') {
+    return 'VSAF needs Bun. Install it, then open a new terminal:\n'
+      + '  powershell -c "irm https://bun.sh/install.ps1 | iex"';
+  }
+  return 'VSAF needs Bun. Install it, then open a new terminal:\n'
+    + '  curl -fsSL https://bun.sh/install | bash\n'
+    + '  (or: wget -qO- https://bun.sh/install | bash)';
+}
+
+/** Decide what to do about Bun. Pure. */
+function bunInstallPlan({ platform, hasBun, isCI, optOut, hasCurl, hasWget }) {
+  if (hasBun) return { action: 'skip', reason: 'bun already installed' };
+  if (optOut) return { action: 'skip', reason: 'VSAF_SKIP_BUN_INSTALL=1' };
+  if (isCI) return { action: 'skip', reason: 'CI environment' };
+
+  if (platform === 'win32') {
+    return { action: 'install', shell: 'powershell', command: `powershell -c "irm ${BUN_INSTALL_PS1} | iex"` };
+  }
+  if (hasCurl) {
+    return { action: 'install', shell: 'bash', command: `curl -fsSL ${BUN_INSTALL_SH} | bash` };
+  }
+  if (hasWget) {
+    return { action: 'install', shell: 'bash', command: `wget -qO- ${BUN_INSTALL_SH} | bash` };
+  }
+  return { action: 'manual', instructions: manualInstructions(platform) };
+}
+
+/** Reminder that the current shell session has not picked up ~/.bun/bin yet. */
+function postInstallPathNote(platform, env) {
+  if (platform === 'win32') {
+    return '✓ Bun installed. Open a NEW terminal before using `vsaf`.';
+  }
+  const rc = String(env.SHELL || '').includes('zsh') ? '~/.zshrc' : '~/.bashrc';
+  return '✓ Bun installed to ~/.bun/bin\n'
+    + `  ⚠ Open a NEW terminal (or run: source ${rc}) before using \`vsaf\`.`;
+}
+
+/**
+ * Device that reaches the user's controlling terminal directly. npm suppresses
+ * postinstall stdout/stderr by default (even with a TTY), so writing to the
+ * terminal device is the only way the user reliably sees these messages.
+ */
+function userTtyDevice(platform) {
+  return platform === 'win32' ? '\\\\.\\CONOUT$' : '/dev/tty';
+}
+
+/**
+ * Build a notifier that writes to the controlling TTY (bypassing npm's output
+ * capture), falling back to stderr when there is no TTY (CI / piped output).
+ */
+function makeUserNotifier({ platform, openSync, writeSync, closeSync, stderrWrite }) {
+  return function notify(msg) {
+    try {
+      const fd = openSync(userTtyDevice(platform), 'w');
+      try { writeSync(fd, msg + '\n'); } finally { closeSync(fd); }
+      return;
+    } catch { /* no controlling TTY (CI / piped) */ }
+    try { stderrWrite(msg + '\n'); } catch { /* nothing else we can do */ }
+  };
+}
+
+/** Orchestrator: probe real state via injected deps, then act. Never throws. */
+function maybeInstallBun({ platform, env, exists, probe, exec, log }) {
+  const optOut = env.VSAF_SKIP_BUN_INSTALL === '1';
+  const isCI = !!env.CI;
+  const { present: hasBun } = detectBun({ platform, env, exists, probe });
+  const hasCurl = platform !== 'win32' && probe('curl');
+  const hasWget = platform !== 'win32' && probe('wget');
+  const plan = bunInstallPlan({ platform, hasBun, isCI, optOut, hasCurl, hasWget });
+
+  if (plan.action === 'skip') return plan;
+  if (plan.action === 'manual') { log(plan.instructions); return plan; }
+
+  log('[vsaf] Bun not found — installing via the official bun.sh installer…');
+  try {
+    exec(plan.command);
+    log(postInstallPathNote(platform, env));
+  } catch (e) {
+    log('[vsaf] Bun auto-install failed — install it manually:\n' + manualInstructions(platform));
+    log('[vsaf] (reason: ' + (e && e.message ? e.message : String(e)) + ')');
+  }
+  return plan;
+}
+
+module.exports = {
+  wellKnownBunPath,
+  detectBun,
+  bunInstallPlan,
+  manualInstructions,
+  postInstallPathNote,
+  userTtyDevice,
+  makeUserNotifier,
+  maybeInstallBun,
+};

package/scripts/postinstall.js

@@ -1,21 +1,52 @@
 #!/usr/bin/env node
 
 /**
- * Postinstall script — create @vsaf/core workspace link
+ * Postinstall script — bootstrap Bun (if missing) + create @vsaf/core workspace link
  *
- * Monorepo workspace links are stripped during `npm pack` (prepack removes
- * "workspaces" from package.json). This script recreates the link so that
- * `require('@vsaf/core')` works after `npm install -g`.
+ * 1. Bun bootstrap: every `vsaf` command runs under bun (bin shebang + bun:sqlite),
+ *    so bun must exist before vsaf can run. This postinstall runs under `node`
+ *    during `npm install` — the only place that can install bun automatically.
+ *    Best-effort and never fatal (see scripts/bun-bootstrap.js).
  *
- * Strategy (in order):
- *   1. symlink (macOS/Linux) or junction (Windows — no admin needed)
- *   2. cpSync fallback (copy dist/ contents)
- *   3. Fail with clear instructions
+ * 2. Workspace link: monorepo workspace links are stripped during `npm pack`
+ *    (prepack removes "workspaces" from package.json). This recreates the link so
+ *    `require('@vsaf/core')` works after `npm install -g`.
+ *    Strategy (in order):
+ *      a. symlink (macOS/Linux) or junction (Windows — no admin needed)
+ *      b. cpSync fallback (copy dist/ contents)
+ *      c. Fail with clear instructions
  */
 
 const fs = require('fs');
 const path = require('path');
+const { execSync } = require('child_process');
+const { maybeInstallBun, makeUserNotifier } = require('./bun-bootstrap.js');
 
+// --- Step 1: bootstrap Bun before anything else. Must never break `npm install`.
+function probeCmd(name) {
+  try { execSync(`${name} --version`, { stdio: 'ignore' }); return true; }
+  catch { return false; }
+}
+try {
+  maybeInstallBun({
+    platform: process.platform,
+    env: process.env,
+    exists: fs.existsSync,
+    probe: probeCmd,
+    exec: (command) => execSync(command, { stdio: 'inherit', timeout: 300000 }),
+    // npm hides postinstall output by default → write to the controlling TTY so
+    // the user actually sees the announce + "open a new terminal" note.
+    log: makeUserNotifier({
+      platform: process.platform,
+      openSync: fs.openSync,
+      writeSync: fs.writeSync,
+      closeSync: fs.closeSync,
+      stderrWrite: (s) => process.stderr.write(s),
+    }),
+  });
+} catch { /* bootstrap must never break `npm install` */ }
+
+// --- Step 2: link @vsaf/core (existing behavior).
 const cwd = process.cwd();
 const nsDir = path.resolve(cwd, 'node_modules', '@vsaf');
 const target = path.resolve(nsDir, 'core');