larkit 0.0.0-stage → 0.1.0

package/src/bootstrap/cli-install.js

@@ -0,0 +1,184 @@
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import { spawnSync } from "node:child_process";
+import {
+  BIN_DIR,
+  CLI_INSTALL_DIR,
+  IS_REPO_CHECKOUT,
+  PKG_ROOT,
+  displayPath,
+} from "../shared/paths.js";
+import { ensureDir, readJson, writeJson } from "../shared/util.js";
+
+function runNpm(args) {
+  const command = process.platform === "win32" ? "npm.cmd" : "npm";
+  const result = spawnSync(command, args, {
+    encoding: "utf8",
+    shell: process.platform === "win32",
+    env: {
+      ...process.env,
+      npm_config_update_notifier: "false",
+      npm_config_fund: "false",
+    },
+  });
+  if (result.error) throw result.error;
+  if (result.status !== 0) {
+    const detail = (result.stderr || result.stdout || "").trim().split("\n").slice(-8).join("\n");
+    throw new Error(`npm ${args[0]} failed (exit ${result.status})${detail ? `:\n${detail}` : ""}`);
+  }
+  return result.stdout;
+}
+
+function shimBody(target) {
+  return `#!/usr/bin/env sh\nexec node "${target}" "$@"\n`;
+}
+
+function cmdShimBody(target) {
+  return `@echo off\r\nnode "${target}" %*\r\n`;
+}
+
+function writeShims(entry, binDir) {
+  const binDirOfPackage = path.dirname(entry);
+  const targets = {
+    larkit: path.join(binDirOfPackage, "larkit.js"),
+    "larkit-mcp": path.join(binDirOfPackage, "larkit-mcp.js"),
+  };
+  ensureDir(binDir);
+  const written = [];
+  for (const [name, target] of Object.entries(targets)) {
+    if (!fs.existsSync(target)) continue;
+    const file = path.join(binDir, name);
+    fs.writeFileSync(file, shimBody(target));
+    fs.chmodSync(file, 0o755);
+    written.push(file);
+    if (process.platform === "win32") {
+      const cmd = `${file}.cmd`;
+      fs.writeFileSync(cmd, cmdShimBody(target));
+      written.push(cmd);
+    }
+  }
+  return written;
+}
+
+export function binDirOnPath(binDir = BIN_DIR) {
+  const parts = String(process.env.PATH || "")
+    .split(path.delimiter)
+    .filter(Boolean)
+    .map((part) => path.resolve(part));
+  return parts.includes(path.resolve(binDir));
+}
+
+export function detectCliInstall({ binDir = BIN_DIR } = {}) {
+  const shim = path.join(binDir, "larkit");
+  const installedPackage = path.join(CLI_INSTALL_DIR, "node_modules", "larkit", "package.json");
+  const repoVersion = IS_REPO_CHECKOUT
+    ? readJson(path.join(PKG_ROOT, "package.json"), {}).version || null
+    : null;
+  return {
+    shim,
+    shim_installed: fs.existsSync(shim),
+    bin_dir: binDir,
+    on_path: binDirOnPath(binDir),
+    mode: fs.existsSync(installedPackage)
+      ? "local-prefix"
+      : IS_REPO_CHECKOUT
+        ? "repo"
+        : null,
+    version: readJson(installedPackage, {}).version || repoVersion,
+  };
+}
+
+/**
+ * Install a durable `larkit` command.
+ *
+ * Default strategy: install the package into ~/.larkit/cli and drop a tiny
+ * shell shim into ~/.local/bin, so no sudo/global prefix is required and the
+ * command survives npx cache cleanup.  In a git checkout the shim points at
+ * the checkout itself.  `--global` delegates to `npm install -g`.
+ */
+export function installCli({
+  version,
+  force = false,
+  global = false,
+  binDir = BIN_DIR,
+  source = null,
+} = {}) {
+  if (global) {
+    const target = source || `larkit@${version}`;
+    runNpm(["install", "-g", target, "--no-audit", "--no-fund", "--loglevel=error"]);
+    return {
+      mode: "global",
+      entry: null,
+      shim: null,
+      bin_dir: binDir,
+      on_path: binDirOnPath(binDir),
+      status: "installed",
+    };
+  }
+
+  const devCheckout =
+    IS_REPO_CHECKOUT && fs.existsSync(path.join(PKG_ROOT, "bin", "larkit.js"));
+
+  if (devCheckout && !source) {
+    const entry = path.join(PKG_ROOT, "bin", "larkit.js");
+    const written = writeShims(entry, binDir);
+    return {
+      mode: "repo",
+      entry,
+      shim: path.join(binDir, "larkit"),
+      shims: written,
+      bin_dir: binDir,
+      on_path: binDirOnPath(binDir),
+      status: "linked",
+      version,
+    };
+  }
+
+  const packageRoot = path.join(CLI_INSTALL_DIR, "node_modules", "larkit");
+  const entry = path.join(packageRoot, "bin", "larkit.js");
+  const installed = readJson(path.join(packageRoot, "package.json"), {});
+  let status = "present";
+  if (force || !fs.existsSync(entry) || (version && installed.version !== version)) {
+    ensureDir(CLI_INSTALL_DIR);
+    const manifest = path.join(CLI_INSTALL_DIR, "package.json");
+    if (!fs.existsSync(manifest)) {
+      writeJson(manifest, { name: "larkit-cli-install", private: true });
+    }
+    const target = source || `larkit@${version}`;
+    runNpm([
+      "install",
+      "--prefix",
+      CLI_INSTALL_DIR,
+      "--no-save",
+      "--no-package-lock",
+      "--no-audit",
+      "--no-fund",
+      "--loglevel=error",
+      target,
+    ]);
+    if (!fs.existsSync(entry)) {
+      throw new Error(
+        `npm installed ${target} but ${displayPath(entry)} is missing; check that the package bin entry is correct`,
+      );
+    }
+    status = "installed";
+  }
+  const written = writeShims(entry, binDir);
+  return {
+    mode: "local-prefix",
+    entry,
+    shim: path.join(binDir, "larkit"),
+    shims: written,
+    bin_dir: binDir,
+    on_path: binDirOnPath(binDir),
+    status,
+    version: readJson(path.join(packageRoot, "package.json"), {}).version || version,
+  };
+}
+
+export function mcpServerCommand() {
+  const shim = path.join(BIN_DIR, "larkit-mcp");
+  if (fs.existsSync(shim)) return shim;
+  return "larkit-mcp";
+}

