docks-kit 0.17.0 → 0.17.2

package/cli/src/engine-native/bun.ts

@@ -1,98 +1,120 @@
-import { mkdtempSync, rmSync } from "node:fs"
-import { tmpdir } from "node:os"
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
 
-import { p, spawnProcess, type AsyncProcessOptions, type AsyncProcessResult } from "./exec"
-import type { Ctx } from "./index"
-import type { EngineServices } from "./services"
-import { hostOs, type HostOs } from "./os"
-import { field } from "./toolchain"
+import { p, spawnProcess, type AsyncProcessOptions, type AsyncProcessResult } from "./exec";
+import type { Ctx } from "./index";
+import type { EngineServices } from "./services";
+import { hostOs, type HostOs } from "./os";
+import { field } from "./toolchain";
 
 export type BunRuntimeState =
   | { readonly kind: "ready"; readonly executable: string }
   | {
-      readonly kind: "deferred"
-      readonly reason: "missing-curl" | "download-failed" | "installer-failed" | "install-failed"
-    }
+      readonly kind: "deferred";
+      readonly reason: "missing-curl" | "download-failed" | "installer-failed" | "install-failed";
+    };
 
 function predictedExecutable(ctx: Ctx, host: HostOs = hostOs()): string {
-  const root = process.env["BUN_INSTALL"] !== undefined && process.env["BUN_INSTALL"] !== ""
-    ? process.env["BUN_INSTALL"]!
-    : p(ctx.home, ".bun")
-  return p(root, "bin", host.bunExecutableName)
+  const root =
+    process.env["BUN_INSTALL"] !== undefined && process.env["BUN_INSTALL"] !== ""
+      ? process.env["BUN_INSTALL"]!
+      : p(ctx.home, ".bun");
+  return p(root, "bin", host.bunExecutableName);
 }
 
 type BunInstallResult =
   | { readonly ok: true }
-  | { readonly ok: false; readonly reason: "download-failed" | "installer-failed"; readonly detail: string }
+  | {
+      readonly ok: false;
+      readonly reason: "download-failed" | "installer-failed";
+      readonly detail: string;
+    };
 
 function processFailure(result: AsyncProcessResult): string {
-  const details = [result.error?.message, result.stderr.trim()].filter((value): value is string => value !== undefined && value !== "")
-  return details.join(": ") || (result.exitCode === null ? "the process ended without an exit code" : `exit code ${result.exitCode}`)
+  const details = [result.error?.message, result.stderr.trim()].filter(
+    (value): value is string => value !== undefined && value !== "",
+  );
+  return (
+    details.join(": ") ||
+    (result.exitCode === null
+      ? "the process ended without an exit code"
+      : `exit code ${result.exitCode}`)
+  );
 }
 
