@thieung/agentkit-helper 0.1.0 → 0.1.1

package/README.md

@@ -28,7 +28,7 @@ In the TUI, use:
 - ↑/↓ to navigate
 - Space to select multiple runtimes
 - Enter to confirm
-- `← Back` to return to the previous step
+- Esc to return to the previous step
 
 Choose a project or user/global scope, Engineer or Marketing Kit, one or more
 runtimes, and the Stable or Beta channel. AgentKit remains responsible for Kit
@@ -40,6 +40,12 @@ separate consent, defaulting to No. It retries with `--force` only after you
 choose Yes. Global update is preserve-only: user-modified files are skipped
 and the helper never adds `--force`.
 
+Platform status: macOS is verified locally. Linux is a supported target for the
+portable Node.js path. Native Windows PowerShell support is experimental until
+it passes a real-machine smoke test; the repository includes Windows-oriented
+command handling and CI coverage, but does not yet claim provider-backed E2E
+verification.
+
 <details>
 <summary><strong>Advanced CLI usage</strong></summary>
 

package/README.vi.md

@@ -27,7 +27,7 @@ Trong TUI, dùng:
 - ↑/↓ để di chuyển
 - Space để chọn nhiều runtime
 - Enter để xác nhận
-- `← Quay lại` để trở về bước trước
+- Esc để trở về bước trước
 
 Bạn chỉ cần chọn scope project hoặc user/global, Engineer hoặc Marketing Kit,
 một hay nhiều runtime và release channel Stable hoặc Beta. AgentKit vẫn quản
@@ -38,6 +38,11 @@ tồn tại hoặc có drift, TUI hiển thị WARNING và hỏi consent riêng,
 Chỉ khi chọn Yes, helper mới retry bằng `--force`. Global update luôn dùng
 preserve-only: file do user chỉnh sửa được bỏ qua và helper không thêm `--force`.
 
+Trạng thái platform: macOS đã được verify local. Linux là target được hỗ trợ
+qua code path Node.js portable. Native Windows PowerShell đang ở mức
+experimental cho đến khi được smoke-test trên máy thật; repository đã có xử lý
+command và CI dành cho Windows nhưng chưa claim provider-backed E2E.
+
 <details>
 <summary><strong>Cách dùng CLI nâng cao</strong></summary>
 

package/bin/agentkit-helper.mjs

