@ngocsangairvds/vsaf 5.5.1 → 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.1",
+  "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');

package/skills/sdlc/onboard-code/SKILL.md

@@ -142,7 +142,10 @@ Icon: `⏳` running, `✅` done, `❌` error.
     - Code module (from GitNexus) → is there a corresponding business concept? (check graph.json)
       - YES → record mapping
       - NO → technical module (infra, utils) — OK, record note
-17. Update `CONTEXT.md` with technical terms from code:
+17. Update `CONTEXT.md` with technical terms from code — IDEMPOTENTLY (never overwrite the whole file, never
+    blind-append; re-runs must not bloat it): PRESERVE the `## Shared Language` section written by onboard-docs;
+    own `## Cross-Domain Verification` + `## Technical Terms` — if a section exists REPLACE its body in place,
+    else append it; one row per mapping/term (dedupe, update rather than duplicate):
 
 ```markdown
 ## Technical Terms

package/skills/sdlc/onboard-docs/SKILL.md

@@ -155,7 +155,10 @@ Print conversion summary:
 [ONBOARD-DOCS] [4/4] Extract domain terms → CONTEXT.md... ⏳
 ```
 
-15. From the completed graph, extract domain terms → `CONTEXT.md`
+15. From the completed graph, extract domain terms → `CONTEXT.md` — update IDEMPOTENTLY (never overwrite the
+    whole file, never blind-append; re-runs must not bloat it): ensure one top `# Project Context: {name}`
+    heading, then own the `## Shared Language` section — if it exists REPLACE its body in place, else append it;
+    leave other sections (`## Technical Terms`, `## Cross-Domain Verification`) untouched; one row per Term (dedupe).
 16. Format Shared Language table:
 
 ```markdown

package/workflows/sdlc/onboard-code.yaml

@@ -87,7 +87,11 @@ nodes:
       Read `graphify-out/graph.json` (the docs graph from onboard-docs — READ ONLY) and query the code via GitNexus (`query`, `context`). Cross-reference:
       - business concept (graph.json) → is there a matching code module? YES → record `{concept} ↔ {module/class}`; NO → "{concept} not yet implemented".
       - code module (GitNexus) → matching business concept? YES → mapping; NO → technical module (infra/utils), record as such.
-      Append a "## Technical Terms" table to `CONTEXT.md` (| Term | Definition | Maps to Business Concept |).
+      Update `CONTEXT.md` IDEMPOTENTLY — never overwrite the whole file, and never blind-append (re-runs would bloat it). Manage BY SECTION:
+      - PRESERVE the `## Shared Language` section written by onboard-docs — do NOT delete or rewrite it.
+      - You OWN `## Cross-Domain Verification` (the concept↔module mappings above) and `## Technical Terms`
+        (table: | Term | Definition | Maps to Business Concept |). If a section already exists, REPLACE its body in place; otherwise append it.
+      - Keep ONE row per mapping/term (dedupe by key) — update rather than duplicate.
       Flag any cross-database access. If `graphify-out/graph.json` is absent, note that onboard-docs must run first.
 
   - id: summary

package/workflows/sdlc/onboard-docs.yaml

@@ -83,7 +83,16 @@ nodes:
       Print progress `[ONBOARD-DOCS] [4/4] Extract domain terms → CONTEXT.md... ⏳/✅`.
 
       From the completed `graph.json`, extract DOMAIN terms (business vocabulary, not technical/code terms —
-      those are added later by onboard-code). Append/update a "## Shared Language" table in `CONTEXT.md` at the project root:
+      those are added later by onboard-code).
+
+      Update `CONTEXT.md` at the project root IDEMPOTENTLY — never overwrite the whole file, and never blind-append
+      (re-running onboarding would bloat it). Manage the file BY SECTION:
+      - Ensure a single top `# Project Context: {project-name}` heading (create once if missing).
+      - You OWN the `## Shared Language` section: if it already exists, REPLACE its body in place; otherwise append it.
+        Leave every other section (e.g. `## Technical Terms`, `## Cross-Domain Verification`) untouched.
+      - Keep ONE row per Term (dedupe by term name) — update an existing term's row instead of adding a duplicate.
+
+      ## Shared Language
 
       | Term | Definition | Example |
       |------|-----------|---------|