-async function installBun(pin: string, directory: string, host: HostOs = hostOs()): Promise<BunInstallResult> {
-  const options: AsyncProcessOptions = { stdio: ["ignore", "ignore", "pipe"] }
-  const installer = host.bunInstaller(pin, directory)
-  const download = await spawnProcess(installer.download.command, installer.download.args, options)
+async function installBun(
+  pin: string,
+  directory: string,
+  host: HostOs = hostOs(),
+): Promise<BunInstallResult> {
+  const options: AsyncProcessOptions = { stdio: ["ignore", "ignore", "pipe"] };
+  const installer = host.bunInstaller(pin, directory);
+  const download = await spawnProcess(installer.download.command, installer.download.args, options);
   if (download.error !== undefined || download.exitCode !== 0) {
-    return { ok: false, reason: "download-failed", detail: processFailure(download) }
+    return { ok: false, reason: "download-failed", detail: processFailure(download) };
   }
-  const install = await spawnProcess(installer.run.command, installer.run.args, options)
+  const install = await spawnProcess(installer.run.command, installer.run.args, options);
   if (install.error !== undefined || install.exitCode !== 0) {
-    return { ok: false, reason: "installer-failed", detail: processFailure(install) }
+    return { ok: false, reason: "installer-failed", detail: processFailure(install) };
   }
-  return { ok: true }
+  return { ok: true };
 }
 
 export function bunBootstrap(ctx: Ctx, services: EngineServices): Promise<BunRuntimeState> {
-  if (ctx.bunRuntime !== undefined) return ctx.bunRuntime
-  const pending = runBunBootstrap(ctx, services)
-  ctx.bunRuntime = pending
-  return pending
+  if (ctx.bunRuntime !== undefined) return ctx.bunRuntime;
+  const pending = runBunBootstrap(ctx, services);
+  ctx.bunRuntime = pending;
+  return pending;
 }
 
 async function runBunBootstrap(ctx: Ctx, services: EngineServices): Promise<BunRuntimeState> {
-  const host = hostOs(services.platform.name())
+  const host = hostOs(services.platform.name());
 
-  const existing = await services.deps.path("bun")
-  if (existing !== "") return { kind: "ready", executable: existing }
+  const existing = await services.deps.path("bun");
+  if (existing !== "") return { kind: "ready", executable: existing };
 
-  const pin = field("bun", "verified")
+  const pin = field("bun", "verified");
   if (pin === "") {
-    services.logger.warn("Bun bootstrap aborted — SoT/toolchain.json has no verified Bun pin")
-    return { kind: "deferred", reason: "install-failed" }
+    services.logger.warn("Bun bootstrap aborted — SoT/toolchain.json has no verified Bun pin");
+    return { kind: "deferred", reason: "install-failed" };
   }
   if (services.deps.probe("curl").state === "missing") {
-    services.deps.warnMissing("curl", services.logger, "cannot bootstrap Bun; install Bun manually, then re-run sync")
-    return { kind: "deferred", reason: "missing-curl" }
+    services.deps.warnMissing(
+      "curl",
+      services.logger,
+      "cannot bootstrap Bun; install Bun manually, then re-run sync",
+    );
+    return { kind: "deferred", reason: "missing-curl" };
   }
   if (ctx.dryRun) {
-    const executable = predictedExecutable(ctx, host)
-    services.logger.echo(`[dry-run] install Bun ${pin} (kit-verified) -> ${executable}`)
-    return { kind: "ready", executable }
+    const executable = predictedExecutable(ctx, host);
+    services.logger.echo(`[dry-run] install Bun ${pin} (kit-verified) -> ${executable}`);
+    return { kind: "ready", executable };
   }
-  services.logger.warn(`Bun not found — installing Bun ${pin} (kit-verified)...`)
-  const temporaryDir = mkdtempSync(p(tmpdir(), "docks-kit-bun-"))
-  let result: BunInstallResult
+  services.logger.warn(`Bun not found — installing Bun ${pin} (kit-verified)...`);
+  const temporaryDir = mkdtempSync(p(tmpdir(), "docks-kit-bun-"));
+  let result: BunInstallResult;
   try {
-    result = await installBun(pin, temporaryDir, host)
+    result = await installBun(pin, temporaryDir, host);
   } finally {
-    rmSync(temporaryDir, { recursive: true, force: true })
+    rmSync(temporaryDir, { recursive: true, force: true });
   }
   if (!result.ok) {
-    const stage = result.reason === "download-failed" ? "installer download" : "installer"
+    const stage = result.reason === "download-failed" ? "installer download" : "installer";
     services.logger.warn(
-      `Bun ${stage} failed (${result.detail}). Install Bun manually from https://bun.sh/docs/installation, then re-run sync.`
-    )
-    return { kind: "deferred", reason: result.reason }
+      `Bun ${stage} failed (${result.detail}). Install Bun manually from https://bun.sh/docs/installation, then re-run sync.`,
+    );
+    return { kind: "deferred", reason: result.reason };
   }
 
-  const installed = await services.deps.path("bun")
+  const installed = await services.deps.path("bun");
   if (installed === "") {
-    services.logger.warn("Bun install failed. Install manually from https://bun.sh/docs/installation, then re-run sync.")
-    return { kind: "deferred", reason: "install-failed" }
+    services.logger.warn(
+      "Bun install failed. Install manually from https://bun.sh/docs/installation, then re-run sync.",
+    );
+    return { kind: "deferred", reason: "install-failed" };
   }
-  const version = await services.deps.version("bun")
-  services.logger.change(`Bun installed (${version !== "" ? version : "version unknown"})`)
-  return { kind: "ready", executable: installed }
+  const version = await services.deps.version("bun");
+  services.logger.change(`Bun installed (${version !== "" ? version : "version unknown"})`);
+  return { kind: "ready", executable: installed };
 }

