local-commander-agent 0.3.2

package/README.md

@@ -0,0 +1,44 @@
+# Local Commander Agent
+
+Windows 11 x64 bootstrap package for Local Commander.
+
+## Install and pair
+
+```powershell
+npx local-commander-agent@latest
+```
+
+The bootstrap installs the self-contained Local Commander runtime under the current user's `%LOCALAPPDATA%LocalCommander` directory, opens the browser pairing flow, lets the user choose a workspace, enables per-user autostart and starts the background agent.
+
+Node.js 20+ is required only to run npm/npx. The installed agent uses its bundled Node runtime.
+
+## Management
+
+```powershell
+npx local-commander-agent@latest status
+npx local-commander-agent@latest start
+npx local-commander-agent@latest stop
+npx local-commander-agent@latest restart
+npx local-commander-agent@latest update
+npx local-commander-agent@latest approve-workspace
+npx local-commander-agent@latest uninstall
+```
+
+To also remove the protected Local Commander enrollment/state during uninstall:
+
+```powershell
+npx local-commander-agent@latest uninstall --purge-state
+```
+
+Uninstall never removes user project files.
+
+## Control plane
+
+The package defaults to `https://localcmd.cloudpub.ru`. A staging or self-hosted control plane can be selected only at first pairing with:
+
+```powershell
+$env:LC_CONTROL_PLANE_ORIGIN="https://your-control-plane.example"
+npx local-commander-agent@latest
+```
+
+The enrollment stores the selected origin for later relay connections.

package/bin/localcommander.mjs

