kablan 0.5.0

package/README.md

@@ -0,0 +1,65 @@
+# Kablan
+
+Run coding agents — Claude Code, Codex, Gemini CLI, Amp and others — against your repositories
+from a board, and watch them work.
+
+Each task gets its own git worktree and its own branch, so several agents can run at once without
+standing on each other. You follow the conversation, review the diff, start the project's dev
+server, and merge or open a PR when it looks right.
+
+## Run it
+
+```bash
+npx kablan
+```
+
+Nothing to install. This downloads the binary for your platform, caches it under `~/.kablan/bin`,
+and opens Kablan in your browser.
+
+## Install it as an app (macOS)
+
+```bash
+npx kablan --install
+```
+
+Puts `Kablan.app` in `~/Applications`. Opening it starts Kablan in the background — no terminal
+window — and opens your browser. Output goes to `~/Library/Logs/Kablan/kablan.log`.
+
+Because the bundle is assembled on your machine rather than downloaded, macOS does not quarantine
+it: no "unidentified developer" prompt, and nothing to notarise.
+
+- Update: `npx kablan@latest --install`
+- Remove: `npx kablan --uninstall` (cached binaries stay in `~/.kablan/bin`)
+
+## What you need
+
+- **Node 18 or newer**, to run this wrapper.
+- **A coding agent, already authenticated.** Kablan drives each agent's own CLI, so it uses the
+  subscription you already have and never sees your model credentials.
+- **Git.** Every attempt is a worktree on its own branch.
+
+Platforms: macOS on Apple silicon and Intel, Linux x64, Windows x64.
+
+## Environment
+
+| Variable | What it does |
+| --- | --- |
+| `PORT` | Port to serve on. Defaults to one the OS picks. |
+| `HOST` | Host to bind. Defaults to `127.0.0.1`. |
+| `KABLAN_LOCAL=1` | Use binaries from `npx-cli/dist/` instead of a release, for development. |
+| `KABLAN_DEBUG=1` | Verbose wrapper output. |
+
+## MCP
+
+```bash
+npx kablan --mcp
+```
+
+Runs the MCP task server on stdio, so an agent can create and update Kablan tasks itself.
+
+## About
+
+Kablan is a fork of [Vibe Kanban](https://github.com/BloopAI/vibe-kanban) by Bloop AI, used under
+the Apache License 2.0. It is not affiliated with or endorsed by Bloop AI.
+
+Source and issues: [github.com/AmarShaked/kablan.dev](https://github.com/AmarShaked/kablan.dev)

package/bin/cli.js

@@ -0,0 +1,218 @@
+#!/usr/bin/env node
+
+const { execSync, spawn } = require("child_process");
+const AdmZip = require("adm-zip");
+const path = require("path");
+const fs = require("fs");
+const { ensureBinary, BINARY_TAG, CACHE_DIR, LOCAL_DEV_MODE, LOCAL_DIST_DIR, getLatestVersion } = require("./download");
+const { installMacApp, uninstallMacApp, appDir } = require("./install-app");
+
+const CLI_VERSION = require("../package.json").version;
+
+// Resolve effective arch for our published 64-bit binaries only.
+// Any ARM → arm64; anything else → x64. On macOS, handle Rosetta.
+function getEffectiveArch() {
+  const platform = process.platform;
+  const nodeArch = process.arch;
+
+  if (platform === "darwin") {
+    // If Node itself is arm64, we're natively on Apple silicon
+    if (nodeArch === "arm64") return "arm64";
+
+    // Otherwise check for Rosetta translation
+    try {
+      const translated = execSync("sysctl -in sysctl.proc_translated", {
+        encoding: "utf8",
+      }).trim();
+      if (translated === "1") return "arm64";
+    } catch {
+      // sysctl key not present → assume true Intel
+    }
+    return "x64";
+  }
+
+  // Non-macOS: coerce to broad families we support
+  if (/arm/i.test(nodeArch)) return "arm64";
+
+  // On Windows with 32-bit Node (ia32), detect OS arch via env
+  if (platform === "win32") {
+    const pa = process.env.PROCESSOR_ARCHITECTURE || "";
+    const paw = process.env.PROCESSOR_ARCHITEW6432 || "";
+    if (/arm/i.test(pa) || /arm/i.test(paw)) return "arm64";
+  }
+
+  return "x64";
+}
+
+const platform = process.platform;
+const arch = getEffectiveArch();
+
+// Map to our build target names
+function getPlatformDir() {
+  if (platform === "linux" && arch === "x64") return "linux-x64";
+  if (platform === "linux" && arch === "arm64") return "linux-arm64";
+  if (platform === "win32" && arch === "x64") return "windows-x64";
+  if (platform === "win32" && arch === "arm64") return "windows-arm64";
+  if (platform === "darwin" && arch === "x64") return "macos-x64";
+  if (platform === "darwin" && arch === "arm64") return "macos-arm64";
+
+  console.error(`Unsupported platform: ${platform}-${arch}`);
+  console.error("Supported platforms:");
+  console.error("  - Linux x64");
+  console.error("  - Linux ARM64");
+  console.error("  - Windows x64");
+  console.error("  - Windows ARM64");
+  console.error("  - macOS x64 (Intel)");
+  console.error("  - macOS ARM64 (Apple Silicon)");
+  process.exit(1);
+}
+
+function getBinaryName(base) {
+  return platform === "win32" ? `${base}.exe` : base;
+}
+
+const platformDir = getPlatformDir();
+// In local dev mode, extract directly to dist directory; otherwise use global cache
+const versionCacheDir = LOCAL_DEV_MODE
+  ? path.join(LOCAL_DIST_DIR, platformDir)
+  : path.join(CACHE_DIR, BINARY_TAG, platformDir);
+
+function showProgress(downloaded, total) {
+  const percent = total ? Math.round((downloaded / total) * 100) : 0;
+  const mb = (downloaded / (1024 * 1024)).toFixed(1);
+  const totalMb = total ? (total / (1024 * 1024)).toFixed(1) : "?";
+  process.stderr.write(`\r   Downloading: ${mb}MB / ${totalMb}MB (${percent}%)`);
+}
+
+async function extractAndRun(baseName, launch) {
+  const binName = getBinaryName(baseName);
+  const binPath = path.join(versionCacheDir, binName);
+  const zipPath = path.join(versionCacheDir, `${baseName}.zip`);
+
+  // Clean old binary if exists
+  try {
+    if (fs.existsSync(binPath)) {
+      fs.unlinkSync(binPath);
+    }
+  } catch (err) {
+    if (process.env.KABLAN_DEBUG) {
+      console.warn(`Warning: Could not delete existing binary: ${err.message}`);
+    }
+  }
+
+  // Download if not cached
+  if (!fs.existsSync(zipPath)) {
+    console.error(`Downloading ${baseName}...`);
+    try {
+      await ensureBinary(platformDir, baseName, showProgress);
+      console.error(""); // newline after progress
+    } catch (err) {
+      console.error(`\nDownload failed: ${err.message}`);
+      process.exit(1);
+    }
+  }
+
+  // Extract
+  if (!fs.existsSync(binPath)) {
+    try {
+      const zip = new AdmZip(zipPath);
+      zip.extractAllTo(versionCacheDir, true);
+    } catch (err) {
+      console.error("Extraction failed:", err.message);
+      try {
+        fs.unlinkSync(zipPath);
+      } catch {}
+      process.exit(1);
+    }
+  }
+
+  if (!fs.existsSync(binPath)) {
+    console.error(`Extracted binary not found at: ${binPath}`);
+    console.error("This usually indicates a corrupt download. Please try again.");
+    process.exit(1);
+  }
+
+  // Set permissions (non-Windows)
+  if (platform !== "win32") {
+    try {
+      fs.chmodSync(binPath, 0o755);
+    } catch {}
+  }
+
+  return launch(binPath);
+}
+
+async function main() {
+  fs.mkdirSync(versionCacheDir, { recursive: true });
+
+  const args = process.argv.slice(2);
+  const isMcpMode = args.includes("--mcp");
+
+  // `--install` puts a double-clickable app in ~/Applications and exits; it never starts a
+  // server itself, so re-running it to update is safe while Kablan is open.
+  if (args.includes("--uninstall")) {
+    const removed = uninstallMacApp();
+    console.log(removed ? `Removed ${removed}` : `Nothing installed at ${appDir()}`);
+    console.log("Cached binaries are still in ~/.kablan/bin; delete that to reclaim the space.");
+    return;
+  }
+
+  if (args.includes("--install")) {
+    await extractAndRun("kablan", (bin) => {
+      const app = installMacApp(bin, CLI_VERSION);
+      console.log(`\nInstalled ${app}`);
+      console.log("Open it from Launchpad or Spotlight — it starts Kablan in the background");
+      console.log("and opens your browser. Logs: ~/Library/Logs/Kablan/kablan.log");
+      console.log("\nUpdate with `npx kablan@latest --install`, remove with `npx kablan --uninstall`.");
+    });
+    return;
+  }
+
+  // Non-blocking update check. Skipped in MCP mode, where stdout is a protocol stream, and in
+  // local dev mode, where the binaries did not come from a release.
+  if (!isMcpMode && !LOCAL_DEV_MODE) {
+    getLatestVersion()
+      .then((latest) => {
+        if (latest && latest !== CLI_VERSION) {
+          setTimeout(() => {
+            console.log(`\nUpdate available: ${CLI_VERSION} -> ${latest}`);
+            console.log(`Run: npx kablan@latest`);
+          }, 2000);
+        }
+      })
+      .catch(() => {});
+  }
+
+  if (isMcpMode) {
+    await extractAndRun("kablan-mcp", (bin) => {
+      const proc = spawn(bin, [], { stdio: "inherit" });
+      proc.on("exit", (c) => process.exit(c || 0));
+      proc.on("error", (e) => {
+        console.error("MCP server error:", e.message);
+        process.exit(1);
+      });
+      process.on("SIGINT", () => {
+        proc.kill("SIGINT");
+      });
+      process.on("SIGTERM", () => proc.kill("SIGTERM"));
+    });
+  } else {
+    const modeLabel = LOCAL_DEV_MODE ? " (local dev)" : "";
+    console.log(`Starting kablan v${CLI_VERSION}${modeLabel}...`);
+    await extractAndRun("kablan", (bin) => {
+      if (platform === "win32") {
+        execSync(`"${bin}"`, { stdio: "inherit" });
+      } else {
+        execSync(`"${bin}"`, { stdio: "inherit" });
+      }
+    });
+  }
+}
+
+main().catch((err) => {
+  console.error("Fatal error:", err.message);
+  if (process.env.KABLAN_DEBUG) {
+    console.error(err.stack);
+  }
+  process.exit(1);
+});

package/bin/download.js

@@ -0,0 +1,195 @@
+const https = require("https");
+const fs = require("fs");
+const path = require("path");
+const crypto = require("crypto");
+
+/**
+ * Where the binaries come from.
+ *
+ * Upstream hosted these in a Cloudflare R2 bucket whose URL was substituted in at pack time —
+ * infrastructure this fork does not have, which is why `npx kablan` could never have worked by
+ * renaming the package alone. They come from this repository's own GitHub release instead: one
+ * artifact store, one place to look when a download fails, and no second account to keep alive.
+ *
+ * The tag is derived from this package's own version rather than injected, which makes it
+ * impossible to publish a package pointing at binaries from a different release.
+ */
+const REPO = "AmarShaked/kablan.dev";
+const PKG_VERSION = require("../package.json").version;
+const BINARY_TAG = `v${PKG_VERSION}`;
+const RELEASE_BASE = `https://github.com/${REPO}/releases/download/${BINARY_TAG}`;
+
+const CACHE_DIR = path.join(require("os").homedir(), ".kablan", "bin");
+
+// Local development mode: use binaries from npx-cli/dist/ instead of the release.
+// Only activate if dist/ exists (i.e., running from source after local-build.sh)
+const LOCAL_DIST_DIR = path.join(__dirname, "..", "dist");
+const LOCAL_DEV_MODE = fs.existsSync(LOCAL_DIST_DIR) || process.env.KABLAN_LOCAL === "1";
+
+function get(url, onResponse, reject) {
+  https
+    .get(url, { headers: { "User-Agent": `kablan-cli/${PKG_VERSION}` } }, (res) => {
+      if (res.statusCode === 301 || res.statusCode === 302) {
+        return get(res.headers.location, onResponse, reject);
+      }
+      onResponse(res);
+    })
+    .on("error", reject);
+}
+
+async function fetchText(url) {
+  return new Promise((resolve, reject) => {
+    get(
+      url,
+      (res) => {
+        if (res.statusCode !== 200) {
+          return reject(new Error(`HTTP ${res.statusCode} fetching ${url}`));
+        }
+        let data = "";
+        res.on("data", (chunk) => (data += chunk));
+        res.on("end", () => resolve(data));
+      },
+      reject
+    );
+  });
+}
+
+async function fetchJson(url) {
+  return JSON.parse(await fetchText(url));
+}
+
+async function downloadFile(url, destPath, expectedSha256, onProgress) {
+  const tempPath = destPath + ".tmp";
+  return new Promise((resolve, reject) => {
+    const file = fs.createWriteStream(tempPath);
+    const hash = crypto.createHash("sha256");
+
+    const cleanup = () => {
+      try {
+        fs.unlinkSync(tempPath);
+      } catch {}
+    };
+
+    get(
+      url,
+      (res) => {
+        if (res.statusCode !== 200) {
+          file.close();
+          cleanup();
+          return reject(new Error(`HTTP ${res.statusCode} downloading ${url}`));
+        }
+
+        const totalSize = parseInt(res.headers["content-length"], 10);
+        let downloadedSize = 0;
+
+        res.on("data", (chunk) => {
+          downloadedSize += chunk.length;
+          hash.update(chunk);
+          if (onProgress) onProgress(downloadedSize, totalSize);
+        });
+        res.pipe(file);
+
+        file.on("finish", () => {
+          file.close();
+          const actualSha256 = hash.digest("hex");
+          if (expectedSha256 && actualSha256 !== expectedSha256) {
+            cleanup();
+            reject(
+              new Error(`Checksum mismatch: expected ${expectedSha256}, got ${actualSha256}`)
+            );
+          } else {
+            try {
+              fs.renameSync(tempPath, destPath);
+              resolve(destPath);
+            } catch (err) {
+              cleanup();
+              reject(err);
+            }
+          }
+        });
+      },
+      (err) => {
+        file.close();
+        cleanup();
+        reject(err);
+      }
+    );
+  });
+}
+
+/**
+ * The release's checksum file, parsed into { filename: sha256 }. Fetched at most once per run.
+ * A release without one still installs — the download is over HTTPS from a pinned tag — but the
+ * extra check is cheap and catches a truncated or swapped asset.
+ */
+let checksumsPromise = null;
+function getChecksums() {
+  if (!checksumsPromise) {
+    checksumsPromise = fetchText(`${RELEASE_BASE}/sha256sums.txt`)
+      .then((text) => {
+        const map = {};
+        for (const line of text.split("\n")) {
+          const m = line.trim().match(/^([0-9a-f]{64})\s+\*?(.+)$/i);
+          if (m) map[m[2]] = m[1].toLowerCase();
+        }
+        return map;
+      })
+      .catch(() => ({}));
+  }
+  return checksumsPromise;
+}
+
+async function ensureBinary(platform, binaryName, onProgress) {
+  // In local dev mode, use binaries directly from npx-cli/dist/
+  if (LOCAL_DEV_MODE) {
+    const localZipPath = path.join(LOCAL_DIST_DIR, platform, `${binaryName}.zip`);
+    if (fs.existsSync(localZipPath)) {
+      return localZipPath;
+    }
+    throw new Error(
+      `Local binary not found: ${localZipPath}\n` +
+        `Run ./local-build.sh first to build the binaries.`
+    );
+  }
+
+  const cacheDir = path.join(CACHE_DIR, BINARY_TAG, platform);
+  const zipPath = path.join(cacheDir, `${binaryName}.zip`);
+
+  if (fs.existsSync(zipPath)) return zipPath;
+
+  fs.mkdirSync(cacheDir, { recursive: true });
+
+  // Assets are flat on the release, so the platform is part of the name.
+  const assetName = `${binaryName}-${platform}.zip`;
+  const checksums = await getChecksums();
+
+  try {
+    await downloadFile(`${RELEASE_BASE}/${assetName}`, zipPath, checksums[assetName], onProgress);
+  } catch (err) {
+    if (/HTTP 404/.test(err.message)) {
+      throw new Error(
+        `${binaryName} is not published for ${platform} in ${BINARY_TAG}.\n` +
+          `See https://github.com/${REPO}/releases/tag/${BINARY_TAG} for what that release contains.`
+      );
+    }
+    throw err;
+  }
+
+  return zipPath;
+}
+
+async function getLatestVersion() {
+  const release = await fetchJson(`https://api.github.com/repos/${REPO}/releases/latest`);
+  return String(release.tag_name || "").replace(/^v/, "");
+}
+
+module.exports = {
+  REPO,
+  RELEASE_BASE,
+  BINARY_TAG,
+  CACHE_DIR,
+  LOCAL_DEV_MODE,
+  LOCAL_DIST_DIR,
+  ensureBinary,
+  getLatestVersion,
+};

package/bin/install-app.js

@@ -0,0 +1,136 @@
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const { execFileSync } = require("child_process");
+
+/**
+ * Installs Kablan into ~/Applications as a real macOS app.
+ *
+ * The point is a double-clickable icon that starts Kablan in the background — no Terminal
+ * window, no command to remember. It also happens to sidestep Gatekeeper: the bundle is
+ * assembled here, on this machine, from a binary this process downloaded, so nothing carries the
+ * quarantine flag that produces "unidentified developer". A downloaded .app would need
+ * notarisation and a paid Apple account; one built locally needs neither.
+ */
+
+const APP_NAME = "Kablan";
+const BUNDLE_ID = "dev.kablan.app";
+
+function appDir() {
+  // ~/Applications rather than /Applications: it needs no password, and Spotlight and Launchpad
+  // both index it.
+  return path.join(os.homedir(), "Applications", `${APP_NAME}.app`);
+}
+
+/**
+ * A GUI-launched process inherits a minimal PATH — roughly /usr/bin:/bin — so the coding agents,
+ * node and pnpm are all missing and every task fails at its first command. The launcher asks the
+ * login shell what PATH really is, the same thing a terminal would have.
+ */
+function launcherScript() {
+  return `#!/bin/bash
+# Generated by \`npx kablan --install\`. Re-run that to update.
+set -u
+
+HERE="$(cd "$(dirname "$0")" && pwd)"
+
+# Adopt the login shell's PATH; a GUI launch would otherwise see almost nothing.
+SHELL_BIN="\${SHELL:-/bin/zsh}"
+RESOLVED="$("$SHELL_BIN" -ilc 'printf %s "$PATH"' 2>/dev/null || true)"
+if [ -n "$RESOLVED" ]; then
+  export PATH="$RESOLVED"
+fi
+for dir in /opt/homebrew/bin /usr/local/bin /usr/bin /bin; do
+  case ":$PATH:" in *":$dir:"*) ;; *) PATH="$dir:$PATH" ;; esac
+done
+export PATH
+
+# There is no terminal attached, so keep output where it can be read after the fact.
+LOG_DIR="$HOME/Library/Logs/${APP_NAME}"
+mkdir -p "$LOG_DIR"
+
+exec "$HERE/${APP_NAME.toLowerCase()}-server" >>"$LOG_DIR/${APP_NAME.toLowerCase()}.log" 2>&1
+`;
+}
+
+function infoPlist(version) {
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>CFBundleName</key><string>${APP_NAME}</string>
+  <key>CFBundleDisplayName</key><string>${APP_NAME}</string>
+  <key>CFBundleIdentifier</key><string>${BUNDLE_ID}</string>
+  <key>CFBundleVersion</key><string>${version}</string>
+  <key>CFBundleShortVersionString</key><string>${version}</string>
+  <key>CFBundleExecutable</key><string>${APP_NAME}</string>
+  <key>CFBundleIconFile</key><string>${APP_NAME}</string>
+  <key>CFBundlePackageType</key><string>APPL</string>
+  <key>CFBundleInfoDictionaryVersion</key><string>6.0</string>
+  <key>NSHighResolutionCapable</key><true/>
+  <key>LSMinimumSystemVersion</key><string>11.0</string>
+</dict>
+</plist>
+`;
+}
+
+/**
+ * @param binPath  the extracted server binary to install
+ * @param version  the wrapper's version, shown in Finder's Get Info
+ */
+function installMacApp(binPath, version) {
+  if (process.platform !== "darwin") {
+    throw new Error(
+      `--install builds a macOS app bundle and this is ${process.platform}.\n` +
+        `On Linux and Windows, run \`npx kablan\` directly.`
+    );
+  }
+
+  const app = appDir();
+  const macos = path.join(app, "Contents", "MacOS");
+  const resources = path.join(app, "Contents", "Resources");
+
+  // Replace wholesale rather than merging, so an older layout cannot leave stale files behind.
+  fs.rmSync(app, { recursive: true, force: true });
+  fs.mkdirSync(macos, { recursive: true });
+  fs.mkdirSync(resources, { recursive: true });
+
+  fs.writeFileSync(path.join(app, "Contents", "Info.plist"), infoPlist(version));
+
+  const serverName = `${APP_NAME.toLowerCase()}-server`;
+  fs.copyFileSync(binPath, path.join(macos, serverName));
+  fs.chmodSync(path.join(macos, serverName), 0o755);
+
+  const launcher = path.join(macos, APP_NAME);
+  fs.writeFileSync(launcher, launcherScript());
+  fs.chmodSync(launcher, 0o755);
+
+  const icon = path.join(__dirname, "..", "assets", `${APP_NAME}.icns`);
+  if (fs.existsSync(icon)) {
+    fs.copyFileSync(icon, path.join(resources, `${APP_NAME}.icns`));
+  }
+
+  // Finder caches icons per bundle; without this the app can show a blank page icon until
+  // something else invalidates it.
+  try {
+    execFileSync("/usr/bin/touch", [app]);
+    execFileSync(
+      "/System/Library/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Support/lsregister",
+      ["-f", app],
+      { stdio: "ignore" }
+    );
+  } catch {
+    // Cosmetic only — the app works either way.
+  }
+
+  return app;
+}
+
+function uninstallMacApp() {
+  const app = appDir();
+  if (!fs.existsSync(app)) return null;
+  fs.rmSync(app, { recursive: true, force: true });
+  return app;
+}
+
+module.exports = { installMacApp, uninstallMacApp, appDir, APP_NAME };

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "kablan",
+  "version": "0.5.0",
+  "description": "NPX wrapper around the Kablan server and its MCP task server",
+  "license": "Apache-2.0",
+  "author": "Shaked Amar",
+  "homepage": "https://github.com/AmarShaked/kablan.dev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AmarShaked/kablan.dev.git"
+  },
+  "bugs": {
+    "url": "https://github.com/AmarShaked/kablan.dev/issues"
+  },
+  "keywords": [
+    "claude-code",
+    "codex",
+    "coding-agent",
+    "kanban",
+    "git-worktree",
+    "ai"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "bin": {
+    "kablan": "bin/cli.js"
+  },
+  "files": [
+    "bin",
+    "assets"
+  ],
+  "dependencies": {
+    "adm-zip": "^0.5.16"
+  },
+  "private": false
+}