@@ -17,6 +17,7 @@ import {
 import {
   exportArgs,
   formatCommand,
+  formatEnvironmentAssignments,
   globalUpdateApplyArgs,
   globalUpdatePreviewArgs,
   installArgs,
@@ -45,6 +46,12 @@ import {
 } from "../lib/github-issue.mjs";
 import { t } from "../lib/i18n.mjs";
 import { isUnsafeProjectPath, resolveProjectPath } from "../lib/project.mjs";
+import {
+  classifyPiProfiles,
+  parsePiProfileInventory,
+  piProfileManagerInvocation,
+  piProfileProcessOptions,
+} from "../lib/pi-profiles.mjs";
 import { BACK, walkSelections } from "../lib/navigation.mjs";
 import {
   ask,
@@ -78,11 +85,15 @@ const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const metadata = JSON.parse(await readFile(resolve(packageRoot, "package.json"), "utf8"));
 const akBinary = process.env.AK_HELPER_AK_BIN || "ak";
 const ghBinary = process.env.AK_HELPER_GH_BIN || "gh";
+const piProfileManager = piProfileManagerInvocation(
+  process.env.AK_HELPER_PPM_BIN || "pi-profile-manager",
+);
 const installerUrl = "https://agentkit.best/install.sh";
 const windowsInstallerUrl = "https://agentkit.best/install.ps1";
 let activeLanguage = "en";
 let activeAction = null;
 let installedAkVersion = "";
+let binaryUpdateAvailable = false;
 
 function ui(key, values) {
   return t(activeLanguage, key, values);
@@ -172,38 +183,74 @@ Target groups:
 `);
 }
 
-function printPlan(args, cwd) {
+function printPlan(args, cwd, envOverrides = {}) {
   const suffix = cwd && cwd !== process.cwd() ? `  (cwd: ${cwd})` : "";
-  process.stdout.write(`${colorText(`  ${formatCommand(akBinary, args)}${suffix}`, "command")}\n`);
+  const environment = formatEnvironmentAssignments(envOverrides);
+  const prefix = environment ? `${environment} ` : "";
+  process.stdout.write(`${colorText(`  ${prefix}${formatCommand(akBinary, args)}${suffix}`, "command")}\n`);
 }
 
 function printSection(message) {
   process.stdout.write(`\n${colorText(message, "section")}\n`);
 }
 
-async function runAkCommand(args, { cwd = process.cwd() } = {}) {
+async function runAkCommand(
+  args,
+  { cwd = process.cwd(), envOverrides = {}, envUnset = [] } = {},
+) {
   const result = await withSpinner(
     ui("runningAkCommand"),
     ui("akCommandComplete"),
-    () => runCapture(akBinary, args, { cwd }),
+    () => runCapture(akBinary, args, { cwd, envOverrides, envUnset }),
   );
   if (result.stdout) process.stdout.write(`${result.stdout}\n`);
   if (result.stderr) process.stderr.write(`${result.stderr}\n`);
 }
 
+async function checkInteractiveBinaryUpdate() {
+  const channel = releaseChannelForVersion(installedAkVersion) || "stable";
+  try {
+    const result = await withSpinner(
+      ui("checkingBinaryUpdate"),
+      ui("checkedBinaryUpdate"),
+      () => runCapture(akBinary, selfUpdateJsonCheckArgs(channel)),
+    );
+    const check = parseSelfUpdateOutput(result.stdout);
+    const classification = classifySelfUpdate(check);
+    binaryUpdateAvailable = classification === "update";
+    if (binaryUpdateAvailable) {
+      warning(`│  ${ui("binaryUpdateAvailable", {
+        current: check.current_version,
+        latest: check.latest_version,
+        channel: check.channel || channel,
+      })}`);
+    } else if (classification === "current") {
+      process.stdout.write(`${colorText(`│  ${ui("binaryUpToDate", {
+        version: check.current_version,
+        channel: check.channel || channel,
+      })}`, "binary")}\n`);
+    } else {
+      warning(`│  ${ui("binaryUpdateStatusUnknown", { status: check.status })}`);
+    }
+  } catch (error) {
+    binaryUpdateAvailable = false;
+    warning(`│  ${ui("binaryUpdateCheckFailed", { message: error.message })}`);
+  }
+}
+
 async function chooseCommand(allowLanguageBack = false) {
   const choices = [
+    { label: ui("selfUpdateAction"), value: "self-update" },
     { label: ui("installAction"), value: "install" },
     { label: ui("updateAction"), value: "update" },
-    { label: ui("selfUpdateAction"), value: "self-update" },
     { label: ui("updateAllAction"), value: "update-all" },
     { label: ui("exportAction"), value: "export" },
     { label: ui("doctorAction"), value: "doctor" },
   ];
-  if (allowLanguageBack) {
-    choices.push({ label: ui("backToLanguage"), value: BACK });
-  }
-  return choose(ui("commandPrompt"), choices);
+  const defaultIndex = binaryUpdateAvailable ? 0 : 1;
+  return allowLanguageBack
+    ? chooseWithBack(ui("commandPrompt"), choices, defaultIndex, ui("escapeBack"))
+    : choose(ui("commandPrompt"), choices, defaultIndex);
 }
 
 function kitName(kit) {
@@ -231,7 +278,7 @@ async function selectLanguage(options, forcePrompt = false) {
 
 function chooseLocalized(allowBack, message, choices, defaultIndex = 0) {
   return allowBack
-    ? chooseWithBack(message, choices, defaultIndex, ui("back"))
+    ? chooseWithBack(message, choices, defaultIndex, ui("escapeBack"))
     : choose(message, choices, defaultIndex);
 }
 
@@ -331,8 +378,7 @@ async function selectTarget(
       disabled: true,
     });
   }
-  const configuredTargets = splitTargetSpec(config?.target).filter((target) => targets.has(target));
-  const initialValues = configuredTargets.length > 0 ? configuredTargets : ["codex"];
+  const initialValues = [];
   const selected = await (allowBack ? multiChooseWithBack : multiChoose)(
     ui(promptKey, promptValues),
     choices,
@@ -715,14 +761,14 @@ async function update(commandOptions, allowBack = false) {
 }
 
 function updateAllPreviewArgs(candidate, channel) {
-  if (candidate.kind === "global") {
+  if (candidate.kind === "global" || candidate.kind === "profile") {
     return globalUpdatePreviewArgs(channel, candidate.runtimes, candidate.kit);
   }
   return projectUpdatePreviewArgs(candidate.path, candidate.runtime, channel, candidate.kit);
 }
 
 function updateAllApplyArgs(candidate, channel) {
-  if (candidate.kind === "global") {
+  if (candidate.kind === "global" || candidate.kind === "profile") {
     return globalUpdateApplyArgs(channel, candidate.runtimes, candidate.kit);
   }
   return projectUpdateApplyArgs(candidate.path, candidate.runtime, channel, candidate.kit);
@@ -732,7 +778,12 @@ async function askDeepScanRoots() {
   return [await askDirectory(ui("deepScanRootsPrompt"), { root: homedir() })];
 }
 
-function buildUpdateCandidates(discovery, globalInstalls) {
+function buildUpdateCandidates(
+  discovery,
+  globalInstalls,
+  piProfiles = [],
+  claimedProfileRuntimes = new Set(),
+) {
   const projects = discovery.projects.flatMap((project) => project.installs.map(({ kit, runtime }) => ({
     ...project,
     id: `${project.id}:${kit}:${runtime}`,
@@ -745,16 +796,40 @@ function buildUpdateCandidates(discovery, globalInstalls) {
       kit: kitName(kit),
     }),
   })));
+  const profileCandidates = piProfiles.map((profile) => ({
+    id: `profile:${profile.runtime}:${profile.id}`,
+    kind: "profile",
+    kit: "engineer",
+    runtime: profile.runtime,
+    runtimes: [profile.runtime],
+    profile,
+    ...piProfileProcessOptions(profile),
+    label: ui("piProfileCandidate", {
+      profile: profile.id,
+      runtime: profile.runtime,
+    }),
+  }));
+  const ordinaryGlobalInstalls = globalInstalls
+    .map((install) => install.kit === "engineer"
+      ? {
+        ...install,
+        runtimes: install.runtimes.filter((runtime) => !claimedProfileRuntimes.has(runtime)),
+      }
+      : install)
+    .filter((install) => install.runtimes.length > 0);
   return {
     registered: projects.filter((project) => project.sources.includes("registry")),
     unregistered: projects.filter((project) => !project.sources.includes("registry")),
-    other: globalInstalls.map(({ kit, runtimes }) => ({
-      id: `global:${kit}`,
-      kind: "global",
-      kit,
-      runtimes,
-      label: ui("globalCandidate", { kit: kitName(kit), runtimes: runtimes.join(", ") }),
-    })),
+    other: [
+      ...profileCandidates,
+      ...ordinaryGlobalInstalls.map(({ kit, runtimes }) => ({
+        id: `global:${kit}`,
+        kind: "global",
+        kit,
+        runtimes,
+        label: ui("globalCandidate", { kit: kitName(kit), runtimes: runtimes.join(", ") }),
+      })),
+    ],
   };
 }
 
@@ -779,7 +854,7 @@ function printUpdateInventory(groups) {
 }
 
 function orderUpdateCandidates(candidates) {
-  const priority = { global: 0, project: 1 };
+  const priority = { profile: 0, global: 1, project: 2 };
   return [...candidates].sort((left, right) => priority[left.kind] - priority[right.kind]);
 }
 
@@ -804,7 +879,46 @@ async function loadUpdateInventory(commandOptions, deepScanRoots) {
     supportedRuntimes: UPDATE_TARGETS,
     kits: KITS,
   });
-  return { discovery, groups: buildUpdateCandidates(discovery, globalInstalls) };
+  const profileRuntimeInstalls = new Set(globalInstalls
+    .filter((install) => install.kit === "engineer")
+    .flatMap((install) => install.runtimes)
+    .filter((runtime) => runtime === "pi" || runtime === "omp"));
+  let updateableProfiles = [];
+  const claimedProfileRuntimes = new Set();
+  try {
+    const inventory = await runCapture(piProfileManager.binary, [
+      ...piProfileManager.prefixArgs,
+      "profiles", "list", "--json",
+    ]);
+    const profiles = parsePiProfileInventory(inventory.stdout);
+    for (const profile of profiles.filter((profile) => profile.agentkitEnabled)) {
+      claimedProfileRuntimes.add(profile.runtime);
+    }
+    const classified = classifyPiProfiles(profiles);
+    updateableProfiles = classified.updateable;
+    for (const profile of classified.skipped) {
+      discovery.warnings.push(ui("piProfileSkipped", {
+        profile: profile.id,
+        reason: !profile.agentkitEnabled
+          ? ui("piProfileNoAgentKit")
+          : ui("piProfileNotSafe"),
+      }));
+    }
+  } catch (error) {
+    if (error.code !== "ENOENT") {
+      for (const runtime of profileRuntimeInstalls) claimedProfileRuntimes.add(runtime);
+      discovery.warnings.push(ui("piProfileDiscoveryUnavailable", { message: error.message }));
+    }
+  }
+  return {
+    discovery,
+    groups: buildUpdateCandidates(
+      discovery,
+      globalInstalls,
+      updateableProfiles,
+      claimedProfileRuntimes,
+    ),
+  };
 }
 
 async function updateAll(commandOptions, allowBack = false) {
@@ -847,8 +961,9 @@ async function updateAll(commandOptions, allowBack = false) {
           { label: ui("chooseUpdates"), value: "choose" },
           { label: ui("customDeepScanAction"), value: "custom-deep-scan" },
         ];
-        if (allowBack) actionChoices.push({ label: ui("updateAllBack"), value: BACK });
-        const action = await choose(ui("selectUpdateAll"), actionChoices);
+        const action = allowBack
+          ? await chooseWithBack(ui("selectUpdateAll"), actionChoices, 0, ui("escapeBack"))
+          : await choose(ui("selectUpdateAll"), actionChoices);
         if (action === BACK) break;
         if (action === "custom-deep-scan") {
           scanBaselinePaths = new Set(projectCandidates.map((candidate) => candidate.path));
@@ -871,10 +986,12 @@ async function updateAll(commandOptions, allowBack = false) {
           ui("backFromTargetSelection"),
         );
         if (ids === BACK) continue;
-        const selectedAction = await choose(ui("confirmSelectedUpdates", { count: ids.length }), [
-          { label: ui("previewSelectedUpdates", { count: ids.length }), value: "continue" },
-          { label: ui("back"), value: BACK },
-        ]);
+        const selectedAction = await chooseWithBack(
+          ui("confirmSelectedUpdates", { count: ids.length }),
+          [{ label: ui("previewSelectedUpdates", { count: ids.length }), value: "continue" }],
+          0,
+          ui("escapeBack"),
+        );
         if (selectedAction === BACK) continue;
         selected = candidates.filter((candidate) => ids.includes(candidate.id));
       }
@@ -884,7 +1001,7 @@ async function updateAll(commandOptions, allowBack = false) {
     if (!selected) continue;
     if (selected.length === 0) throw new Error(ui("noUpdateCandidates"));
     selected = orderUpdateCandidates(selected);
-    if (selected.some((candidate) => candidate.kind === "global")) {
+    if (selected.some((candidate) => candidate.kind === "global" || candidate.kind === "profile")) {
       warning(ui("globalUpdateSafety"));
     }
     if (channel === "beta" && selected.length > 0) {
@@ -895,10 +1012,12 @@ async function updateAll(commandOptions, allowBack = false) {
     printSection(ui("updateAllPreview"));
     for (const candidate of selected) {
       process.stdout.write(`\n${colorText(candidate.label, "target")}\n`);
-      await runAkCommand(updateAllPreviewArgs(candidate, channel));
+      await runAkCommand(updateAllPreviewArgs(candidate, channel), candidate);
     }
     printSection(ui("updateAllApplyPlan"));
-    for (const candidate of selected) printPlan(updateAllApplyArgs(candidate, channel));
+    for (const candidate of selected) {
+      printPlan(updateAllApplyArgs(candidate, channel), null, candidate.envOverrides);
+    }
     if (commandOptions.dryRun) {
       process.stdout.write(`\n${ui("dryRunFiles")}\n`);
       return;
@@ -913,7 +1032,7 @@ async function updateAll(commandOptions, allowBack = false) {
         total: selected.length,
         label: candidate.label,
       })}\n`);
-      await runAkCommand(updateAllApplyArgs(candidate, channel));
+      await runAkCommand(updateAllApplyArgs(candidate, channel), candidate);
     }
     process.stdout.write(`${ui("updateAllComplete")}\n`);
     return;
@@ -1006,7 +1125,10 @@ async function main() {
   const interactiveRoot = !options.command;
   const languageCanChange = interactiveRoot && !options.language;
   installedAkVersion = await ensureAk(akBinary);
-  if (interactiveRoot) showCurrentBinary();
+  if (interactiveRoot) {
+    showCurrentBinary();
+    await checkInteractiveBinaryUpdate();
+  }
   while (true) {
     if (!options.command) {
       const command = await chooseCommand(languageCanChange);

package/lib/commands.mjs

@@ -101,6 +101,27 @@ function quote(value) {
     : `'${value.replaceAll("'", `'\\''`)}'`;
 }
 
-export function formatCommand(binary, args) {
-  return [binary, ...args].map(quote).join(" ");
+function quotePowerShell(value) {
+  return /^[A-Za-z0-9_./:@=\\-]+$/.test(value)
+    ? value
+    : `'${value.replaceAll("'", "''")}'`;
+}
+
+export function formatCommand(binary, args, { platform = process.platform } = {}) {
+  const quoteValue = platform === "win32" ? quotePowerShell : quote;
+  return [binary, ...args].map(quoteValue).join(" ");
+}
+
+export function formatEnvironmentAssignments(
+  values,
+  { platform = process.platform } = {},
+) {
+  if (platform === "win32") {
+    return Object.entries(values)
+      .map(([name, value]) => `$env:${name} = ${quotePowerShell(String(value))};`)
+      .join(" ");
+  }
+  return Object.entries(values)
+    .map(([name, value]) => `${name}=${quote(String(value))}`)
+    .join(" ");
 }

package/lib/i18n.mjs

@@ -5,6 +5,12 @@ const messages = {
     languagePrompt: "Choose interface language / Chọn ngôn ngữ giao diện",
     commandPrompt: "What do you want to do?",
     currentBinary: "Current ak binary: {version} ({channel})",
+    checkingBinaryUpdate: "Checking for ak binary updates…",
+    checkedBinaryUpdate: "Checked ak binary updates.",
+    binaryUpdateAvailable: "UPDATE AVAILABLE: ak {current} → {latest} ({channel}). The update action is selected for you.",
+    binaryUpToDate: "UP TO DATE: ak {version} is the latest version on the {channel} channel.",
+    binaryUpdateStatusUnknown: "Could not determine binary update availability (status: {status}).",
+    binaryUpdateCheckFailed: "Could not check for ak binary updates: {message}. Continuing without blocking the helper.",
     installAction: "Install a Kit",
     updateAction: "Update a Kit",
     selfUpdateAction: "Update ak binary",
@@ -12,6 +18,7 @@ const messages = {
     exportAction: "Export Kit (not a runtime install)",
     doctorAction: "Run health checks",
     backToLanguage: "← Back to interface language",
+    escapeBack: "Esc: Back",
     chooseProject: "Choose a project directory",
     currentProjectScope: "Use current project ({path})",
     globalScope: "Use user/global Kit scope",
@@ -84,12 +91,17 @@ const messages = {
     unregisteredProjects: "Other discovered projects:",
     otherInstalls: "Global scope:",
     globalCandidate: "{kit} global scope ({runtimes})",
+    piProfileCandidate: "Engineer Kit — {runtime} profile: {profile}",
+    piProfileSkipped: "Pi Profile Manager skipped {profile}: {reason}",
+    piProfileNoAgentKit: "AgentKit is not enabled",
+    piProfileNotSafe: "profile is unmanaged, unhealthy, or drifted",
+    piProfileDiscoveryUnavailable: "Pi profile discovery is unavailable: {message}",
     projectCandidate: "{name} — {kit} ({runtime}) — {path}",
     selectUpdateAll: "Select what to update (Space toggles, Enter confirms)",
     updateEverything: "Update all discovered Kit installs: global + projects ({count})",
     updateAllProjects: "Update projects only ({count})",
     chooseUpdates: "Choose individual targets…",
-    backFromTargetSelection: "← Back (select with Space, then confirm with Enter)",
+    backFromTargetSelection: "Esc: Back",
     confirmSelectedUpdates: "What should happen with the {count} selected target(s)?",
     previewSelectedUpdates: "Continue to preview ({count})",
     noProjectsInRegistry: "No updateable registered projects were found.",
@@ -128,6 +140,12 @@ const messages = {
     languagePrompt: "Chọn ngôn ngữ giao diện / Choose interface language",
     commandPrompt: "Bạn muốn làm gì?",
     currentBinary: "ak binary hiện tại: {version} ({channel})",
+    checkingBinaryUpdate: "Đang kiểm tra bản cập nhật ak binary…",
+    checkedBinaryUpdate: "Đã kiểm tra cập nhật ak binary.",
+    binaryUpdateAvailable: "CÓ BẢN MỚI: ak {current} → {latest} ({channel}). Helper đã focus sẵn action cập nhật.",
+    binaryUpToDate: "ĐÃ LÀ BẢN MỚI NHẤT: ak {version} trên channel {channel}.",
+    binaryUpdateStatusUnknown: "Không thể xác định trạng thái cập nhật binary (status: {status}).",
+    binaryUpdateCheckFailed: "Không thể kiểm tra cập nhật ak binary: {message}. Helper vẫn tiếp tục hoạt động.",
     installAction: "Cài Kit",
     updateAction: "Cập nhật Kit",
     selfUpdateAction: "Cập nhật ak binary",
@@ -135,6 +153,7 @@ const messages = {
     exportAction: "Export Kit (không cài vào runtime)",
     doctorAction: "Chạy health check",
     backToLanguage: "← Quay lại chọn ngôn ngữ",
+    escapeBack: "Esc: Quay lại",
     chooseProject: "Chọn thư mục project",
     currentProjectScope: "Dùng project hiện tại ({path})",
     globalScope: "Dùng Kit ở scope user/global",
@@ -207,12 +226,17 @@ const messages = {
     unregisteredProjects: "Project khác đã discover:",
     otherInstalls: "Global scope:",
     globalCandidate: "{kit} global scope ({runtimes})",
+    piProfileCandidate: "Engineer Kit — profile {runtime}: {profile}",
+    piProfileSkipped: "Pi Profile Manager bỏ qua {profile}: {reason}",
+    piProfileNoAgentKit: "chưa bật AgentKit",
+    piProfileNotSafe: "profile không được quản lý, không healthy hoặc đã drift",
+    piProfileDiscoveryUnavailable: "Không thể discover Pi profile: {message}",
     projectCandidate: "{name} — {kit} ({runtime}) — {path}",
     selectUpdateAll: "Chọn mục cần update (Space bật/tắt, Enter xác nhận)",
     updateEverything: "Update mọi Kit đã detect: global + project ({count})",
     updateAllProjects: "Chỉ update các project đã discover ({count})",
     chooseUpdates: "Chọn từng target…",
-    backFromTargetSelection: "← Quay lại (nhấn Space rồi Enter)",
+    backFromTargetSelection: "Esc: Quay lại",
     confirmSelectedUpdates: "Xử lý thế nào với {count} target đã chọn?",
     previewSelectedUpdates: "Tiếp tục preview ({count})",
     noProjectsInRegistry: "Không tìm thấy registered project nào có thể update.",

package/lib/pi-profiles.mjs

@@ -0,0 +1,102 @@
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { extname, isAbsolute, resolve, win32 } from "node:path";
+
+function validPath(value) {
+  return typeof value === "string" && (isAbsolute(value) || win32.isAbsolute(value));
+}
+
+export function piProfileManagerInvocation(
+  configuredBinary = "pi-profile-manager",
+  {
+    platform = process.platform,
+    home = homedir(),
+    fileExists = existsSync,
+    nodeBinary = process.execPath,
+  } = {},
+) {
+  if (platform !== "win32") return { binary: configuredBinary, prefixArgs: [] };
+
+  const extension = extname(configuredBinary).toLowerCase();
+  if ([".js", ".cjs", ".mjs"].includes(extension)) {
+    return { binary: nodeBinary, prefixArgs: [configuredBinary] };
+  }
+
+  const siblingModule = extension === ".cmd"
+    ? configuredBinary.slice(0, -extension.length) + ".mjs"
+    : null;
+  const managedModule = (platform === "win32" ? win32.resolve : resolve)(
+    home,
+    "bin",
+    "pi-profile-manager.mjs",
+  );
+  const modulePath = siblingModule && fileExists(siblingModule)
+    ? siblingModule
+    : (!configuredBinary.includes("/") && !configuredBinary.includes("\\") && fileExists(managedModule)
+      ? managedModule
+      : null);
+  return modulePath
+    ? { binary: nodeBinary, prefixArgs: [modulePath] }
+    : { binary: configuredBinary, prefixArgs: [] };
+}
+
+export function parsePiProfileInventory(output) {
+  const value = JSON.parse(output);
+  if (value?.schemaVersion !== 1 || !Array.isArray(value.profiles)) {
+    throw new Error("unsupported pi-profile-manager profile inventory contract");
+  }
+  const ids = new Set();
+  return value.profiles.map((profile) => {
+    const sessionIsValid = profile?.runtime === "omp"
+      ? profile.sessionDir === null
+      : validPath(profile?.sessionDir);
+    if (
+      !profile || typeof profile.id !== "string" || !profile.id.trim() ||
+      !["pi", "omp"].includes(profile.runtime) || !validPath(profile.agentDir) ||
+      !sessionIsValid || typeof profile.agentkitEnabled !== "boolean" ||
+      typeof profile.managed !== "boolean" || typeof profile.healthy !== "boolean"
+    ) {
+      throw new Error("invalid pi-profile-manager profile inventory entry");
+    }
+    if (ids.has(profile.id)) {
+      throw new Error("duplicate pi-profile-manager profile inventory entry");
+    }
+    ids.add(profile.id);
+    return {
+      id: profile.id,
+      runtime: profile.runtime,
+      agentDir: profile.agentDir,
+      sessionDir: profile.sessionDir,
+      agentkitEnabled: profile.agentkitEnabled,
+      managed: profile.managed,
+      healthy: profile.healthy,
+    };
+  });
+}
+
+export function piProfileProcessOptions(profile) {
+  if (profile.runtime === "omp") {
+    return {
+      envOverrides: { AGENTKIT_OMP_HOME: profile.agentDir },
+      envUnset: ["PI_CODING_AGENT_DIR", "PI_CODING_AGENT_SESSION_DIR", "OMP_HOME"],
+    };
+  }
+  return {
+    envOverrides: {
+      PI_CODING_AGENT_DIR: profile.agentDir,
+      PI_CODING_AGENT_SESSION_DIR: profile.sessionDir,
+    },
+    envUnset: ["AGENTKIT_OMP_HOME", "OMP_HOME"],
+  };
+}
+
+export function classifyPiProfiles(profiles) {
+  return {
+    updateable: profiles.filter((profile) => (
+      profile.agentkitEnabled && profile.managed && profile.healthy
+    )),
+    skipped: profiles.filter((profile) => !(
+      profile.agentkitEnabled && profile.managed && profile.healthy
+    )),
+  };
+}

package/lib/prompts.mjs

@@ -60,11 +60,31 @@ export async function choose(message, choices, defaultIndex = 0) {
   }));
 }
 
-export async function chooseWithBack(message, choices, defaultIndex = 0, backLabel = "← Back") {
-  return choose(message, [
-    ...choices,
-    { label: backLabel, value: BACK },
-  ], defaultIndex);
+async function escapeBack(prompt) {
+  let cancelKey = null;
+  const trackCancelKey = (chunk) => {
+    const input = String(chunk);
+    if (input === "\u001b") cancelKey = "escape";
+    if (input === "\u0003") cancelKey = "interrupt";
+  };
+  stdin.on("data", trackCancelKey);
+  try {
+    const value = await prompt();
+    if (!isCancel(value)) return value;
+    if (cancelKey === "escape") return BACK;
+    return unwrap(value);
+  } finally {
+    stdin.off("data", trackCancelKey);
+  }
+}
+
+export async function chooseWithBack(message, choices, defaultIndex = 0, backLabel = "Esc: Back") {
+  startSession();
+  return escapeBack(() => select({
+    message: highlightPrompt(`${message} · ${backLabel}`),
+    options: choices,
+    initialValue: choices[defaultIndex]?.value,
+  }));
 }
 
 export async function multiChoose(message, choices, initialValues = choices.map((choice) => choice.value)) {
@@ -81,13 +101,15 @@ export async function multiChooseWithBack(
   message,
   choices,
   initialValues = choices.map((choice) => choice.value),
-  backLabel = "← Back (select with Space, then confirm with Enter)",
+  backLabel = "Esc: Back",
 ) {
-  const values = await multiChoose(message, [
-    ...choices,
-    { label: backLabel, value: BACK },
-  ], initialValues);
-  return values.includes(BACK) ? BACK : values;
+  startSession();
+  return escapeBack(() => multiselect({
+    message: highlightPrompt(`${message} · ${backLabel}`),
+    options: choices,
+    initialValues,
+    required: true,
+  }));
 }
 
 export async function ask(message) {

package/lib/runner.mjs

@@ -1,4 +1,12 @@
 import { spawn } from "node:child_process";
+import { extname } from "node:path";
+
+export function spawnInvocation(binary, args, platform = process.platform) {
+  if (platform === "win32" && [".js", ".cjs", ".mjs"].includes(extname(binary).toLowerCase())) {
+    return { binary: process.execPath, args: [binary, ...args] };
+  }
+  return { binary, args };
+}
 
 function jsonErrorMessage(output) {
   const candidates = [output, ...String(output).split("\n").reverse()];
@@ -56,13 +64,24 @@ export function requiresForceConsent(error) {
     /--force/i.test(diagnostic);
 }
 
-export function run(binary, args, { cwd = process.cwd(), stdio = "inherit" } = {}) {
+function childEnv(envOverrides = {}, envUnset = []) {
+  const env = { ...process.env, ...envOverrides };
+  for (const name of envUnset) delete env[name];
+  return env;
+}
+
+export function run(
+  binary,
+  args,
+  { cwd = process.cwd(), stdio = "inherit", envOverrides = {}, envUnset = [] } = {},
+) {
   return new Promise((resolve, reject) => {
-    const child = spawn(binary, args, {
+    const invocation = spawnInvocation(binary, args);
+    const child = spawn(invocation.binary, invocation.args, {
       cwd,
       stdio,
       shell: false,
-      env: process.env,
+      env: childEnv(envOverrides, envUnset),
     });
     child.once("error", (error) => {
       error.command = { binary, args: [...args], cwd };
@@ -87,13 +106,18 @@ export function run(binary, args, { cwd = process.cwd(), stdio = "inherit" } = {
   });
 }
 
-export function runCapture(binary, args, { cwd = process.cwd() } = {}) {
+export function runCapture(
+  binary,
+  args,
+  { cwd = process.cwd(), envOverrides = {}, envUnset = [] } = {},
+) {
   return new Promise((resolve, reject) => {
-    const child = spawn(binary, args, {
+    const invocation = spawnInvocation(binary, args);
+    const child = spawn(invocation.binary, invocation.args, {
       cwd,
       stdio: ["ignore", "pipe", "pipe"],
       shell: false,
-      env: process.env,
+      env: childEnv(envOverrides, envUnset),
     });
     let stdout = "";
     let stderr = "";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thieung/agentkit-helper",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Community helper for installing and updating AgentKit kits by runtime and channel",
   "type": "module",
   "bin": {