@@ -0,0 +1,425 @@
+#!/usr/bin/env node
+import { constants as fsConstants } from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { randomBytes } from "node:crypto";
+import { spawn, spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const PACKAGE_META = JSON.parse(await fs.readFile(path.join(PACKAGE_ROOT, "package.json"), "utf8"));
+const VERSION = String(PACKAGE_META.version || "");
+const DEFAULT_ORIGIN = String(PACKAGE_META.localCommander?.controlPlaneOrigin || "");
+const RUNTIME_FILES = ["LocalCommanderAgent.exe", "OwnerBridge.exe", "JobHost.exe", "agent.mjs", "node.exe", "NODE-LICENSE.txt"];
+const RUN_KEY = "HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Run";
+const RUN_VALUE = "LocalCommanderAgent";
+const MAX_STDIO = 64 * 1024;
+
+function fail(code) {
+  const error = new Error(code);
+  error.code = code;
+  throw error;
+}
+function requireWindows() {
+  if (process.platform !== "win32" || process.arch !== "x64") fail("WINDOWS_X64_REQUIRED");
+}
+function appDataRoot() {
+  const value = process.env.LOCALAPPDATA;
+  if (!value || !path.isAbsolute(value) || /[\u0000-\u001f]/u.test(value)) fail("APP_DATA_MISSING");
+  return path.join(value, "LocalCommander");
+}
+function stateDirectory() {
+  const override = process.env.LC_AGENT_STATE_DIR;
+  if (override) {
+    if (!path.isAbsolute(override) || /[\u0000-\u001f]/u.test(override)) fail("STATE_DIR_INVALID");
+    return path.resolve(override);
+  }
+  return path.join(appDataRoot(), "Agent");
+}
+function versionsDirectory() {
+  return path.join(appDataRoot(), "Versions");
+}
+function currentPath() {
+  return path.join(appDataRoot(), "current.json");
+}
+function runtimeSource() {
+  return path.join(PACKAGE_ROOT, "runtime");
+}
+function processFile() {
+  return path.join(stateDirectory(), "agent-process.json");
+}
+function under(parent, child) {
+  const rel = path.relative(parent, child);
+  return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
+}
+function boundedText(value) {
+  const text = String(value ?? "");
+  return text.length > MAX_STDIO ? text.slice(0, MAX_STDIO) : text;
+}
+async function regular(file) {
+  const stat = await fs.lstat(file);
+  if (!stat.isFile() || stat.isSymbolicLink() || stat.size < 1) fail("PACKAGE_RUNTIME_INVALID");
+  return stat;
+}
+async function ensurePlainDirectory(dir) {
+  await fs.mkdir(dir, { recursive: true, mode: 0o700 });
+  const stat = await fs.lstat(dir);
+  if (!stat.isDirectory() || stat.isSymbolicLink()) fail("INSTALL_DIRECTORY_INVALID");
+  return dir;
+}
+async function ensureInstallDirectories() {
+  const root = await ensurePlainDirectory(appDataRoot());
+  const versions = await ensurePlainDirectory(versionsDirectory());
+  if (!under(root, versions)) fail("INSTALL_DIRECTORY_INVALID");
+  return { root, versions };
+}
+async function runtimeValid(dir) {
+  try {
+    for (const name of RUNTIME_FILES) await regular(path.join(dir, name));
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function writeJsonAtomic(file, value) {
+  await ensurePlainDirectory(path.dirname(file));
+  const existing = await fs.lstat(file).catch(error => error?.code === "ENOENT" ? null : Promise.reject(error));
+  if (existing && (!existing.isFile() || existing.isSymbolicLink())) fail("INSTALL_STATE_INVALID");
+  const temp = file + "." + process.pid + "." + randomBytes(6).toString("hex") + ".tmp";
+  await fs.writeFile(temp, JSON.stringify(value, null, 2) + "\n", { flag: "wx", mode: 0o600 });
+  try {
+    await fs.rename(temp, file);
+  } catch (error) {
+    await fs.rm(temp, { force: true });
+    throw error;
+  }
+}
+async function readCurrent() {
+  try {
+    const current = currentPath();
+    const stat = await fs.lstat(current);
+    if (!stat.isFile() || stat.isSymbolicLink()) fail("INSTALL_STATE_INVALID");
+    const raw = JSON.parse(await fs.readFile(current, "utf8"));
+    if (!raw || typeof raw !== "object" || typeof raw.version !== "string" || typeof raw.runtimeDir !== "string") fail("INSTALL_STATE_INVALID");
+    const dir = path.resolve(raw.runtimeDir);
+    if (!under(versionsDirectory(), dir) || !(await runtimeValid(dir))) fail("INSTALL_STATE_INVALID");
+    return { version: raw.version, runtimeDir: dir };
+  } catch (error) {
+    if (error && error.code === "ENOENT") return null;
+    throw error;
+  }
+}
+async function copyRuntime() {
+  const source = runtimeSource();
+  if (!(await runtimeValid(source))) fail("PACKAGE_RUNTIME_MISSING");
+  const { versions } = await ensureInstallDirectories();
+  const target = path.join(versions, VERSION);
+  if (await runtimeValid(target)) {
+    await writeJsonAtomic(currentPath(), { version: VERSION, runtimeDir: target });
+    return target;
+  }
+  const targetStat = await fs.lstat(target).catch(error => error?.code === "ENOENT" ? null : Promise.reject(error));
+  if (targetStat) {
+    if (!targetStat.isDirectory() || targetStat.isSymbolicLink() || !under(versions, target)) fail("INSTALL_TARGET_INVALID");
+    await fs.rm(target, { recursive: true, force: true });
+  }
+  const temp = path.join(versions, "." + VERSION + "." + process.pid + "." + randomBytes(6).toString("hex"));
+  await fs.mkdir(temp, { recursive: false, mode: 0o700 });
+  try {
+    for (const name of RUNTIME_FILES) {
+      const sourceFile = path.join(source, name);
+      const sourceStat = await regular(sourceFile);
+      const destination = path.join(temp, name);
+      await fs.copyFile(sourceFile, destination, fsConstants.COPYFILE_EXCL);
+      const copied = await regular(destination);
+      if (copied.size !== sourceStat.size) fail("PACKAGE_COPY_INVALID");
+    }
+    try {
+      await fs.rename(temp, target);
+    } catch (error) {
+      if (!(await runtimeValid(target))) throw error;
+      await fs.rm(temp, { recursive: true, force: true });
+    }
+    await writeJsonAtomic(currentPath(), { version: VERSION, runtimeDir: target });
+    return target;
+  } catch (error) {
+    await fs.rm(temp, { recursive: true, force: true });
+    throw error;
+  }
+}
+function runReg(args, allowMissing = false) {
+  const result = spawnSync("reg.exe", args, { windowsHide: true, encoding: "utf8", timeout: 10_000 });
+  if (result.error) fail("AUTOSTART_COMMAND_FAILED");
+  if (result.status !== 0 && !(allowMissing && result.status === 1)) fail("AUTOSTART_COMMAND_FAILED");
+}
+function registerAutostart(runtimeDir) {
+  const exe = path.join(runtimeDir, "LocalCommanderAgent.exe");
+  if (exe.includes('"')) fail("INSTALL_PATH_INVALID");
+  runReg(["ADD", RUN_KEY, "/v", RUN_VALUE, "/t", "REG_SZ", "/d", '"' + exe + '" run', "/f"]);
+}
+function removeAutostart() {
+  runReg(["DELETE", RUN_KEY, "/v", RUN_VALUE, "/f"], true);
+}
+function agentEnv() {
+  const env = { ...process.env, LC_AGENT_STATE_DIR: stateDirectory() };
+  delete env.NODE_OPTIONS;
+  delete env.NODE_PATH;
+  return env;
+}
+function agentExe(runtimeDir) {
+  return path.join(runtimeDir, "LocalCommanderAgent.exe");
+}
+function execAgent(runtimeDir, args, timeout = 30_000) {
+  const result = spawnSync(agentExe(runtimeDir), args, {
+    windowsHide: true,
+    encoding: "utf8",
+    timeout,
+    env: agentEnv()
+  });
+  if (result.error) fail("AGENT_COMMAND_FAILED");
+  return { status: result.status ?? -1, stdout: boundedText(result.stdout), stderr: boundedText(result.stderr) };
+}
+function openBrowser(url) {
+  let parsed;
+  try { parsed = new URL(url); } catch { fail("PAIRING_URL_INVALID"); }
+  if (parsed.protocol !== "https:" && !(parsed.protocol === "http:" && ["localhost", "127.0.0.1", "[::1]"].includes(parsed.hostname))) fail("PAIRING_URL_INVALID");
+  const child = spawn("rundll32.exe", ["url.dll,FileProtocolHandler", parsed.toString()], { detached: true, windowsHide: true, stdio: "ignore" });
+  child.unref();
+}
+async function identityStatus(runtimeDir) {
+  const result = execAgent(runtimeDir, ["identity-status"], 15_000);
+  if (result.status !== 0) fail(result.stderr.trim() || "IDENTITY_STATUS_FAILED");
+  try {
+    const parsed = JSON.parse(result.stdout.trim());
+    return { paired: parsed.paired === true, accountEmail: typeof parsed.accountEmail === "string" ? parsed.accountEmail : null, deviceId: typeof parsed.deviceId === "string" ? parsed.deviceId : null };
+  } catch { fail("IDENTITY_STATUS_INVALID"); }
+}
+async function pair(runtimeDir) {
+  const origin = process.env.LC_CONTROL_PLANE_ORIGIN || DEFAULT_ORIGIN;
+  if (!origin) fail("CONTROL_PLANE_ORIGIN_MISSING");
+  const child = spawn(agentExe(runtimeDir), ["pair"], {
+    windowsHide: true,
+    env: { ...agentEnv(), LC_CONTROL_PLANE_ORIGIN: origin },
+    stdio: ["ignore", "pipe", "pipe"]
+  });
+  let stdout = "", stderr = "", opened = false;
+  child.stdout.setEncoding("utf8");
+  child.stderr.setEncoding("utf8");
+  child.stdout.on("data", chunk => {
+    stdout = boundedText(stdout + chunk);
+    if (opened) return;
+    const lineEnd = stdout.indexOf("\n");
+    if (lineEnd < 0) return;
+    const line = stdout.slice(0, lineEnd).trim();
+    try {
+      const begin = JSON.parse(line);
+      if (typeof begin.approvalUrl !== "string" || typeof begin.confirmationCode !== "string") fail("PAIRING_RESPONSE_INVALID");
+      opened = true;
+      process.stdout.write("Pairing code: " + begin.confirmationCode + "\n");
+      process.stdout.write("Opening: " + begin.approvalUrl + "\n");
+      openBrowser(begin.approvalUrl);
+    } catch {
+      child.kill();
+    }
+  });
+  child.stderr.on("data", chunk => { stderr = boundedText(stderr + chunk); });
+  const exitCode = await new Promise((resolve, reject) => {
+    child.once("error", reject);
+    child.once("exit", code => resolve(code ?? -1));
+  }).catch(() => -1);
+  if (exitCode !== 0) fail(stderr.trim() || "PAIRING_FAILED");
+  if (!opened) fail("PAIRING_RESPONSE_INVALID");
+  process.stdout.write("Device paired.\n");
+}
+async function approveWorkspace(runtimeDir) {
+  const result = execAgent(runtimeDir, ["approve-workspace"], 180_000);
+  if (result.status !== 0) fail(result.stderr.trim() || "WORKSPACE_APPROVAL_FAILED");
+  process.stdout.write(result.stdout || "Workspace selection finished.\n");
+}
+function pidAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try { process.kill(pid, 0); return true; }
+  catch (error) { return error && error.code === "EPERM"; }
+}
+async function readProcessRecord() {
+  try {
+    const parsed = JSON.parse(await fs.readFile(processFile(), "utf8"));
+    if (!parsed || typeof parsed !== "object" || !Number.isInteger(parsed.pid) || parsed.pid <= 0 || typeof parsed.runtimeDir !== "string") return null;
+    const runtimeDir = path.resolve(parsed.runtimeDir);
+    if (!under(versionsDirectory(), runtimeDir)) return null;
+    return { pid: parsed.pid, runtimeDir, version: typeof parsed.version === "string" ? parsed.version : null, startedAt: typeof parsed.startedAt === "string" ? parsed.startedAt : null };
+  } catch { return null; }
+}
+async function statusObject() {
+  const current = await readCurrent();
+  const record = await readProcessRecord();
+  const running = !!record && pidAlive(record.pid);
+  if (record && !running) await fs.rm(processFile(), { force: true }).catch(() => {});
+  const identity = current ? await identityStatus(current.runtimeDir).catch(() => ({ paired: false, accountEmail: null, deviceId: null })) : { paired: false, accountEmail: null, deviceId: null };
+  return {
+    installed: !!current,
+    version: current?.version ?? null,
+    running,
+    pid: running ? record.pid : null,
+    paired: identity.paired,
+    accountEmail: identity.accountEmail,
+    deviceId: identity.deviceId,
+    stateDirectory: stateDirectory()
+  };
+}
+async function verifyOwnedProcess(record) {
+  if (!pidAlive(record.pid)) return false;
+  const script = '$p=Get-CimInstance Win32_Process -Filter "ProcessId = ' + record.pid + '"; if($null -eq $p){exit 3}; [Console]::OutputEncoding=[System.Text.Encoding]::UTF8; Write-Output $p.ExecutablePath; Write-Output $p.CommandLine';
+  const result = spawnSync("powershell.exe", ["-NoLogo", "-NoProfile", "-NonInteractive", "-Command", script], { windowsHide: true, encoding: "utf8", timeout: 10_000 });
+  if (result.status === 3) return false;
+  if (result.status !== 0) fail("PROCESS_IDENTITY_CHECK_FAILED");
+  const lines = String(result.stdout || "").split(/\r?\n/u).filter(Boolean);
+  const executable = path.resolve(lines.shift() || "");
+  const expectedNode = path.resolve(record.runtimeDir, "node.exe");
+  const commandLine = lines.join("\n").toLowerCase();
+  return executable.toLowerCase() === expectedNode.toLowerCase() && commandLine.includes(path.join(record.runtimeDir, "agent.mjs").toLowerCase());
+}
+async function stopAgent() {
+  const record = await readProcessRecord();
+  if (!record || !pidAlive(record.pid)) {
+    await fs.rm(processFile(), { force: true }).catch(() => {});
+    return false;
+  }
+  if (!(await verifyOwnedProcess(record))) fail("PROCESS_IDENTITY_MISMATCH");
+  const result = spawnSync("taskkill.exe", ["/PID", String(record.pid), "/T", "/F"], { windowsHide: true, encoding: "utf8", timeout: 15_000 });
+  if (result.status !== 0 && pidAlive(record.pid)) fail("AGENT_STOP_FAILED");
+  for (let i = 0; i < 20 && pidAlive(record.pid); i += 1) await new Promise(resolve => setTimeout(resolve, 100));
+  if (pidAlive(record.pid)) fail("AGENT_STOP_TIMEOUT");
+  await fs.rm(processFile(), { force: true }).catch(() => {});
+  return true;
+}
+async function startAgent() {
+  const current = await readCurrent();
+  if (!current) fail("AGENT_NOT_INSTALLED");
+  const identity = await identityStatus(current.runtimeDir);
+  if (!identity.paired) fail("ENROLLMENT_MISSING");
+  const status = await statusObject();
+  if (status.running) return false;
+  const child = spawn(agentExe(current.runtimeDir), ["run"], { detached: true, windowsHide: true, stdio: "ignore", env: agentEnv() });
+  child.unref();
+  for (let i = 0; i < 40; i += 1) {
+    await new Promise(resolve => setTimeout(resolve, 100));
+    const record = await readProcessRecord();
+    if (record && pidAlive(record.pid)) return true;
+  }
+  fail("AGENT_START_TIMEOUT");
+}
+async function bootstrap({ chooseWorkspace = true } = {}) {
+  const previous = await readCurrent();
+  const target = path.join(versionsDirectory(), VERSION);
+  const running = await readProcessRecord();
+  if (running && pidAlive(running.pid) && path.resolve(running.runtimeDir).toLowerCase() !== path.resolve(target).toLowerCase()) await stopAgent();
+  const runtimeDir = await copyRuntime();
+  const identity = await identityStatus(runtimeDir);
+  if (!identity.paired) await pair(runtimeDir);
+  if (chooseWorkspace) {
+    const list = execAgent(runtimeDir, ["list-workspaces"], 15_000);
+    let count = 0;
+    if (list.status === 0) {
+      try { const parsed = JSON.parse(list.stdout || "[]"); count = Array.isArray(parsed) ? parsed.length : 0; } catch {}
+    }
+    if (count === 0) await approveWorkspace(runtimeDir);
+  }
+  registerAutostart(runtimeDir);
+  await startAgent();
+  if (previous && previous.version !== VERSION) process.stdout.write("Updated Local Commander from " + previous.version + " to " + VERSION + ".\n");
+  process.stdout.write("Local Commander " + VERSION + " is installed and running.\n");
+}
+async function uninstall(purgeState) {
+  await stopAgent();
+  removeAutostart();
+  const versions = versionsDirectory();
+  if (under(appDataRoot(), versions)) await fs.rm(versions, { recursive: true, force: true });
+  await fs.rm(currentPath(), { force: true });
+  if (purgeState) {
+    const state = stateDirectory();
+    const expected = path.join(appDataRoot(), "Agent");
+    if (path.resolve(state).toLowerCase() !== path.resolve(expected).toLowerCase()) fail("CUSTOM_STATE_PURGE_REFUSED");
+    await fs.rm(state, { recursive: true, force: true });
+  }
+  process.stdout.write(purgeState ? "Local Commander removed, including local enrollment state.\n" : "Local Commander removed. Protected enrollment state was preserved.\n");
+}
+function help() {
+  return [
+    "Local Commander agent " + VERSION,
+    "",
+    "Usage:",
+    "  npx local-commander-agent@latest              install/pair/start",
+    "  npx local-commander-agent@latest status       show local state",
+    "  npx local-commander-agent@latest start        start background agent",
+    "  npx local-commander-agent@latest stop         stop background agent",
+    "  npx local-commander-agent@latest restart      restart background agent",
+    "  npx local-commander-agent@latest update       install this package version and restart",
+    "  npx local-commander-agent@latest approve-workspace",
+    "  npx local-commander-agent@latest uninstall [--purge-state]",
+    ""
+  ].join("\n");
+}
+async function main() {
+  requireWindows();
+  if (!/^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/u.test(VERSION)) fail("PACKAGE_VERSION_INVALID");
+  const command = process.argv[2] || "bootstrap";
+  const args = process.argv.slice(3);
+  if (command === "-h" || command === "--help" || command === "help") {
+    process.stdout.write(help());
+    return;
+  }
+  if (command === "bootstrap" || command === "install") {
+    if (args.length) fail("ARGUMENT_INVALID");
+    await bootstrap();
+    return;
+  }
+  if (command === "update") {
+    if (args.length) fail("ARGUMENT_INVALID");
+    await bootstrap({ chooseWorkspace: false });
+    return;
+  }
+  if (command === "start") {
+    if (args.length) fail("ARGUMENT_INVALID");
+    await startAgent();
+    process.stdout.write("Local Commander is running.\n");
+    return;
+  }
+  if (command === "stop") {
+    if (args.length) fail("ARGUMENT_INVALID");
+    const stopped = await stopAgent();
+    process.stdout.write(stopped ? "Local Commander stopped.\n" : "Local Commander was not running.\n");
+    return;
+  }
+  if (command === "restart") {
+    if (args.length) fail("ARGUMENT_INVALID");
+    await stopAgent();
+    await startAgent();
+    process.stdout.write("Local Commander restarted.\n");
+    return;
+  }
+  if (command === "status") {
+    if (args.length) fail("ARGUMENT_INVALID");
+    process.stdout.write(JSON.stringify(await statusObject(), null, 2) + "\n");
+    return;
+  }
+  if (command === "approve-workspace") {
+    if (args.length) fail("ARGUMENT_INVALID");
+    const current = await readCurrent();
+    if (!current) fail("AGENT_NOT_INSTALLED");
+    await approveWorkspace(current.runtimeDir);
+    return;
+  }
+  if (command === "uninstall") {
+    if (args.length > 1 || (args.length === 1 && args[0] !== "--purge-state")) fail("ARGUMENT_INVALID");
+    await uninstall(args[0] === "--purge-state");
+    return;
+  }
+  fail("ARGUMENT_INVALID");
+}
+
+void main().catch(error => {
+  const code = error && typeof error.message === "string" && /^[A-Z0-9_]{1,80}$/u.test(error.message) ? error.message : "LOCAL_COMMANDER_FAILED";
+  process.stderr.write(code + "\n");
+  process.exitCode = 1;
+});

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "local-commander-agent",
+  "version": "0.3.2",
+  "description": "One-command Windows bootstrap for the Local Commander agent.",
+  "type": "module",
+  "bin": {
+    "localcommander": "bin/localcommander.mjs"
+  },
+  "os": [
+    "win32"
+  ],
+  "cpu": [
+    "x64"
+  ],
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "files": [
+    "bin/",
+    "runtime/",
+    "README.md"
+  ],
+  "scripts": {
+    "prepack": "node ../../scripts/build-npm-agent.mjs",
+    "prepublishOnly": "node ../../scripts/verify-npm-agent.mjs"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "mcp",
+    "local",
+    "agent",
+    "chatgpt",
+    "claude",
+    "windows"
+  ],
+  "localCommander": {
+    "controlPlaneOrigin": "https://localcmd.cloudpub.ru"
+  }
+}