@thinkingai/ae-cli 6.1.25 → 6.1.26

package/dist/{chunk-BW7JUDEI.js → chunk-KFNMQTZI.js}

@@ -1,21 +1,105 @@
 import { createRequire as __createRequire } from 'node:module'; const require = __createRequire(import.meta.url);
 import {
   peekCliToken
-} from "./chunk-DU72X2IO.js";
+} from "./chunk-GIK6EDUG.js";
 import {
   getActiveHost,
   getConfigDir,
   isAeSandboxRuntime,
   normalizeUrl
-} from "./chunk-IG3DYEIR.js";
+} from "./chunk-UQ77JXYH.js";
 import {
   logger
-} from "./chunk-YVGXGTD6.js";
+} from "./chunk-WNGFSIOB.js";
 
-// src/core/version-sync.ts
-import { spawnSync } from "child_process";
+// src/core/install-process.ts
+import spawn from "cross-spawn";
 import fs from "fs";
 import path from "path";
+var INSTALL_TIMEOUT_MS = 12e4;
+var SKILLS_TOOL = "skills@1.5.12";
+var defaultInstallRunner = (command, args, timeoutMs) => {
+  const result = spawn.sync(command, args, {
+    encoding: "utf8",
+    maxBuffer: 8 * 1024 * 1024,
+    stdio: ["ignore", "pipe", "pipe"],
+    timeout: timeoutMs,
+    windowsHide: true,
+    env: {
+      ...process.env,
+      DISABLE_TELEMETRY: "1",
+      NO_COLOR: "1",
+      // Select installed clients, not only the AI that launched AE CLI.
+      ...args[1] === SKILLS_TOOL && args[2] === "add" ? { AI_AGENT: "ae-cli" } : {}
+    }
+  });
+  return { ...result, stdout: result.stdout || "", stderr: result.stderr || "" };
+};
+function resolveNodeTool(tool, execPath = process.execPath, platform = process.platform) {
+  const filename = platform === "win32" ? `${tool}.cmd` : tool;
+  const sibling = path.join(path.dirname(execPath), filename);
+  return fs.existsSync(sibling) ? sibling : filename;
+}
+function commandSucceeded(result) {
+  return !result.error && !result.signal && result.status === 0;
+}
+function exactVersion(raw) {
+  const version = raw.trim().replace(/^v/i, "");
+  if (!/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/.test(version)) {
+    throw new Error("Expected an exact version such as 6.0.49 or 6.1.9.");
+  }
+  return version;
+}
+function installHost(raw) {
+  if (!raw) return null;
+  const normalized = normalizeUrl(raw.trim());
+  try {
+    if (raw.includes("://") && !/^https?:\/\//.test(raw.trim())) throw new Error();
+    const url = new URL(normalized);
+    if (!["https:", "http:"].includes(url.protocol) || !url.hostname || url.username || url.password || url.search || url.hash || /[\s'"`$\\<>]/.test(normalized)) throw new Error();
+    return normalized;
+  } catch {
+    throw new Error("Host must be an HTTP(S) URL without credentials, query parameters, or fragments.");
+  }
+}
+function classifyInstallFailure(result) {
+  const text = `${result.error?.message || ""}
+${result.stderr}
+${result.stdout}`;
+  if (result.error?.code === "ETIMEDOUT" || /timed?\s*out|ETIMEDOUT/i.test(text)) return "timeout";
+  if (/EACCES|EPERM|permission denied|access is denied/i.test(text)) return "permission";
+  if (/EAI_AGAIN|ENOTFOUND|ECONNRESET|ECONNREFUSED|network|unable to access|could not resolve|certificate|SSL/i.test(text)) return "network";
+  if (/E404|404 Not Found|no matching version|couldn't find remote ref/i.test(text)) return "package_missing";
+  return "unknown";
+}
+
+// src/core/package-info.ts
+import fs2 from "fs";
+import path2 from "path";
+import { fileURLToPath } from "url";
+function getLocalCliPackageInfo() {
+  let dir = path2.dirname(fileURLToPath(import.meta.url));
+  for (let i = 0; i < 8; i += 1) {
+    const candidate = path2.join(dir, "package.json");
+    try {
+      if (fs2.existsSync(candidate)) {
+        const pkg = JSON.parse(fs2.readFileSync(candidate, "utf8"));
+        if (pkg.name && pkg.version && String(pkg.name).includes("ae-cli")) {
+          return { name: pkg.name, version: pkg.version, root: dir };
+        }
+      }
+    } catch {
+    }
+    const parent = path2.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return { name: "@tant/ae-cli", version: "0.0.0", root: "" };
+}
+
+// src/core/version-sync.ts
+import fs5 from "fs";
+import path5 from "path";
 
 // src/core/update-check.ts
 function shouldSkipUpdateCheck(argv = process.argv) {
@@ -84,8 +168,6 @@ var HISTORICAL_CLUSTER_TO_PUBLIC_PIN = {
 
 // src/core/version-compat.ts
 var OPEN_SOURCE_AE_CLI_PACKAGE = "@thinkingai/ae-cli";
-var OPEN_SOURCE_NPM_REGISTRY = "https://registry.npmjs.org";
-var AE_CLI_SKILLS_REPO = "ThinkingAIAgenticEngine/ae-cli";
 var PUBLISHED_EXTERNAL_VERSIONS = /* @__PURE__ */ new Set([
   "1.0.15",
   "1.0.18",
@@ -183,16 +265,18 @@ function formatPinCommands(expectedVersion) {
   const ver = resolvePinTarget(expectedVersion);
   if (!ver) return [];
   return [
-    `npm i -g ${OPEN_SOURCE_AE_CLI_PACKAGE}@${ver} --registry=${OPEN_SOURCE_NPM_REGISTRY}`,
-    `npx skills add ${AE_CLI_SKILLS_REPO}#v${ver} -g -y`
+    `npx ${OPEN_SOURCE_AE_CLI_PACKAGE}@latest update --target ${ver}`
   ];
 }
 function formatUpgradeCommands(expectedVersion) {
-  const ver = expectedVersion.trim().replace(/^v/i, "");
-  if (!/^\d+\.\d+\.\d+(?:[-+].*)?$/.test(ver)) return [];
+  let ver;
+  try {
+    ver = exactVersion(expectedVersion);
+  } catch {
+    return [];
+  }
   return [
-    `npm i -g ${OPEN_SOURCE_AE_CLI_PACKAGE}@${ver} --registry=${OPEN_SOURCE_NPM_REGISTRY}`,
-    `npx skills add ${AE_CLI_SKILLS_REPO}#v${ver} -g -y`
+    `npx ${OPEN_SOURCE_AE_CLI_PACKAGE}@latest update --target ${ver}`
   ];
 }
 function formatUnifiedUpdateCommand() {
@@ -241,22 +325,335 @@ function formatCompatNotice(verdict) {
   ].join("\n");
 }
 
+// src/core/installation.ts
+import fs4 from "fs";
+import path4 from "path";
+
+// src/core/skills-install.ts
+import fs3 from "fs";
+import os from "os";
+import path3 from "path";
+import { parseDocument } from "yaml";
+function globalSkillsDirectory() {
+  return path3.join(os.homedir(), ".agents", "skills");
+}
+function skillName(content) {
+  const frontmatter = content.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
+  if (!frontmatter) throw new Error("Missing YAML frontmatter.");
+  const parsed = parseDocument(frontmatter[1], { uniqueKeys: true });
+  if (parsed.errors.length) throw new Error("Invalid YAML frontmatter.");
+  const data = parsed.toJS({ maxAliasCount: 100 });
+  if (!data || typeof data.name !== "string" || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(data.name) || typeof data.description !== "string" || !data.description.trim()) throw new Error("Invalid Skill metadata.");
+  return data.name;
+}
+function readFiles(root, prefix = "", files = /* @__PURE__ */ new Map()) {
+  for (const entry of fs3.readdirSync(path3.join(root, prefix), { withFileTypes: true })) {
+    if (entry.name.startsWith(".") || ["metadata.json", "__pycache__", "__pypackages__"].includes(entry.name)) continue;
+    const relative = path3.join(prefix, entry.name);
+    if (entry.isSymbolicLink()) throw new Error("Bundled Skills must contain regular files.");
+    if (entry.isDirectory()) readFiles(root, relative, files);
+    else if (entry.isFile()) files.set(relative, fs3.readFileSync(path3.join(root, relative)));
+  }
+  return files;
+}
+function readBundledSkills(directory) {
+  const skills = fs3.readdirSync(directory, { withFileTypes: true }).filter((entry) => entry.isDirectory() && !entry.name.startsWith(".")).map((entry) => {
+    try {
+      const files = readFiles(path3.join(directory, entry.name));
+      return { name: skillName(files.get("SKILL.md").toString("utf8")), files };
+    } catch {
+      const name = /^[a-z0-9-]+$/.test(entry.name) ? entry.name : "(invalid name)";
+      throw new Error(`Invalid bundled Skill ${name}: missing files or YAML/frontmatter error.`);
+    }
+  });
+  if (!skills.length || new Set(skills.map((skill) => skill.name)).size !== skills.length) {
+    throw new Error("Bundled Skills are empty or contain duplicate names.");
+  }
+  return skills;
+}
+function verifyGlobalSkills(skills, directory) {
+  return skills.flatMap((skill) => {
+    let reason = "";
+    try {
+      const target = path3.join(directory, skill.name);
+      if (skillName(fs3.readFileSync(path3.join(target, "SKILL.md"), "utf8")) !== skill.name) {
+        reason = "Installed Skill name does not match the bundled Skill.";
+      } else {
+        for (const [file, expected] of skill.files) {
+          if (!fs3.readFileSync(path3.join(target, file)).equals(expected)) {
+            reason = "Installed files do not match the CLI package version.";
+            break;
+          }
+        }
+      }
+    } catch (error) {
+      reason = error.code === "ENOENT" ? "Expected Skill file is missing." : "Installed Skill has invalid YAML/frontmatter or unreadable files.";
+    }
+    return reason ? [{ skill: skill.name, reason }] : [];
+  });
+}
+function skillProcessProblem(result) {
+  const output = `${result.stdout}
+${result.stderr}`.replace(/\x1b\[[0-9;]*m/g, "");
+  if (/(?:YAML|frontmatter)[^\n]*(?:parse|invalid|error)|(?:parse|invalid|error)[^\n]*(?:YAML|frontmatter)/i.test(output)) {
+    return "Skills reported a YAML/frontmatter parsing error.";
+  }
+  const lines = output.split(/\r?\n/);
+  const ignored = lines.filter((line) => /(?:PromptScript|Eve) does not support global skill installation\s*$/.test(line));
+  const failures = [...output.matchAll(/Failed to install (\d+)/g)].reduce((sum, match) => sum + Number(match[1]), 0);
+  const remaining = lines.filter((line) => !ignored.includes(line) && !/Failed to install \d+/.test(line)).join("\n");
+  if (failures > ignored.length || /✗|(?:^|\n)[^\w\n]*(?:Error\b|Installation failed\b|Failed\b)/i.test(remaining)) {
+    return "Skills installation failed for a supported client. Check directory permissions and retry.";
+  }
+  if (commandSucceeded(result)) return null;
+  if (!result.error && !result.signal && ignored.length > 0 && failures === ignored.length && !/EACCES|EPERM|ETIMEDOUT|ENOTFOUND|ECONN|network|permission denied/i.test(remaining)) return null;
+  return "Skills process failed. Check network access and directory permissions, then retry.";
+}
+
+// src/core/installation.ts
+function distribution(packageName) {
+  if (packageName === "@thinkingai/ae-cli") return { registry: "https://registry.npmjs.org", repository: "ThinkingAIAgenticEngine/ae-cli" };
+  if (packageName === "@tant/ae-cli") return { registry: "https://npm.thinkingdata.cn:3443", repository: "http://10.27.249.150:8888/te-ai/te-cli.git" };
+  throw new Error("Unsupported CLI package. Use an official AE CLI distribution.");
+}
+function newInstallationReport(packageName, version, dryRun = false) {
+  return {
+    ok: false,
+    dry_run: dryRun,
+    cli: { package: packageName, version, path: null, verified: false, action: "pending", warnings: [] },
+    skills: {
+      directory: globalSkillsDirectory(),
+      expected_count: 0,
+      installed_count: 0,
+      missing: [],
+      source: null,
+      version,
+      status: "pending",
+      failures: [],
+      attempts: []
+    },
+    auth: { host: null, authenticated: null, warnings: [] },
+    next_steps: []
+  };
+}
+function failInstallation(report, stage, message, cause = "validation") {
+  report.ok = false;
+  report.error = { type: "config", code: "AE_CLI_INSTALL_FAILED", message, stage, cause };
+  if (!report.next_steps.length) report.next_steps.push("Fix the reported problem and rerun the same install or update command.");
+  return report;
+}
+function installPlan(packageName, version, root = "<npm-root>") {
+  const config = distribution(packageName);
+  const target = exactVersion(version);
+  const source = path4.join(root, packageName, "skills");
+  return [
+    `npm install -g ${packageName}@${target} --registry=${config.registry}`,
+    `npx -y ${SKILLS_TOOL} add ${JSON.stringify(source)} -g -y --agent universal`,
+    `npx -y ${SKILLS_TOOL} add ${config.repository}#v${target} -g -y --agent universal`,
+    `npx -y ${SKILLS_TOOL} add ${JSON.stringify(globalSkillsDirectory())} -g -y --copy`
+  ];
+}
+function verifySkillsAttempt(report, skills, result, stage, source) {
+  const problem = skillProcessProblem(result);
+  report.skills.failures = verifyGlobalSkills(skills, report.skills.directory);
+  if (problem) {
+    for (const skill of skills) {
+      if (!report.skills.failures.some((failure) => failure.skill === skill.name)) {
+        report.skills.failures.push({ skill: skill.name, reason: problem });
+      }
+    }
+  }
+  report.skills.missing = report.skills.failures.map((failure) => failure.skill);
+  report.skills.installed_count = skills.length - report.skills.missing.length;
+  const cause = commandSucceeded(result) ? "validation" : classifyInstallFailure(result);
+  report.skills.attempts.push({
+    source,
+    stage,
+    cause: report.skills.missing.length ? cause : null,
+    failures: [...report.skills.failures]
+  });
+  report.skills.status = !report.skills.missing.length ? "success" : report.skills.installed_count ? "partial" : "failed";
+  return report.skills.status === "success";
+}
+function readPackage(root) {
+  try {
+    return JSON.parse(fs4.readFileSync(path4.join(root, "package.json"), "utf8"));
+  } catch {
+    return null;
+  }
+}
+function linked(root) {
+  try {
+    return fs4.lstatSync(root).isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
+function cliBinBelongsToPackage(bin, packageRoot, platform) {
+  const entry = fs4.realpathSync(path4.join(packageRoot, "bin", "ae-cli.js"));
+  if (platform !== "win32") return fs4.realpathSync(bin) === entry;
+  const shim = fs4.readFileSync(bin, "utf8");
+  const targets = [...shim.matchAll(/"%(?:dp0%|~dp0)[\\/]([^"\r\n]+)"/gi)];
+  return targets.some(([, relative]) => {
+    try {
+      const target = path4.resolve(path4.dirname(bin), relative.replace(/\\/g, path4.sep));
+      return fs4.realpathSync(target).toLowerCase() === entry.toLowerCase();
+    } catch {
+      return false;
+    }
+  });
+}
+function runInstallation(options = {}) {
+  const local = getLocalCliPackageInfo();
+  const packageName = options.packageName ?? local.name;
+  const report = newInstallationReport(packageName, "", Boolean(options.dryRun));
+  const runner = options.runner ?? defaultInstallRunner;
+  const progress = options.progress ?? (() => {
+  });
+  const platform = options.platform ?? process.platform;
+  report.skills.directory = options.skillsDirectory ?? globalSkillsDirectory();
+  let stage = "environment";
+  try {
+    const target = exactVersion(options.target ?? local.version);
+    report.cli.version = target;
+    report.skills.version = target;
+    const config = distribution(packageName);
+    report.auth.host = installHost(options.host);
+    const major = Number((options.nodeVersion ?? process.versions.node).split(".")[0]);
+    if (!Number.isInteger(major) || major < 20) return failInstallation(report, stage, "AE CLI requires Node.js 20 or later. Select an existing supported Node runtime and rerun.");
+    if (options.dryRun) {
+      report.ok = true;
+      report.commands = installPlan(packageName, target);
+      report.next_steps.push("Dry run only; CLI, global Skills, and authentication have not been verified.");
+      return report;
+    }
+    const npm = resolveNodeTool("npm", process.execPath, platform);
+    progress("[ae-cli] [1/4] Checking Node.js, npm, and npx...");
+    for (const tool of [npm, resolveNodeTool("npx", process.execPath, platform)]) {
+      const result = runner(tool, ["--version"], 15e3);
+      if (!commandSucceeded(result)) return failInstallation(report, stage, "npm and npx must be available alongside the selected Node.js runtime.", classifyInstallFailure(result));
+    }
+    stage = "package_validation";
+    const rootResult = runner(npm, ["root", "-g"], 15e3);
+    const prefixResult = runner(npm, ["prefix", "-g"], 15e3);
+    const globalRoot = rootResult.stdout.trim();
+    const prefix = prefixResult.stdout.trim();
+    if (!commandSucceeded(rootResult) || !commandSucceeded(prefixResult) || !path4.isAbsolute(globalRoot) || !path4.isAbsolute(prefix) || /[\r\n]/.test(globalRoot + prefix)) return failInstallation(report, stage, "Cannot resolve npm global root and prefix. Check npm configuration.");
+    const packageRoot = path4.join(globalRoot, packageName);
+    const bin = platform === "win32" ? path4.join(prefix, "ae-cli.cmd") : path4.join(prefix, "bin", "ae-cli");
+    report.cli.path = bin;
+    const env = options.env ?? process.env;
+    const installedBefore = readPackage(packageRoot);
+    if (linked(packageRoot) && !options.skipCliInstall) return failInstallation(report, stage, "The global CLI is npm-linked to source. Preserve the link; use a separate npm prefix for a packaged installation.");
+    if (options.skipCliInstall || installedBefore?.name === packageName && installedBefore.version === target && fs4.existsSync(bin)) {
+      report.cli.action = "skipped";
+      progress("[ae-cli] [2/4] Verifying the existing CLI...");
+    } else {
+      stage = "npm_install";
+      progress(`[ae-cli] [2/4] Installing ${packageName}@${target}...`);
+      const result = runner(npm, ["install", "-g", `${packageName}@${target}`, "--registry", config.registry], INSTALL_TIMEOUT_MS);
+      if (!commandSucceeded(result)) return failInstallation(report, stage, "npm installation failed. Check network access and a user-writable npm prefix; do not use sudo.", classifyInstallFailure(result));
+      report.cli.action = "installed";
+    }
+    stage = "package_validation";
+    const installed = readPackage(packageRoot);
+    if (installed?.name !== packageName || installed.version !== target) return failInstallation(report, stage, "Installed CLI package identity or version does not match the requested distribution.");
+    if (!fs4.existsSync(bin)) return failInstallation(report, stage, "npm did not create the global ae-cli executable. Enable npm bin-links, reinstall, and add the global executable directory to PATH.");
+    if (!cliBinBelongsToPackage(bin, packageRoot, platform)) return failInstallation(report, stage, "The global executable does not belong to the installed CLI package.");
+    const versionResult = runner(bin, ["--version"], 15e3);
+    if (!commandSucceeded(versionResult) || versionResult.stdout.trim() !== target) return failInstallation(report, stage, "ae-cli --version did not return the requested version. Refresh the shell command cache and check npm bin links.");
+    report.cli.verified = true;
+    const pathKey = platform === "win32" ? Object.keys(env).find((key) => key.toLowerCase() === "path") : "PATH";
+    const installedPathBin = (env[pathKey ?? "PATH"] ?? "").split(platform === "win32" ? ";" : path4.delimiter).filter(Boolean).map((dir) => path4.join(dir.replace(/^"(.*)"$/, "$1"), platform === "win32" ? "ae-cli.cmd" : "ae-cli")).find((file) => fs4.existsSync(file) && !file.includes(`${path4.sep}_npx${path4.sep}`));
+    if (!installedPathBin || fs4.realpathSync(installedPathBin) !== fs4.realpathSync(bin)) {
+      report.cli.warnings.push(`Add ${path4.dirname(bin)} to the front of PATH and refresh the shell command cache. The absolute executable was verified.`);
+      report.next_steps.push(`Use the verified executable at ${bin}, or correct PATH before invoking ae-cli.`);
+    }
+    stage = "skills_local";
+    const skillsPath = path4.join(packageRoot, "skills");
+    const skills = readBundledSkills(skillsPath);
+    report.skills.expected_count = skills.length;
+    for (const source of [skillsPath, `${config.repository}#v${target}`]) {
+      stage = source === skillsPath ? "skills_local" : "skills_github";
+      report.skills.source = source === skillsPath ? "installed-package" : source;
+      progress("[ae-cli] [3/4] Installing and verifying global Skills...");
+      const result = runner(resolveNodeTool("npx", process.execPath, platform), [
+        "-y",
+        SKILLS_TOOL,
+        "add",
+        source,
+        "-g",
+        "-y",
+        "--agent",
+        "universal",
+        "--skill",
+        ...skills.map((skill) => skill.name)
+      ], INSTALL_TIMEOUT_MS);
+      if (verifySkillsAttempt(report, skills, result, stage, report.skills.source)) break;
+    }
+    if (report.skills.status !== "success") {
+      report.skills.status = report.skills.installed_count ? "partial" : "failed";
+      const first = report.skills.attempts[0];
+      return failInstallation(
+        report,
+        first.stage,
+        "Global Skills installation is incomplete. See skills.attempts for the original and fallback failures.",
+        first.cause ?? "validation"
+      );
+    }
+    stage = "skills_clients";
+    progress("[ae-cli] [3/4] Distributing Skills to detected clients...");
+    const clientResult = runner(
+      resolveNodeTool("npx", process.execPath, platform),
+      ["-y", SKILLS_TOOL, "add", report.skills.directory, "-g", "-y", "--copy", "--skill", ...skills.map((skill) => skill.name)],
+      INSTALL_TIMEOUT_MS
+    );
+    if (!verifySkillsAttempt(report, skills, clientResult, stage, report.skills.directory)) {
+      return failInstallation(
+        report,
+        stage,
+        "Global Skills were installed, but client distribution is incomplete. See skills.attempts for details.",
+        report.skills.attempts.at(-1).cause ?? "validation"
+      );
+    }
+    progress("[ae-cli] [4/4] Checking authentication guidance...");
+    if (report.auth.host) {
+      const result = runner(bin, ["--no-update-check", "--format", "json", "auth", "status", "--host", report.auth.host], INSTALL_TIMEOUT_MS);
+      try {
+        const body = JSON.parse(result.stdout);
+        if (!commandSucceeded(result) || !body.ok || typeof body.data?.authenticated !== "boolean") throw new Error();
+        report.auth.authenticated = body.data.authenticated;
+      } catch {
+        report.auth.warnings.push("Authentication status could not be verified. Run auth status for this host.");
+      }
+    }
+    if (report.auth.authenticated !== true) {
+      report.next_steps.push(`ae-cli auth login --host ${report.auth.host ?? "<AE_HOST>"} --no-wait`);
+      report.next_steps.push("Complete browser authorization, then run ae-cli auth login --host <AE_HOST> --device-code <DEVICE_CODE>.");
+    }
+    report.ok = true;
+    return report;
+  } catch (error) {
+    const safe = error instanceof Error && /^(Expected an exact|Unsupported CLI package|Host must|Invalid bundled Skill|Bundled Skills are empty)/.test(error.message);
+    return failInstallation(report, stage, safe ? error.message : "Installation could not complete at this stage. Check file permissions, package contents, and global Skills directory.");
+  }
+}
+
 // src/core/version-sync.ts
-var COMMAND_TIMEOUT_MS = 12e4;
 var AUTO_ATTEMPT_INTERVAL_MS = 60 * 60 * 1e3;
 var MAX_AUTO_ATTEMPTS_PER_DAY = 3;
 var LOCK_STALE_MS = 10 * 60 * 1e3;
 var SYNC_STATE_FILE = "version-sync.json";
 var SYNC_LOCK_FILE = "version-sync.lock";
 function syncStatePath() {
-  return path.join(getConfigDir(), SYNC_STATE_FILE);
+  return path5.join(getConfigDir(), SYNC_STATE_FILE);
 }
 function syncLockPath() {
-  return path.join(getConfigDir(), SYNC_LOCK_FILE);
+  return path5.join(getConfigDir(), SYNC_LOCK_FILE);
 }
 function readSyncStore() {
   try {
-    const raw = JSON.parse(fs.readFileSync(syncStatePath(), "utf8"));
+    const raw = JSON.parse(fs5.readFileSync(syncStatePath(), "utf8"));
     if (raw && typeof raw === "object" && raw.hosts && typeof raw.hosts === "object") {
       return raw;
     }
@@ -266,8 +663,8 @@ function readSyncStore() {
 }
 function writeSyncStore(store) {
   try {
-    fs.mkdirSync(getConfigDir(), { recursive: true });
-    fs.writeFileSync(syncStatePath(), JSON.stringify(store, null, 2));
+    fs5.mkdirSync(getConfigDir(), { recursive: true });
+    fs5.writeFileSync(syncStatePath(), JSON.stringify(store, null, 2));
   } catch {
   }
 }
@@ -343,61 +740,9 @@ function isAutoSyncTargetEligible(version) {
 function isPublicAeCliPackage(packageName) {
   return packageName === OPEN_SOURCE_AE_CLI_PACKAGE;
 }
-function resolveNodeTool(tool, execPath = process.execPath, platform = process.platform) {
-  const fileName = platform === "win32" ? `${tool}.cmd` : tool;
-  const sibling = path.join(path.dirname(execPath), fileName);
-  return fs.existsSync(sibling) ? sibling : fileName;
-}
-function buildVersionInstallPlan(targetRaw, globalRoot = "<npm-root>") {
+function buildVersionInstallPlan(targetRaw, globalRoot = "<npm-root>", packageName = OPEN_SOURCE_AE_CLI_PACKAGE) {
   const target = normalizeCliVersion(targetRaw);
-  const localSkills = path.join(globalRoot, "@thinkingai", "ae-cli", "skills");
-  return {
-    target,
-    commands: [
-      `npm install -g ${OPEN_SOURCE_AE_CLI_PACKAGE}@${target} --registry=${OPEN_SOURCE_NPM_REGISTRY}`,
-      `npx -y skills add ${localSkills} -g -y`,
-      `npx -y skills add ${AE_CLI_SKILLS_REPO}#v${target} -g -y`
-    ],
-    skillsSources: ["installed-package", "github-fallback"]
-  };
-}
-function defaultRunner(command, args, timeoutMs) {
-  const result = spawnSync(command, args, {
-    encoding: "utf8",
-    maxBuffer: 2 * 1024 * 1024,
-    stdio: ["ignore", "pipe", "pipe"],
-    timeout: timeoutMs,
-    windowsHide: true
-  });
-  return {
-    status: result.status,
-    stdout: result.stdout || "",
-    stderr: result.stderr || "",
-    error: result.error,
-    signal: result.signal
-  };
-}
-function resultMessage(result) {
-  if (result.error?.message) return result.error.message;
-  const detail = (result.stderr || result.stdout).trim().split(/\r?\n/).filter(Boolean).slice(-3).join(" ");
-  if (detail) return detail;
-  if (result.signal) return `Command terminated by ${result.signal}`;
-  return `Command exited with status ${result.status ?? "unknown"}`;
-}
-function classifyFailure(result) {
-  const text = `${result.error?.message || ""}
-${result.stderr}
-${result.stdout}`;
-  if (result.error && result.error.code === "ETIMEDOUT") return "timeout";
-  if (/timed?\s*out|ETIMEDOUT/i.test(text)) return "timeout";
-  if (/EACCES|EPERM|permission denied|access is denied/i.test(text)) return "permission";
-  if (/EAI_AGAIN|ENOTFOUND|ECONNRESET|ECONNREFUSED|network|unable to access|could not resolve|certificate|SSL/i.test(text)) {
-    return "network";
-  }
-  if (/E404|404 Not Found|no matching version|couldn't find remote ref|not found/i.test(text)) {
-    return "package_missing";
-  }
-  return "unknown";
+  return { target, commands: installPlan(packageName, target, globalRoot), skillsSources: ["installed-package", "github-fallback"] };
 }
 function friendlyVersionSyncFailure(result) {
   if (result.cause === "busy") {
@@ -420,24 +765,21 @@ function friendlyVersionSyncFailure(result) {
   }
   return `Version synchronization failed at ${result.stage}.`;
 }
-function commandSucceeded(result) {
-  return !result.error && result.status === 0;
-}
 function acquireInstallLock(now) {
-  fs.mkdirSync(getConfigDir(), { recursive: true });
+  fs5.mkdirSync(getConfigDir(), { recursive: true });
   const file = syncLockPath();
   try {
-    return fs.openSync(file, "wx");
+    return fs5.openSync(file, "wx");
   } catch {
     try {
-      const age = now.getTime() - fs.statSync(file).mtimeMs;
+      const age = now.getTime() - fs5.statSync(file).mtimeMs;
       if (age >= LOCK_STALE_MS) {
-        fs.unlinkSync(file);
-        return fs.openSync(file, "wx");
+        fs5.unlinkSync(file);
+        return fs5.openSync(file, "wx");
       }
     } catch {
       try {
-        return fs.openSync(file, "wx");
+        return fs5.openSync(file, "wx");
       } catch {
         return null;
       }
@@ -447,121 +789,53 @@ function acquireInstallLock(now) {
 }
 function releaseInstallLock(fd) {
   try {
-    fs.closeSync(fd);
+    fs5.closeSync(fd);
   } catch {
   }
   try {
-    fs.unlinkSync(syncLockPath());
+    fs5.unlinkSync(syncLockPath());
   } catch {
   }
 }
-function validateInstalledPackage(npm, target, runner) {
-  const rootResult = runner(npm, ["root", "-g"], COMMAND_TIMEOUT_MS);
-  if (!commandSucceeded(rootResult)) {
-    return { ok: false, message: resultMessage(rootResult) };
-  }
-  const globalRoot = rootResult.stdout.trim();
-  const packageRoot = path.join(globalRoot, "@thinkingai", "ae-cli");
-  const packageJson = path.join(packageRoot, "package.json");
-  const skillsPath = path.join(packageRoot, "skills");
-  try {
-    const installed = JSON.parse(fs.readFileSync(packageJson, "utf8"));
-    if (normalizeCliVersion(installed.version || "") !== target) {
-      return {
-        ok: false,
-        message: `Installed package version ${installed.version || "unknown"} does not match ${target}`
-      };
-    }
-    if (!fs.statSync(skillsPath).isDirectory()) {
-      return { ok: false, message: `Installed package has no skills directory: ${skillsPath}` };
-    }
-    return { ok: true, skillsPath };
-  } catch (error) {
-    return { ok: false, message: error?.message || String(error) };
-  }
-}
 function installVersion(targetRaw, options = {}) {
-  const target = normalizeCliVersion(targetRaw);
-  const runner = options.runner ?? defaultRunner;
-  const progress = options.progress ?? (() => {
-  });
-  const npm = resolveNodeTool("npm");
-  const npx = resolveNodeTool("npx");
-  const lock = acquireInstallLock(options.now ?? /* @__PURE__ */ new Date());
-  if (lock === null) {
+  const run = () => {
+    const report = runInstallation({ ...options, target: targetRaw });
+    const cliInstalled = report.cli.verified || report.cli.action === "installed";
+    if (report.ok) return { ok: true, cliInstalled, skillsSource: report.skills.source === "installed-package" ? "local" : "github", report };
+    return {
+      ok: false,
+      stage: report.error?.stage ?? "environment",
+      cliInstalled,
+      skillsPending: cliInstalled,
+      cause: report.error?.cause ?? "validation",
+      message: report.error?.message ?? "Installation failed.",
+      report
+    };
+  };
+  if (options.dryRun) return run();
+  let lock;
+  try {
+    lock = acquireInstallLock(options.now ?? /* @__PURE__ */ new Date());
+  } catch {
     return {
       ok: false,
       stage: "lock",
       cliInstalled: false,
       skillsPending: Boolean(options.skipCliInstall),
-      cause: "busy",
-      message: "Another ae-cli process is already synchronizing the global installation."
+      cause: "permission",
+      message: "The installation lock directory is not writable."
     };
   }
-  let cliInstalled = Boolean(options.skipCliInstall);
+  if (lock === null) return {
+    ok: false,
+    stage: "lock",
+    cliInstalled: false,
+    skillsPending: Boolean(options.skipCliInstall),
+    cause: "busy",
+    message: "Another ae-cli process is already synchronizing the global installation."
+  };
   try {
-    if (!options.skipCliInstall) {
-      progress(`[ae-cli] [1/2] Installing ae-cli ${target}...`);
-      const npmResult = runner(
-        npm,
-        [
-          "install",
-          "-g",
-          `${OPEN_SOURCE_AE_CLI_PACKAGE}@${target}`,
-          "--registry",
-          OPEN_SOURCE_NPM_REGISTRY
-        ],
-        COMMAND_TIMEOUT_MS
-      );
-      if (!commandSucceeded(npmResult)) {
-        return {
-          ok: false,
-          stage: "npm_install",
-          cliInstalled: false,
-          skillsPending: false,
-          cause: classifyFailure(npmResult),
-          message: resultMessage(npmResult)
-        };
-      }
-      cliInstalled = true;
-    }
-    const installed = validateInstalledPackage(npm, target, runner);
-    if (!installed.ok) {
-      return {
-        ok: false,
-        stage: "package_validation",
-        cliInstalled,
-        skillsPending: cliInstalled,
-        cause: "validation",
-        message: installed.message
-      };
-    }
-    progress("[ae-cli] [2/2] Synchronizing Skills from the installed npm package...");
-    const localResult = runner(
-      npx,
-      ["-y", "skills", "add", installed.skillsPath, "-g", "-y"],
-      COMMAND_TIMEOUT_MS
-    );
-    if (commandSucceeded(localResult)) {
-      return { ok: true, cliInstalled, skillsSource: "local" };
-    }
-    progress("[ae-cli] Local Skills sync did not complete; trying the GitHub fallback...");
-    const githubResult = runner(
-      npx,
-      ["-y", "skills", "add", `${AE_CLI_SKILLS_REPO}#v${target}`, "-g", "-y"],
-      COMMAND_TIMEOUT_MS
-    );
-    if (commandSucceeded(githubResult)) {
-      return { ok: true, cliInstalled, skillsSource: "github" };
-    }
-    return {
-      ok: false,
-      stage: "skills_github",
-      cliInstalled,
-      skillsPending: cliInstalled,
-      cause: classifyFailure(githubResult),
-      message: resultMessage(githubResult) || resultMessage(localResult)
-    };
+    return run();
   } finally {
     releaseInstallLock(lock);
   }
@@ -581,12 +855,12 @@ function autoSyncDirection(current, expected) {
 
 // src/core/feature-config.ts
 import crypto from "crypto";
-import fs2 from "fs";
-import path2 from "path";
+import fs6 from "fs";
+import path6 from "path";
 var FEATURE_TTL_MS = 24 * 60 * 60 * 1e3;
 var UNAVAILABLE_TTL_MS = 5 * 60 * 1e3;
 function cachePath() {
-  return path2.join(getConfigDir(), "feature-config.json");
+  return path6.join(getConfigDir(), "feature-config.json");
 }
 function cacheKey(host, token) {
   const fingerprint = crypto.createHash("sha256").update(token).digest("hex");
@@ -594,7 +868,7 @@ function cacheKey(host, token) {
 }
 function readStore() {
   try {
-    const value = JSON.parse(fs2.readFileSync(cachePath(), "utf8"));
+    const value = JSON.parse(fs6.readFileSync(cachePath(), "utf8"));
     return value?.entries && typeof value.entries === "object" ? value : { entries: {} };
   } catch {
     return { entries: {} };
@@ -604,13 +878,13 @@ function writeStore(store) {
   const target = cachePath();
   const temp = `${target}.${process.pid}.${crypto.randomBytes(6).toString("hex")}.tmp`;
   try {
-    fs2.mkdirSync(path2.dirname(target), { recursive: true });
-    fs2.writeFileSync(temp, JSON.stringify(store), { encoding: "utf8", mode: 384 });
-    fs2.renameSync(temp, target);
-    fs2.chmodSync(target, 384);
+    fs6.mkdirSync(path6.dirname(target), { recursive: true });
+    fs6.writeFileSync(temp, JSON.stringify(store), { encoding: "utf8", mode: 384 });
+    fs6.renameSync(temp, target);
+    fs6.chmodSync(target, 384);
   } catch {
     try {
-      fs2.rmSync(temp, { force: true });
+      fs6.rmSync(temp, { force: true });
     } catch {
     }
   }
@@ -640,19 +914,20 @@ async function resolveKbAutoDiscoveryFeature(host, token, fetchRemote) {
 }
 
 // src/core/compat-check.ts
-import fs3 from "fs";
-import path3 from "path";
-var CHECK_INTERVAL_MS = 24 * 60 * 60 * 1e3;
+import fs7 from "fs";
+import path7 from "path";
+var CHECK_INTERVAL_MS = 60 * 60 * 1e3;
+var NOTIFY_INTERVAL_MS = 24 * 60 * 60 * 1e3;
 var FETCH_TIMEOUT_MS = 3e3;
 var CLI_CONFIG_PATH = "/v1/ta/cli/config";
 function cacheFilePath() {
-  return path3.join(getConfigDir(), "compat-check.json");
+  return path7.join(getConfigDir(), "compat-check.json");
 }
 function readStore2() {
   try {
     const file = cacheFilePath();
-    if (!fs3.existsSync(file)) return { hosts: {} };
-    const raw = JSON.parse(fs3.readFileSync(file, "utf8"));
+    if (!fs7.existsSync(file)) return { hosts: {} };
+    const raw = JSON.parse(fs7.readFileSync(file, "utf8"));
     if (!raw || typeof raw !== "object" || !raw.hosts) return { hosts: {} };
     return raw;
   } catch {
@@ -662,23 +937,23 @@ function readStore2() {
 function writeStore2(store) {
   try {
     const dir = getConfigDir();
-    if (!fs3.existsSync(dir)) fs3.mkdirSync(dir, { recursive: true });
-    fs3.writeFileSync(cacheFilePath(), JSON.stringify(store, null, 2));
+    if (!fs7.existsSync(dir)) fs7.mkdirSync(dir, { recursive: true });
+    fs7.writeFileSync(cacheFilePath(), JSON.stringify(store, null, 2));
   } catch {
   }
 }
 function hostKey(host) {
   return normalizeUrl(host);
 }
-function isStale(entry) {
+function isCompatCacheStale(entry, now = Date.now()) {
   if (!entry?.lastFetchedAt) return true;
-  const age = Date.now() - new Date(entry.lastFetchedAt).getTime();
+  const age = now - new Date(entry.lastFetchedAt).getTime();
   return age >= CHECK_INTERVAL_MS;
 }
-function shouldNotify(entry) {
+function shouldNotifyCompat(entry, now = Date.now()) {
   if (!entry?.lastNotifiedAt) return true;
-  const age = Date.now() - new Date(entry.lastNotifiedAt).getTime();
-  return age >= CHECK_INTERVAL_MS;
+  const age = now - new Date(entry.lastNotifiedAt).getTime();
+  return age >= NOTIFY_INTERVAL_MS;
 }
 function shouldSkipCompatCheck(argv = process.argv) {
   if (process.env.AE_CLI_NO_COMPAT_CHECK === "1") return true;
@@ -702,7 +977,7 @@ function rootCommand(argv) {
 }
 function shouldSkipAutoSync(argv = process.argv) {
   const command = rootCommand(argv);
-  return command === "update" || command === "auth" || command === "config";
+  return command === "update" || command === "install" || command === "auth" || command === "config";
 }
 async function fetchCliConfig(host, cliToken) {
   const url = new URL(CLI_CONFIG_PATH, host.endsWith("/") ? host : `${host}/`);
@@ -792,7 +1067,7 @@ async function refreshAndMaybeNotify(host, pkg, allowAutoSync) {
   let expected = existing?.expectedVersion;
   let cluster = existing?.clusterVersion;
   let fetchedAt = existing?.lastFetchedAt;
-  if (isStale(existing)) {
+  if (isCompatCacheStale(existing)) {
     const remote = await fetchCliConfig(host, token);
     if (remote) rememberKbAutoDiscoveryFeature(host, token, remote.projectSemanticKbAutoDiscovery ?? false);
     if (!remote?.aeCliVersion) {
@@ -895,7 +1170,7 @@ async function refreshAndMaybeNotify(host, pkg, allowAutoSync) {
   const notice = verdict.kind === "ok" && pendingSkills ? `[ae-cli] CLI ${expected} is installed, but its Skills are not synchronized.
          Run: ae-cli update` : formatCompatNotice(verdict);
   if (!notice) return { status: "continue" };
-  const dueForTip = shouldNotify(entry);
+  const dueForTip = shouldNotifyCompat(entry);
   if (!dueForTip) {
     pendingHostCompatNotice = void 0;
     pendingUpdateNotice = void 0;
@@ -1070,30 +1345,51 @@ async function formatOutput(data, format, jqExpr) {
   };
   return JSON.stringify(envelope, null, 2);
 }
-function formatError(type, message, hint, code, meta) {
+function formatError(type, message, hint, code, meta, details) {
   const envelope = {
     ok: false,
-    error: { type, message, hint, code },
+    error: { type, message, hint, code, ...details === void 0 ? {} : { details } },
     ...meta && Object.keys(meta).length > 0 ? { meta } : {}
   };
   return JSON.stringify(envelope, null, 2);
 }
 function printError(type, message, hint, code, meta, options = {}) {
-  const formatted = formatError(type, message, hint, code, meta);
+  const formatted = formatError(type, message, hint, code, meta, options.details);
   process.stderr.write(formatted + "\n");
   if (options.log !== false) {
     logger.error(`[${type}] ${message}${hint ? " | " + hint : ""}`);
   }
 }
-async function printOutput(data, format, jqExpr) {
+function sensitiveRecoveryData(data) {
+  const safe = {};
+  const item = {};
+  if (typeof data?.item?.id === "string") item.id = data.item.id;
+  if (Number.isSafeInteger(data?.item?.contentRevision)) item.contentRevision = data.item.contentRevision;
+  if (Object.keys(item).length > 0) safe.item = item;
+  if (["markdown", "text"].includes(data?.contentFormat)) safe.contentFormat = data.contentFormat;
+  if (typeof data?.out === "string") safe.out = data.out;
+  return safe;
+}
+async function printOutput(data, format, jqExpr, options = {}) {
   try {
     process.stdout.write(await formatOutput(data, format, jqExpr) + "\n");
   } catch (error) {
     if (error?.code === "OUTPUT_PROJECTION_FAILED") {
-      const recovery = JSON.parse(formatError("validation", error.message, error.hint, error.code, readOutputMetadata(data)));
+      if (options.redactErrors) {
+        error.message = "Invalid --jq expression: output projection failed; source content is omitted from diagnostics.";
+        error.hint = "The read completed. Fix --jq and explicitly run read-text again without --out, or inspect the file at data.out if present. This error result excludes source content.";
+      }
+      const recovery = JSON.parse(formatError(
+        "validation",
+        error.message,
+        error.hint,
+        error.code,
+        options.redactErrors ? void 0 : readOutputMetadata(data)
+      ));
+      const recoveryData = options.redactErrors ? sensitiveRecoveryData(unwrapOutputData(data)) : unwrapOutputData(data);
       await new Promise((resolve, reject) => {
         process.stdout.write(
-          JSON.stringify({ ...recovery, data: unwrapOutputData(data) }, null, 2) + "\n",
+          JSON.stringify({ ...recovery, data: recoveryData }, null, 2) + "\n",
           (error2) => error2 ? reject(error2) : resolve()
         );
       });
@@ -1103,6 +1399,11 @@ async function printOutput(data, format, jqExpr) {
 }
 
 export {
+  exactVersion,
+  installHost,
+  getLocalCliPackageInfo,
+  newInstallationReport,
+  failInstallation,
   recordVersionSyncResult,
   buildVersionInstallPlan,
   friendlyVersionSyncFailure,