@thieung/agentkit-helper 0.1.0

package/lib/runner.mjs

@@ -0,0 +1,213 @@
+import { spawn } from "node:child_process";
+
+function jsonErrorMessage(output) {
+  const candidates = [output, ...String(output).split("\n").reverse()];
+  for (const candidate of candidates) {
+    try {
+      const value = JSON.parse(candidate);
+      const messages = [
+        value?.error?.message,
+        typeof value?.error === "string" ? value.error : null,
+        value?.message,
+        value?.data?.error?.message,
+        typeof value?.data?.error === "string" ? value.data.error : null,
+        value?.data?.message,
+        value?.errors?.[0]?.message,
+      ];
+      const message = messages.find((item) => typeof item === "string" && item.trim());
+      if (message) return message.trim();
+    } catch {
+      // A command may emit NDJSON mixed with ordinary diagnostic lines.
+    }
+  }
+  return null;
+}
+
+function conciseErrorMessage(message) {
+  const concise = String(message)
+    .replace(/^Error:\s*/i, "")
+    .replace(/^(?:init|install|update):\s*/i, "")
+    .replace(/^lifecycle preflight:\s*/i, "")
+    .trim();
+  return concise.length > 160 ? `${concise.slice(0, 157)}…` : concise;
+}
+
+export function summarizeCommandFailure(stdout, stderr, fallback = "Command failed") {
+  const jsonMessage = jsonErrorMessage(stderr.trim()) || jsonErrorMessage(stdout.trim());
+  if (jsonMessage) return conciseErrorMessage(jsonMessage);
+  const lines = `${stderr}\n${stdout}`
+    .replaceAll(/\u001B\[[0-?]*[ -/]*[@-~]/g, "")
+    .split("\n")
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .filter((line) => !/^[╭╰].*[╮╯]$/.test(line))
+    .map((line) => line.replace(/^│\s?/, "").replace(/\s?│$/, "").trim())
+    .filter((line) => line !== "Command failed.")
+    .filter((line) => !/^→?\s*Re-run with --verbose/i.test(line));
+  const explicitError = lines.find((line) => /^Error:/i.test(line));
+  if (explicitError) return conciseErrorMessage(explicitError);
+  return lines.slice(0, 4).map(conciseErrorMessage).join("\n") || fallback;
+}
+
+export function requiresForceConsent(error) {
+  if (error?.exitCode === 6) return true;
+  const diagnostic = `${error?.message || ""}\n${error?.stderr || ""}`;
+  return /target directory already exists|drifted files detected/i.test(diagnostic) &&
+    /--force/i.test(diagnostic);
+}
+
+export function run(binary, args, { cwd = process.cwd(), stdio = "inherit" } = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(binary, args, {
+      cwd,
+      stdio,
+      shell: false,
+      env: process.env,
+    });
+    child.once("error", (error) => {
+      error.command = { binary, args: [...args], cwd };
+      reject(error);
+    });
+    child.once("exit", (code, signal) => {
+      if (signal) {
+        const error = new Error(`${binary} terminated by ${signal}`);
+        error.command = { binary, args: [...args], cwd };
+        reject(error);
+        return;
+      }
+      if (code !== 0) {
+        const error = new Error(`${binary} exited with status ${code}`);
+        error.exitCode = code;
+        error.command = { binary, args: [...args], cwd };
+        reject(error);
+        return;
+      }
+      resolve();
+    });
+  });
+}
+
+export function runCapture(binary, args, { cwd = process.cwd() } = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(binary, args, {
+      cwd,
+      stdio: ["ignore", "pipe", "pipe"],
+      shell: false,
+      env: process.env,
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (chunk) => { stdout += chunk; });
+    child.stderr.on("data", (chunk) => { stderr += chunk; });
+    child.once("error", (error) => {
+      error.command = { binary, args: [...args], cwd };
+      reject(error);
+    });
+    child.once("exit", (code, signal) => {
+      if (signal || code !== 0) {
+        const fallback = signal
+          ? `${binary} terminated by ${signal}`
+          : `${binary} exited with status ${code}`;
+        const error = new Error(summarizeCommandFailure(stdout, stderr, fallback));
+        error.exitCode = code || 1;
+        error.command = { binary, args: [...args], cwd };
+        error.stdout = stdout.trim();
+        error.stderr = stderr.trim();
+        reject(error);
+        return;
+      }
+      resolve({ stdout: stdout.trim(), stderr: stderr.trim() });
+    });
+  });
+}
+
+export function runPipeline(
+  sourceBinary,
+  sourceArgs,
+  targetBinary,
+  targetArgs,
+  { cwd = process.cwd(), targetEnv = {} } = {},
+) {
+  return new Promise((resolve, reject) => {
+    const source = spawn(sourceBinary, sourceArgs, {
+      cwd,
+      stdio: ["ignore", "pipe", "inherit"],
+      shell: false,
+      env: process.env,
+    });
+    const target = spawn(targetBinary, targetArgs, {
+      cwd,
+      stdio: ["pipe", "inherit", "inherit"],
+      shell: false,
+      env: { ...process.env, ...targetEnv },
+    });
+    source.stdout.pipe(target.stdin);
+    const command = {
+      binary: sourceBinary,
+      args: [...sourceArgs],
+      cwd,
+      pipeline: { binary: targetBinary, args: [...targetArgs] },
+    };
+    let sourceDone = false;
+    let targetDone = false;
+    let settled = false;
+
+    function fail(message, exitCode = 1) {
+      if (settled) return;
+      settled = true;
+      source.kill();
+      target.kill();
+      const error = new Error(message);
+      error.exitCode = exitCode;
+      error.command = command;
+      reject(error);
+    }
+
+    function finish() {
+      if (!settled && sourceDone && targetDone) {
+        settled = true;
+        resolve();
+      }
+    }
+
+    source.once("error", (error) => fail(error.message));
+    target.once("error", (error) => fail(error.message));
+    source.once("exit", (code, signal) => {
+      if (signal || code !== 0) {
+        fail(signal ? `${sourceBinary} terminated by ${signal}` : `${sourceBinary} exited with status ${code}`, code || 1);
+        return;
+      }
+      sourceDone = true;
+      finish();
+    });
+    target.once("exit", (code, signal) => {
+      if (signal || code !== 0) {
+        fail(signal ? `${targetBinary} terminated by ${signal}` : `${targetBinary} exited with status ${code}`, code || 1);
+        return;
+      }
+      targetDone = true;
+      finish();
+    });
+  });
+}
+
+export async function ensureAk(binary) {
+  try {
+    return (await runCapture(binary, ["--version"])).stdout;
+  } catch (error) {
+    if (error.code !== "ENOENT") {
+      throw error;
+    }
+    const lines = [
+      "The ak CLI is not available on PATH.",
+      "Install it from the official AgentKit endpoint, then open a new terminal:",
+      "",
+    ];
+    if (process.platform === "win32") {
+      lines.push("  irm https://agentkit.best/install.ps1 | iex");
+    } else {
+      lines.push("  curl -fsSL https://agentkit.best/install.sh | sh");
+    }
+    throw new Error(lines.join("\n"));
+  }
+}