package/cli/src/engine-native/claudeLsp.ts

@@ -0,0 +1,154 @@
+/**
+ * EngineNative `sync claude` LSP server probes and installs. The php-lsp,
+ * typescript-lsp, and rust-analyzer-lsp plugins are no-ops without their
+ * server binaries, so this pass installs the missing ones. Message strings
+ * and spawned argv are part of the contract.
+ */
+import { spawnProcess } from "./exec";
+import type { Ctx } from "./index";
+import { isObject, parseJson } from "./jq";
+import { belowFloor, field, installedVersion } from "./toolchain";
+import { payloadText } from "../payload";
+
+function lspPkg(ctx: Ctx, tool: string, pkg: string): string | undefined {
+  const version = field(tool, "verified");
+  if (version !== "") return `${pkg}@${version}`;
+  ctx.services.logger.warn(
+    `Skipping ${pkg} install: ${tool} has no verified version in SoT/toolchain.json`,
+  );
+  return undefined;
+}
+
+/**
+ * npm treats a package's `engines` field as advisory unless the host opted
+ * into engine-strict, so installing typescript-language-server 6 on an older
+ * Node succeeds and then fails at every startup. Report the host Node version
+ * when it is too old, and the empty string when the install is safe.
+ */
+async function nodeBelowServerFloor(ctx: Ctx): Promise<string> {
+  const floor = field("node", "floor");
+  if (floor === "") return "";
+  const installed = await installedVersion(ctx, "node");
+  return belowFloor(installed, floor) ? installed : "";
+}
+
+/** npm-global channel: intelephense, typescript-language-server, typescript. */
+async function installNpmServers(ctx: Ctx, missing: ReadonlyArray<string>): Promise<void> {
+  const { change, clearProgress, echo, progress, verbose, warn } = ctx.services.logger;
+  if (missing.length === 0) return;
+  const specs = missing.join(" ");
+  if (ctx.dryRun) {
+    echo(`[dry-run] would install: npm install -g ${specs}`);
+    return;
+  }
+
+  if (ctx.services.deps.probe("npm").state === "missing") {
+    ctx.services.deps.warnMissing(
+      "npm",
+      ctx.services.logger,
+      `cannot install LSP servers (${specs}); the php-lsp/typescript-lsp plugins stay no-ops`,
+    );
+    return;
+  }
+
+  verbose(`Installing LSP servers via npm: ${specs}...`);
+  progress(`Installing LSP servers via npm: ${specs}...`);
+  const installResult = await spawnProcess("npm", ["install", "-g", ...missing], {
+    stdio: "ignore",
+  });
+  clearProgress();
+  if (installResult.exitCode === 0) {
+    change(`LSP servers installed (${specs})`);
+    ctx.nextStepTriggers.claudeRestart = true;
+  } else {
+    warn(`npm install -g ${specs} failed. Try manually: npm install -g ${specs}`);
+  }
+}
+
+/**
+ * rustup channel: rust-analyzer ships no npm package, and upstream's first
+ * recommendation is the rustup component, which tracks the toolchain the host
+ * already trusts. The component version therefore follows that toolchain, so
+ * the manifest row carries no verified pin - the stance bubblewrap already
+ * takes for a distro package.
+ */
+async function installRustAnalyzer(ctx: Ctx): Promise<void> {
+  const { change, clearProgress, echo, progress, verbose, warn } = ctx.services.logger;
+  if (ctx.dryRun) {
+    echo("[dry-run] would install: rustup component add rust-analyzer");
+    return;
+  }
+  verbose("Installing rust-analyzer via rustup...");
+  progress("Installing rust-analyzer via rustup...");
+  const result = await spawnProcess("rustup", ["component", "add", "rust-analyzer"], {
+    stdio: "ignore",
+  });
+  clearProgress();
+  if (result.exitCode === 0) {
+    change("LSP server installed (rust-analyzer via rustup)");
+    ctx.nextStepTriggers.claudeRestart = true;
+  } else {
+    warn(
+      "rustup component add rust-analyzer failed. Try manually: rustup component add rust-analyzer",
+    );
+  }
+}
+
+export async function syncLspServers(ctx: Ctx): Promise<void> {
+  const { echo, verbose, warn } = ctx.services.logger;
+  const sot = parseJson(payloadText("SoT/.claude/settings.json"));
+  const enabled =
+    sot !== undefined && isObject(sot) && isObject(sot["enabledPlugins"])
+      ? sot["enabledPlugins"]
+      : undefined;
+  if (enabled === undefined) return;
+  const enables = (plugin: string): boolean =>
+    Object.prototype.hasOwnProperty.call(enabled, plugin);
+  const hasPhp = enables("php-lsp@claude-plugins-official");
+  const hasTs = enables("typescript-lsp@claude-plugins-official");
+  const hasRust = enables("rust-analyzer-lsp@claude-plugins-official");
+  if (!hasPhp && !hasTs && !hasRust) return;
+
+  const phpMissing = hasPhp && ctx.services.deps.probe("intelephense").state === "missing";
+  const tsServerMissing =
+    hasTs && ctx.services.deps.probe("typescript-language-server").state === "missing";
+  const tscMissing = hasTs && ctx.services.deps.probe("tsc").state === "missing";
+  const rustMissing = hasRust && ctx.services.deps.probe("rust-analyzer").state === "missing";
+  // A host without rustup does no Rust work, so the plugin has nothing to
+  // serve there. Installing is impossible and warning every sync would name no
+  // action the user wants, so that host is not counted as missing a tool.
+  const rustInstallable = rustMissing && ctx.services.deps.probe("rustup").state === "present";
+  if (rustMissing && !rustInstallable) {
+    verbose(
+      "Skipping rust-analyzer: rustup is not installed, so the rust-analyzer-lsp plugin stays a no-op",
+    );
+  }
+
+  const missingToolCount =
+    Number(phpMissing) + Number(tsServerMissing) + Number(tscMissing) + Number(rustInstallable);
+  if (missingToolCount === 0) {
+    if (ctx.dryRun) {
+      echo("[dry-run] LSP server binaries present");
+    } else {
+      verbose("LSP server binaries present");
+    }
+    return;
+  }
+
+  const blockingNode = tsServerMissing ? await nodeBelowServerFloor(ctx) : "";
+  if (blockingNode !== "") {
+    warn(
+      `Skipping typescript-language-server install: Node ${blockingNode} is older than the ${field("node", "floor")} that version requires. Upgrade Node, then re-run sync.`,
+    );
+  }
+  const missing = [
+    phpMissing ? lspPkg(ctx, "intelephense", "intelephense") : undefined,
+    tsServerMissing && blockingNode === ""
+      ? lspPkg(ctx, "typescript-language-server", "typescript-language-server")
+      : undefined,
+    tscMissing ? lspPkg(ctx, "tsc", "typescript") : undefined,
+  ].filter((spec): spec is string => spec !== undefined);
+
+  await installNpmServers(ctx, missing);
+  if (rustInstallable) await installRustAnalyzer(ctx);
+}

