@cliangdev/flux-plugin 0.0.0-dev.cbdf207 → 0.0.0-dev.df3e9bb

package/README.md

@@ -2,10 +2,14 @@
 
 Agent-orchestrated, spec-driven workflow for Claude Code.
 
+## Prerequisites
+
+This plugin requires [Bun](https://bun.sh). If you don't have Bun installed, the installer will offer to install it for you.
+
 ## Installation
 
 ```bash
-npx @cliangdev/flux-plugin
+bunx @cliangdev/flux-plugin
 ```
 
 This installs:
@@ -16,8 +20,8 @@ This installs:
 ### Options
 
 ```bash
-npx @cliangdev/flux-plugin --global   # Install to ~/.claude (all projects)
-npx @cliangdev/flux-plugin --local    # Install to ./.claude (current project)
+bunx @cliangdev/flux-plugin --global   # Install to ~/.claude (all projects)
+bunx @cliangdev/flux-plugin --local    # Install to ./.claude (current project)
 ```
 
 ### What Gets Configured
@@ -121,7 +125,7 @@ your-project/
 To update to the latest version, simply re-run the installer:
 
 ```bash
-npx @cliangdev/flux-plugin@latest --global
+bunx @cliangdev/flux-plugin@latest --global
 ```
 
 This will:

package/bin/install.cjs

@@ -4,22 +4,45 @@ const fs = require("fs");
 const path = require("path");
 const os = require("os");
 const readline = require("readline");
+const { execSync, spawn } = require("child_process");
 
 const args = process.argv.slice(2);
 
 if (args[0] === "serve") {
-	import("../dist/server/index.js").catch((err) => {
+	const serverSrc = path.join(__dirname, "..", "src", "server", "index.ts");
+	const bunPath = getBunPath();
+	if (!bunPath) {
+		console.error("Failed to start Flux MCP server: Bun is required but not found");
+		process.exit(1);
+	}
+	const child = spawn(bunPath, ["run", serverSrc], { stdio: "inherit" });
+	child.on("error", (err) => {
 		console.error("Failed to start Flux MCP server:", err.message);
 		process.exit(1);
 	});
+	child.on("close", (code) => process.exit(code || 0));
 } else {
 	runInstaller();
 }
 
+function getBunPath() {
+	const bunDir = path.join(os.homedir(), ".bun", "bin");
+	const bunBinary = process.platform === "win32" ? "bun.exe" : "bun";
+	const localBunPath = path.join(bunDir, bunBinary);
+	if (fs.existsSync(localBunPath)) return localBunPath;
+	try {
+		execSync("bun --version", { stdio: "ignore" });
+		return "bun";
+	} catch {
+		return null;
+	}
+}
+
 function runInstaller() {
 	const cyan = "\x1b[36m";
 	const green = "\x1b[32m";
 	const yellow = "\x1b[33m";
+	const red = "\x1b[31m";
 	const dim = "\x1b[2m";
 	const reset = "\x1b[0m";
 	const pkg = require("../package.json");
@@ -43,7 +66,7 @@ ${cyan}  ███████╗██╗     ██╗   ██╗██╗
 	console.log(banner);
 
 	if (hasHelp) {
-		console.log(`  ${yellow}Usage:${reset} npx @cliangdev/flux-plugin [options]
+		console.log(`  ${yellow}Usage:${reset} bunx @cliangdev/flux-plugin [options]
 
   ${yellow}Options:${reset}
     ${cyan}-g, --global${reset}    Install globally (to ~/.claude)
@@ -52,17 +75,123 @@ ${cyan}  ███████╗██╗     ██╗   ██╗██╗
 
   ${yellow}Examples:${reset}
     ${dim}# Interactive installation${reset}
-    npx @cliangdev/flux-plugin
+    bunx @cliangdev/flux-plugin
 
     ${dim}# Install globally (all projects)${reset}
-    npx @cliangdev/flux-plugin --global
+    bunx @cliangdev/flux-plugin --global
 
     ${dim}# Install locally (current project only)${reset}
-    npx @cliangdev/flux-plugin --local
+    bunx @cliangdev/flux-plugin --local
+
+  ${yellow}Note:${reset} This plugin requires Bun. Install from https://bun.sh
 `);
 		process.exit(0);
 	}
 
+	function isBunInstalled() {
+		const bunDir = path.join(os.homedir(), ".bun", "bin");
+		const envPath = process.env.PATH || "";
+		const pathWithBun = envPath.includes(bunDir)
+			? envPath
+			: `${bunDir}${path.delimiter}${envPath}`;
+
+		try {
+			execSync("bun --version", {
+				stdio: "ignore",
+				env: { ...process.env, PATH: pathWithBun },
+			});
+			return true;
+		} catch {
+			return false;
+		}
+	}
+
+	function installBun() {
+		return new Promise((resolve, reject) => {
+			const platform = os.platform();
+			const installCmd = platform === "win32" ? "powershell" : "/bin/sh";
+			const installArgs = platform === "win32"
+				? ["-c", "irm bun.sh/install.ps1 | iex"]
+				: ["-c", "curl -fsSL https://bun.sh/install | bash"];
+
+			console.log(`\n  ${cyan}Installing Bun...${reset}\n`);
+
+			const child = spawn(installCmd, installArgs, {
+				stdio: "inherit",
+				shell: false,
+			});
+
+			child.on("close", (code) => {
+				if (code === 0) {
+					console.log(`\n  ${green}✓${reset} Bun installed successfully\n`);
+					resolve(true);
+				} else {
+					reject(new Error(`Installation exited with code ${code}`));
+				}
+			});
+
+			child.on("error", (err) => {
+				reject(err);
+			});
+		});
+	}
+
+	function showBunInstallInstructions() {
+		console.log(`
+  ${yellow}Bun is required but not installed.${reset}
+
+  Install Bun manually:
+
+  ${cyan}macOS/Linux:${reset}
+    curl -fsSL https://bun.sh/install | bash
+
+  ${cyan}Windows:${reset}
+    powershell -c "irm bun.sh/install.ps1 | iex"
+
+  Then restart your terminal and run this installer again.
+
+  ${dim}Learn more: https://bun.sh${reset}
+`);
+	}
+
+	async function checkBunAndContinue(callback) {
+		if (isBunInstalled()) {
+			callback();
+			return;
+		}
+
+		const rl = readline.createInterface({
+			input: process.stdin,
+			output: process.stdout,
+		});
+
+		console.log(`  ${yellow}Bun is required but not installed.${reset}\n`);
+
+		rl.question(`  Install Bun now? ${dim}[Y/n]${reset}: `, async (answer) => {
+			rl.close();
+			const shouldInstall = answer.trim().toLowerCase() !== "n";
+
+			if (shouldInstall) {
+				try {
+					await installBun();
+					if (isBunInstalled()) {
+						callback();
+					} else {
+						console.log(`  ${yellow}Please restart your terminal to use Bun, then run the installer again.${reset}\n`);
+						process.exit(0);
+					}
+				} catch (err) {
+					console.log(`\n  ${red}Failed to install Bun:${reset} ${err.message}\n`);
+					showBunInstallInstructions();
+					process.exit(1);
+				}
+			} else {
+				showBunInstallInstructions();
+				process.exit(1);
+			}
+		});
+	}
+
 	function copyDir(src, dest) {
 		fs.mkdirSync(dest, { recursive: true });
 		const entries = fs.readdirSync(src, { withFileTypes: true });
@@ -177,9 +306,10 @@ ${cyan}  ███████╗██╗     ██╗   ██╗██╗
 			mcpConfig.mcpServers = {};
 		}
 
+		const versionTag = pkg.version.includes("-dev.") ? "latest" : pkg.version;
 		mcpConfig.mcpServers.flux = {
-			command: "npx",
-			args: ["-y", `@cliangdev/flux-plugin@${pkg.version}`, "serve"],
+			command: "bunx",
+			args: [`@cliangdev/flux-plugin@${versionTag}`, "serve"],
 		};
 
 		writeJson(mcpConfigPath, mcpConfig);
@@ -222,14 +352,18 @@ ${cyan}  ███████╗██╗     ██╗   ██╗██╗
 		});
 	}
 
-	if (hasGlobal && hasLocal) {
-		console.error(`  ${yellow}Cannot specify both --global and --local${reset}`);
-		process.exit(1);
-	} else if (hasGlobal) {
-		install(true);
-	} else if (hasLocal) {
-		install(false);
-	} else {
-		promptLocation();
+	function startInstallation() {
+		if (hasGlobal && hasLocal) {
+			console.error(`  ${yellow}Cannot specify both --global and --local${reset}`);
+			process.exit(1);
+		} else if (hasGlobal) {
+			install(true);
+		} else if (hasLocal) {
+			install(false);
+		} else {
+			promptLocation();
+		}
 	}
+
+	checkBunAndContinue(startInstallation);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cliangdev/flux-plugin",
-  "version": "0.0.0-dev.cbdf207",
+  "version": "0.0.0-dev.df3e9bb",
   "description": "Claude Code plugin for AI-first workflow orchestration with MCP server",
   "type": "module",
   "main": "./dist/server/index.js",
@@ -8,8 +8,8 @@
     "flux-plugin": "./bin/install.cjs"
   },
   "files": [
-    "bin/",
-    "dist/",
+    "bin/install.cjs",
+    "src/",
     "skills/",
     "commands/",
     "agents/",
@@ -17,14 +17,12 @@
   ],
   "scripts": {
     "dev": "bun run src/server/index.ts",
-    "build": "bun build src/server/index.ts --outdir dist/server --target node --external better-sqlite3",
-    "postbuild": "node -e \"const fs=require('fs');const f='dist/server/index.js';const c=fs.readFileSync(f,'utf-8');if(!c.startsWith('#!/usr/bin/env node')){fs.writeFileSync(f,'#!/usr/bin/env node\\n'+c)}\"",
-    "build:compile": "bun build --compile --outfile bin/flux-server src/server/index.ts && bun build --compile --outfile bin/flux-status src/status-line/index.ts",
-    "build:compile:server": "bun build --compile --outfile bin/flux-server src/server/index.ts",
-    "build:compile:status": "bun build --compile --outfile bin/flux-status src/status-line/index.ts",
+    "build": "bun build --compile --outfile bin/flux-server src/server/index.ts && bun build --compile --outfile bin/flux-status src/status-line/index.ts",
+    "build:server": "bun build --compile --outfile bin/flux-server src/server/index.ts",
+    "build:status": "bun build --compile --outfile bin/flux-status src/status-line/index.ts",
     "validate": "node scripts/validate-structure.cjs",
     "test:integration": "bun test scripts/__tests__/integration.test.ts --timeout 120000",
-    "prepublishOnly": "bun run validate && bun run build && bun run test:integration",
+    "prepublishOnly": "bun run validate && bun run test:integration",
     "test": "bun test",
     "test:linear-description": "bun run src/server/adapters/__tests__/linear-description-test.ts",
     "typecheck": "tsc --noEmit",
@@ -53,14 +51,12 @@
   "license": "MIT",
   "devDependencies": {
     "@biomejs/biome": "^2.3.11",
-    "@types/better-sqlite3": "^7.6.13",
     "@types/bun": "^1.3.6",
     "typescript": "^5.0.0"
   },
   "dependencies": {
     "@linear/sdk": "^70.0.0",
     "@modelcontextprotocol/sdk": "^1.25.2",
-    "better-sqlite3": "^12.6.2",
     "chalk": "^5.4.1",
     "zod": "^4.3.5"
   },

package/src/__tests__/version.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, test } from "bun:test";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+describe("version module", () => {
+  test("VERSION is exported from src/version.ts", async () => {
+    // Dynamic import to get the VERSION constant
+    const versionModule = await import("../version.js");
+
+    expect(versionModule.VERSION).toBeDefined();
+    expect(typeof versionModule.VERSION).toBe("string");
+  });
+
+  test("VERSION equals package.json version", async () => {
+    // Read package.json version
+    const packageJsonPath = join(process.cwd(), "package.json");
+    expect(existsSync(packageJsonPath)).toBe(true);
+
+    const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf-8"));
+    const packageVersion = packageJson.version;
+
+    expect(packageVersion).toBeDefined();
+    expect(typeof packageVersion).toBe("string");
+
+    // Import VERSION and compare
+    const versionModule = await import("../version.js");
+    expect(versionModule.VERSION).toBe(packageVersion);
+  });
+
+  test("VERSION is a valid semver format", async () => {
+    const versionModule = await import("../version.js");
+
+    // Basic semver format check (e.g., "0.1.0", "1.2.3-beta.1")
+    const semverPattern = /^\d+\.\d+\.\d+(-[\w.]+)?$/;
+    expect(semverPattern.test(versionModule.VERSION)).toBe(true);
+  });
+});

package/src/server/__tests__/config.test.ts

@@ -0,0 +1,163 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import {
+  existsSync,
+  mkdirSync,
+  realpathSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+
+describe("config", () => {
+  const originalEnv = process.env.FLUX_PROJECT_ROOT;
+  const originalCwd = process.cwd();
+  // Use os.tmpdir() to get the real temp path (handles /tmp -> /private/tmp on macOS)
+  const TEST_DIR = `${realpathSync(tmpdir())}/flux-config-test-${Date.now()}`;
+  const NESTED_DIR = `${TEST_DIR}/subdir/nested`;
+
+  beforeEach(async () => {
+    // Clean up any previous test directory
+    if (existsSync(TEST_DIR)) {
+      rmSync(TEST_DIR, { recursive: true });
+    }
+
+    // Create test directory structure
+    mkdirSync(NESTED_DIR, { recursive: true });
+
+    // Clear the config cache before each test
+    const { config } = await import("../config.js");
+    config.clearCache();
+  });
+
+  afterEach(async () => {
+    // Restore original env
+    if (originalEnv !== undefined) {
+      process.env.FLUX_PROJECT_ROOT = originalEnv;
+    } else {
+      delete process.env.FLUX_PROJECT_ROOT;
+    }
+
+    // Restore original cwd
+    process.chdir(originalCwd);
+
+    // Clear the config cache
+    const { config } = await import("../config.js");
+    config.clearCache();
+
+    // Clean up test directory
+    if (existsSync(TEST_DIR)) {
+      rmSync(TEST_DIR, { recursive: true });
+    }
+  });
+
+  test("uses env var when properly set", async () => {
+    process.env.FLUX_PROJECT_ROOT = "/some/valid/path";
+
+    const { config } = await import("../config.js");
+    config.clearCache();
+
+    expect(config.projectRoot).toBe("/some/valid/path");
+  });
+
+  test("ignores unresolved template variable and walks up directories", async () => {
+    // Create a .flux folder at TEST_DIR
+    mkdirSync(`${TEST_DIR}/.flux`, { recursive: true });
+    writeFileSync(
+      `${TEST_DIR}/.flux/project.json`,
+      JSON.stringify({ name: "test" }),
+    );
+
+    // Simulate Claude Code passing unresolved template variable
+    // biome-ignore lint/suspicious/noTemplateCurlyInString: intentionally testing literal template string
+    process.env.FLUX_PROJECT_ROOT = "${CLAUDE_PROJECT_DIR}";
+
+    // Change to nested directory
+    process.chdir(NESTED_DIR);
+
+    const { config } = await import("../config.js");
+    config.clearCache();
+
+    // Should walk up and find TEST_DIR, not use the literal "${CLAUDE_PROJECT_DIR}"
+    expect(config.projectRoot).not.toContain("${");
+    expect(config.projectRoot).toBe(TEST_DIR);
+  });
+
+  test("walks up directories to find .flux folder", async () => {
+    // Create a .flux folder at TEST_DIR (parent of NESTED_DIR)
+    mkdirSync(`${TEST_DIR}/.flux`, { recursive: true });
+    writeFileSync(
+      `${TEST_DIR}/.flux/project.json`,
+      JSON.stringify({ name: "test" }),
+    );
+
+    // No env var set
+    delete process.env.FLUX_PROJECT_ROOT;
+
+    // Change to nested directory
+    process.chdir(NESTED_DIR);
+
+    const { config } = await import("../config.js");
+    config.clearCache();
+
+    // Should walk up and find TEST_DIR
+    expect(config.projectRoot).toBe(TEST_DIR);
+  });
+
+  test("falls back to cwd when no .flux folder found", async () => {
+    // No .flux folder anywhere in TEST_DIR hierarchy
+    // No env var set
+    delete process.env.FLUX_PROJECT_ROOT;
+
+    // Change to test directory (which has no .flux)
+    process.chdir(TEST_DIR);
+
+    const { config } = await import("../config.js");
+    config.clearCache();
+
+    // Should fall back to cwd
+    expect(config.projectRoot).toBe(TEST_DIR);
+  });
+
+  test("projectExists returns true when project.json exists", async () => {
+    mkdirSync(`${TEST_DIR}/.flux`, { recursive: true });
+    writeFileSync(
+      `${TEST_DIR}/.flux/project.json`,
+      JSON.stringify({ name: "test" }),
+    );
+
+    process.env.FLUX_PROJECT_ROOT = TEST_DIR;
+
+    const { config } = await import("../config.js");
+    config.clearCache();
+
+    expect(config.projectExists).toBe(true);
+  });
+
+  test("projectExists returns false when project.json does not exist", async () => {
+    // No .flux folder
+    process.env.FLUX_PROJECT_ROOT = TEST_DIR;
+
+    const { config } = await import("../config.js");
+    config.clearCache();
+
+    expect(config.projectExists).toBe(false);
+  });
+
+  test("caches project root for performance", async () => {
+    process.env.FLUX_PROJECT_ROOT = "/first/path";
+
+    const { config } = await import("../config.js");
+    config.clearCache();
+
+    // First call caches the value
+    expect(config.projectRoot).toBe("/first/path");
+
+    // Changing env var should not affect cached value
+    process.env.FLUX_PROJECT_ROOT = "/second/path";
+    expect(config.projectRoot).toBe("/first/path");
+
+    // After clearing cache, should use new env var
+    config.clearCache();
+    expect(config.projectRoot).toBe("/second/path");
+  });
+});