package/lib/self-update.mjs

@@ -0,0 +1,65 @@
+const SEMVER = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/;
+
+export function releaseChannelForVersion(output) {
+  const version = String(output || "").trim().replace(/^ak\s+/i, "");
+  const match = SEMVER.exec(version);
+  if (!match) return null;
+  return match[4] ? "beta" : "stable";
+}
+
+function comparePrerelease(left, right) {
+  if (left === right) return 0;
+  if (!left) return 1;
+  if (!right) return -1;
+  const leftParts = left.split(".");
+  const rightParts = right.split(".");
+  for (let index = 0; index < Math.max(leftParts.length, rightParts.length); index += 1) {
+    if (leftParts[index] === undefined) return -1;
+    if (rightParts[index] === undefined) return 1;
+    if (leftParts[index] === rightParts[index]) continue;
+    const leftNumber = /^\d+$/.test(leftParts[index]) ? Number(leftParts[index]) : null;
+    const rightNumber = /^\d+$/.test(rightParts[index]) ? Number(rightParts[index]) : null;
+    if (leftNumber !== null && rightNumber !== null) return Math.sign(leftNumber - rightNumber);
+    if (leftNumber !== null) return -1;
+    if (rightNumber !== null) return 1;
+    return leftParts[index] < rightParts[index] ? -1 : 1;
+  }
+  return 0;
+}
+
+export function compareVersions(left, right) {
+  const leftMatch = SEMVER.exec(left);
+  const rightMatch = SEMVER.exec(right);
+  if (!leftMatch || !rightMatch) throw new Error("invalid self-update version contract");
+  for (let index = 1; index <= 3; index += 1) {
+    const comparison = Number(leftMatch[index]) - Number(rightMatch[index]);
+    if (comparison !== 0) return Math.sign(comparison);
+  }
+  return comparePrerelease(leftMatch[4] || "", rightMatch[4] || "");
+}
+
+export function parseSelfUpdateOutput(output) {
+  const value = JSON.parse(output);
+  const data = value?.data;
+  if (
+    value?.schema_version !== 1 || value?.kind !== "self_update" ||
+    typeof data?.current_version !== "string" || typeof data?.latest_version !== "string" ||
+    typeof data?.available !== "boolean" || typeof data?.status !== "string"
+  ) {
+    throw new Error("unsupported ak self-update JSON contract");
+  }
+  return data;
+}
+
+export function classifySelfUpdate(result) {
+  if (result.available) return "update";
+  if (result.status !== "current") return "unavailable";
+  const comparison = compareVersions(result.latest_version, result.current_version);
+  if (comparison < 0) return "downgrade";
+  return comparison === 0 ? "current" : "unavailable";
+}
+
+export function assertInstallerVersion(version) {
+  if (!SEMVER.test(version)) throw new Error("refusing invalid installer version");
+  return version.replace(/^v/, "");
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@thieung/agentkit-helper",
+  "version": "0.1.0",
+  "description": "Community helper for installing and updating AgentKit kits by runtime and channel",
+  "type": "module",
+  "bin": {
+    "agentkit-helper": "bin/agentkit-helper.mjs",
+    "akh": "bin/agentkit-helper.mjs"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "assets/",
+    "README.md",
+    "README.vi.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test --test-concurrency=1 test/*.test.mjs",
+    "check": "node --check bin/agentkit-helper.mjs && node --check lib/*.mjs"
+  },
+  "engines": {
+    "node": ">=20.12"
+  },
+  "keywords": [
+    "agentkit",
+    "coding-agent",
+    "claude-code",
+    "codex",
+    "cursor"
+  ],
+  "author": "Thieu Nguyen",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/thieung/agentkit-helper.git"
+  },
+  "bugs": {
+    "url": "https://github.com/thieung/agentkit-helper/issues"
+  },
+  "homepage": "https://github.com/thieung/agentkit-helper#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.7.0"
+  }
+}