package/cli/src/engine-native/claudeOptionalPlugins.ts

@@ -0,0 +1,113 @@
+/**
+ * EngineNative `sync claude` optional-plugin opt-in pass (--claude-plugin).
+ * Split from claudePluginPasses along the opt-in axis; message strings
+ * and spawned argv are part of the golden-tested contract.
+ */
+import { p } from "./exec";
+import { recordFailure } from "./failures";
+import type { Ctx } from "./index";
+import { isObject, readJsonFile } from "./jq";
+import type { JsonObject } from "./sharedTypes";
+import { cli, pluginUserScopeInstalled } from "./claudePluginPasses";
+
+async function enableOptionalPlugin(
+  ctx: Ctx,
+  claudeDir: string,
+  pluginId: string,
+  marketplaceRepo: string,
+): Promise<boolean> {
+  const { change, clearProgress, progress, verbose } = ctx.services.logger;
+  const installedPlugins = p(claudeDir, "plugins", "installed_plugins.json");
+  const knownMarketplaces = p(claudeDir, "plugins", "known_marketplaces.json");
+  const mpName = pluginId.slice(pluginId.lastIndexOf("@") + 1);
+
+  let marketplaceAdded = false;
+  if (marketplaceRepo !== "") {
+    const known = readJsonFile(knownMarketplaces);
+    const has =
+      known !== undefined &&
+      isObject(known) &&
+      known[mpName] !== undefined &&
+      known[mpName] !== null &&
+      known[mpName] !== false;
+    if (!has) {
+      if (!(await cli(["plugin", "marketplace", "add", marketplaceRepo])).ok) {
+        recordFailure(ctx, `Failed to add marketplace ${marketplaceRepo} for ${pluginId}`);
+        return false;
+      }
+      marketplaceAdded = true;
+    }
+  }
+
+  const wasInstalled = pluginUserScopeInstalled(installedPlugins, pluginId);
+  if (!wasInstalled) {
+    progress(`Installing plugin ${pluginId}...`);
+    const installResult = await cli(["plugin", "install", pluginId]);
+    clearProgress();
+    if (!installResult.ok) {
+      if (marketplaceAdded)
+        change(
+          `Optional plugin ${pluginId}: marketplace added (install failed — will retry next sync)`,
+        );
+      recordFailure(ctx, `Failed to install optional plugin ${pluginId}`);
+      return marketplaceAdded;
+    }
+  }
+
+  const settingsDoc = readJsonFile(p(claudeDir, "settings.json"));
+  const wasEnabled =
+    settingsDoc !== undefined && isObject(settingsDoc) && isObject(settingsDoc["enabledPlugins"])
+      ? (settingsDoc["enabledPlugins"] as JsonObject)[pluginId] === true
+      : false;
+
+  if (!(await cli(["plugin", "enable", pluginId])).ok) {
+    if (marketplaceAdded || !wasInstalled)
+      change(`Optional plugin ${pluginId}: installed (enable failed — will retry next sync)`);
+    recordFailure(ctx, `Failed to enable optional plugin ${pluginId}`);
+    return marketplaceAdded || !wasInstalled;
+  }
+  const changed = marketplaceAdded || !wasInstalled || !wasEnabled;
+  if (changed) change(`Optional plugin opted in: ${pluginId}`);
+  else verbose(`Optional plugin already opted in: ${pluginId} (enable re-asserted)`);
+  return changed;
+}
+
+export async function syncOptionalPlugins(ctx: Ctx, claudeDir: string): Promise<void> {
+  const { echo, warn } = ctx.services.logger;
+  if (ctx.claudePlugins.length === 0) return;
+
+  if (ctx.dryRun) {
+    if (ctx.claudePlugins.includes("supabase")) {
+      echo(
+        "[dry-run] (--claude-plugin=supabase) install + enable supabase@claude-plugins-official in deployed settings",
+      );
+    }
+    if (ctx.claudePlugins.includes("n8n")) {
+      echo(
+        "[dry-run] (--claude-plugin=n8n) add czlonkowski/n8n-skills marketplace + install + enable n8n-mcp-skills@n8n-mcp-skills",
+      );
+    }
+    return;
+  }
+
+  if (ctx.services.deps.probe("claude").state === "missing") {
+    warn("claude CLI not in PATH — cannot opt in optional plugins (--claude-plugin)");
+    return;
+  }
+
+  if (ctx.claudePlugins.includes("supabase")) {
+    if (await enableOptionalPlugin(ctx, claudeDir, "supabase@claude-plugins-official", ""))
+      ctx.nextStepTriggers.claudePlugins = true;
+  }
+  if (ctx.claudePlugins.includes("n8n")) {
+    if (
+      await enableOptionalPlugin(
+        ctx,
+        claudeDir,
+        "n8n-mcp-skills@n8n-mcp-skills",
+        "czlonkowski/n8n-skills",
+      )
+    )
+      ctx.nextStepTriggers.claudePlugins = true;
+  }
+}