package/src/bootstrap/download.js

@@ -0,0 +1,182 @@
+import fs from "node:fs";
+import path from "node:path";
+import { Readable, Transform } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { createHash } from "node:crypto";
+import { fileURLToPath } from "node:url";
+import {
+  ensureDir,
+  fileSizeMiB,
+  log,
+  readJson,
+} from "../shared/util.js";
+import { PKG_ROOT } from "../shared/paths.js";
+
+const VERSION = readJson(path.join(PKG_ROOT, "package.json"), {}).version || "0.0.0";
+
+export function isHttpUrl(value) {
+  return /^https?:\/\//i.test(String(value));
+}
+
+export function isFileUrl(value) {
+  return /^file:\/\//i.test(String(value));
+}
+
+export async function sha256File(file, onProgress) {
+  const hash = createHash("sha256");
+  let bytes = 0;
+  for await (const chunk of fs.createReadStream(file)) {
+    hash.update(chunk);
+    bytes += chunk.length;
+    onProgress?.(bytes);
+  }
+  return { sha256: hash.digest("hex"), bytes };
+}
+
+export function sha256FileSync(file) {
+  return createHash("sha256").update(fs.readFileSync(file)).digest("hex");
+}
+
+async function finalize(partFile, destFile, { expectedSha256, expectedBytes } = {}) {
+  const stat = fs.statSync(partFile);
+  if (expectedBytes && stat.size !== expectedBytes) {
+    throw new Error(
+      `download size mismatch: got ${stat.size} bytes, expected ${expectedBytes}`,
+    );
+  }
+  if (expectedSha256) {
+    const { sha256 } = await sha256File(partFile);
+    if (sha256 !== expectedSha256) {
+      throw new Error(
+        `download checksum mismatch: got ${sha256}, expected ${expectedSha256}`,
+      );
+    }
+  }
+  fs.rmSync(destFile, { force: true });
+  fs.renameSync(partFile, destFile);
+  return { file: destFile, bytes: stat.size };
+}
+
+/** Copy a local file with the same atomic/verified semantics as a download. */
+export async function copyLocalFile(source, dest, options = {}) {
+  const from = isFileUrl(source) ? fileURLToPath(source) : path.resolve(source);
+  if (!fs.existsSync(from)) throw new Error(`file not found: ${source}`);
+  ensureDir(path.dirname(dest));
+  const part = `${dest}.part`;
+  await pipeline(fs.createReadStream(from), fs.createWriteStream(part));
+  return finalize(part, dest, options);
+}
+
+/**
+ * Download (or copy) with resume + sha256 verification.  A `.part` file is
+ * reused when the server supports Range requests, so interrupted installs can
+ * continue instead of restarting a multi-hundred-MB download.
+ */
+export async function downloadFile(source, dest, options = {}) {
+  const {
+    expectedSha256,
+    expectedBytes,
+    onProgress,
+    quiet = false,
+    label = path.basename(dest),
+  } = options;
+
+  if (!isHttpUrl(source)) {
+    if (!quiet) log(`[download] copy ${path.basename(source)} -> ${dest}`);
+    return copyLocalFile(source, dest, { expectedSha256, expectedBytes });
+  }
+
+  ensureDir(path.dirname(dest));
+  const part = `${dest}.part`;
+  let start = fs.existsSync(part) ? fs.statSync(part).size : 0;
+  let response;
+  let lastError;
+
+  for (let attempt = 0; attempt < 2; attempt++) {
+    const headers = {
+      "user-agent": `larkit/${VERSION}`,
+      "accept-encoding": "identity",
+    };
+    if (start > 0) headers.range = `bytes=${start}-`;
+    try {
+      response = await fetch(source, { headers, redirect: "follow" });
+    } catch (error) {
+      lastError = error;
+      await new Promise((resolve) => setTimeout(resolve, 800));
+      continue;
+    }
+    if (response.status === 416 && start > 0) {
+      // The .part file is already complete (or larger). Hash it.
+      const result = await finalize(part, dest, { expectedSha256, expectedBytes });
+      onProgress?.(result.bytes, result.bytes);
+      return result;
+    }
+    if (!response.ok && response.status !== 206) {
+      throw new Error(`HTTP ${response.status} for ${source}`);
+    }
+    break;
+  }
+  if (!response) {
+    throw new Error(`download failed: ${lastError?.message || source}`);
+  }
+
+  const resuming = start > 0 && response.status === 206;
+  if (start > 0 && !resuming) {
+    start = 0;
+    fs.rmSync(part, { force: true });
+  }
+  const length = Number(response.headers.get("content-length")) || 0;
+  const total = expectedBytes || (resuming ? start + length : length);
+  if (!quiet) {
+    log(
+      `[download] ${label} ${resuming ? "resume " : ""}${total ? fileSizeMiB(total) : ""}`,
+    );
+  }
+
+  let received = 0;
+  let lastTick = 0;
+  const progress = new Transform({
+    transform(chunk, _encoding, callback) {
+      received += chunk.length;
+      const now = Date.now();
+      if (now - lastTick > 500) {
+        lastTick = now;
+        onProgress?.(start + received, total);
+      }
+      callback(null, chunk);
+    },
+  });
+
+  try {
+    await pipeline(
+      Readable.fromWeb(response.body),
+      progress,
+      fs.createWriteStream(part, { flags: resuming ? "a" : "w" }),
+    );
+  } catch (error) {
+    throw new Error(
+      `download interrupted at ${fileSizeMiB(start + received)}: ${error.message}; rerun to resume`,
+    );
+  }
+  const result = await finalize(part, dest, { expectedSha256, expectedBytes });
+  onProgress?.(result.bytes, result.bytes);
+  return result;
+}
+
+export async function fetchJson(url) {
+  if (!isHttpUrl(url)) {
+    const file = isFileUrl(url) ? fileURLToPath(url) : path.resolve(url);
+    return readJson(file, null);
+  }
+  const response = await fetch(url, {
+    headers: { "user-agent": `larkit/${VERSION}` },
+    redirect: "follow",
+  });
+  if (!response.ok) throw new Error(`HTTP ${response.status} for ${url}`);
+  return response.json();
+}
+
+export function formatPercent(received, total) {
+  if (!total) return `${fileSizeMiB(received)}`;
+  return `${Math.min(100, Math.round((received / total) * 100))}% (${fileSizeMiB(received)}/${fileSizeMiB(total)})`;
+}