@thieung/agentkit-helper 0.1.0

package/lib/github-issue.mjs

@@ -0,0 +1,137 @@
+import { homedir } from "node:os";
+import { spawn } from "node:child_process";
+
+export const DEFAULT_ISSUE_REPO = "thieung/agentkit-helper";
+
+export function resolveIssueRepository(env = process.env) {
+  const repository = (env.AK_HELPER_ISSUE_REPO || DEFAULT_ISSUE_REPO).trim();
+  if (!/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(repository)) {
+    throw new Error("AK_HELPER_ISSUE_REPO must use owner/repository format");
+  }
+  return repository;
+}
+
+export function issueUrl(repository = resolveIssueRepository()) {
+  return `https://github.com/${repository}/issues/new`;
+}
+
+export function isReportableAkError(error, akBinary = "ak") {
+  return error?.command?.binary === akBinary;
+}
+
+function replaceAllLiteral(value, needle, replacement) {
+  return needle ? value.split(needle).join(replacement) : value;
+}
+
+function isRedactablePath(value) {
+  return typeof value === "string" && value.length > 1;
+}
+
+export function redact(value, { cwd = process.cwd(), home = homedir() } = {}) {
+  let result = String(value ?? "");
+  if (isRedactablePath(cwd)) {
+    result = replaceAllLiteral(result, cwd, "$PROJECT");
+  }
+  if (isRedactablePath(home)) {
+    result = replaceAllLiteral(result, home, "$HOME");
+  }
+  result = result
+    .replace(/\b(?:gh[opusr]_[A-Za-z0-9_]+|github_pat_[A-Za-z0-9_]+|sk-[A-Za-z0-9_-]+)\b/g, "[REDACTED]")
+    .replace(/\b(Bearer)\s+\S+/gi, "$1 [REDACTED]")
+    .replace(/\b(token|api[_-]?key|secret|password)=\S+/gi, "$1=[REDACTED]");
+  return result;
+}
+
+export function buildIssueReport({ error, helperVersion, action, language, cwd = process.cwd() }) {
+  const exitCode = Number.isInteger(error?.exitCode) ? error.exitCode : 1;
+  const command = error?.command
+    ? [error.command.binary, ...error.command.args].join(" ")
+    : "Unavailable";
+  const safeAction = action || "startup";
+  const title = `[bug] ${safeAction} failed with exit ${exitCode}`;
+  const rawDiagnostics = [error?.stderr, error?.stdout].filter(Boolean).join("\n\n");
+  const redactedDiagnostics = rawDiagnostics
+    ? redact(rawDiagnostics, { cwd }).replaceAll("```", "` ` `")
+    : "";
+  const maxDiagnostics = 20_000;
+  const diagnostics = redactedDiagnostics.length > maxDiagnostics
+    ? `${redactedDiagnostics.slice(0, maxDiagnostics)}\n\n[diagnostics truncated]`
+    : redactedDiagnostics;
+  const body = `## Summary
+
+AgentKit Helper failed while running \`${safeAction}\`.
+
+## Diagnostics
+
+- Helper: ${helperVersion}
+- Node: ${process.version}
+- Platform: ${process.platform} ${process.arch}
+- UI language: ${language}
+- Exit code: ${exitCode}
+- Error: ${redact(error?.message || "Unknown error", { cwd })}
+- Command: \`${redact(command, { cwd })}\`
+
+${diagnostics ? `## Redacted ak diagnostics
+
+\`\`\`text
+${diagnostics}
+\`\`\`
+
+` : ""}## Privacy
+
+Verbose ak stdout/stderr is included only after redacting home/project paths and common credential formats. Diagnostics are capped at ${maxDiagnostics} characters.
+`;
+  return { title, body };
+}
+
+function runProcess(binary, args, { input = "" } = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(binary, args, {
+      shell: false,
+      stdio: ["pipe", "pipe", "pipe"],
+      env: process.env,
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (chunk) => { stdout += chunk; });
+    child.stderr.on("data", (chunk) => { stderr += chunk; });
+    child.once("error", reject);
+    child.once("exit", (code, signal) => {
+      if (signal || code !== 0) {
+        const error = new Error(stderr.trim() || `${binary} exited with status ${code}`);
+        error.exitCode = code || 1;
+        reject(error);
+        return;
+      }
+      resolve(stdout.trim());
+    });
+    child.stdin.end(input);
+  });
+}
+
+export async function checkIssueRepository({
+  repository = resolveIssueRepository(), ghBinary = "gh", execute = runProcess,
+} = {}) {
+  await execute(ghBinary, ["repo", "view", repository, "--json", "nameWithOwner"]);
+  return repository;
+}
+
+export async function findDuplicateIssue(report, {
+  repository = resolveIssueRepository(), ghBinary = "gh", execute = runProcess,
+} = {}) {
+  const output = await execute(ghBinary, [
+    "issue", "list", "--repo", repository, "--state", "all",
+    "--search", `\"${report.title}\" in:title`, "--limit", "1", "--json", "title,url",
+  ]);
+  const issues = JSON.parse(output || "[]");
+  return issues.find((issue) => issue.title === report.title) || null;
+}
+
+export async function createGitHubIssue(report, {
+  repository = resolveIssueRepository(), ghBinary = "gh", execute = runProcess,
+} = {}) {
+  return execute(ghBinary, [
+    "issue", "create", "--repo", repository,
+    "--title", report.title, "--body-file", "-",
+  ], { input: report.body });
+}

package/lib/i18n.mjs

@@ -0,0 +1,255 @@
+export const LANGUAGES = new Set(["vi", "en"]);
+
+const messages = {
+  en: {
+    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})",
+    installAction: "Install a Kit",
+    updateAction: "Update a Kit",
+    selfUpdateAction: "Update ak binary",
+    updateAllAction: "Update all detected AgentKit installs",
+    exportAction: "Export Kit (not a runtime install)",
+    doctorAction: "Run health checks",
+    backToLanguage: "← Back to interface language",
+    chooseProject: "Choose a project directory",
+    currentProjectScope: "Use current project ({path})",
+    globalScope: "Use user/global Kit scope",
+    binaryScope: "Update only the ak binary",
+    scopePrompt: "Where should AgentKit manage this Kit?",
+    unsafeCwd: "The current directory ({cwd}) is not used as project scope.",
+    projectDirectory: "Project directory",
+    kitPrompt: "Which Kit do you want to use?",
+    engineerKit: "Engineer Kit",
+    marketingKit: "Marketing Kit",
+    targetPrompt: "Which coding runtimes should receive {kit}?",
+    updateTargetPrompt: "Which installed runtimes should update {kit}?",
+    allRuntimes: "All supported runtimes",
+    dshUpdateUnsupported: "dsh — not supported by ak update",
+    exportTargetPrompt: "Export creates a copy; it does not install a runtime. Choose a format:",
+    savedTargetNeedsUpdateRuntime: "Saved project target {target} is install-only. Update supports {supported}. Re-run with --runtime <target> or choose interactively.",
+    agyExport: "agy (global-only export)",
+    portableExport: "portable (output directory)",
+    exportDirectory: "Export output directory",
+    channelPrompt: "Which release channel?",
+    back: "← Back",
+    installPlan: "Install plan:",
+    betaKitStableBinaryWarning: "WARNING: Installed ak {version} appears to be stable. Installing a beta Kit with --yes may update the ak binary to beta first.",
+    betaKitLifecycleReason: "AgentKit enforces this lifecycle check to satisfy the beta Kit's required CLI version.",
+    binaryPreviewPrerequisite: "A signed {channel} binary update to {version} is required before all selected Kit previews can run.",
+    applyBinaryPrerequisite: "Update ak binary now, then continue previewing the selected Kits?",
+    binaryPrerequisitePlan: "Binary prerequisite:",
+    binaryPrerequisiteDryRun: "Dry run stops here because Kit previews require the newer binary. No changes were applied.",
+    binaryPrerequisiteComplete: "Binary prerequisite complete. Continuing Kit previews with ak {version}.",
+    binaryPrerequisiteDeclined: "Binary update declined; Kit previews were not run.",
+    dryRunFiles: "Dry run complete; no files were changed.",
+    runAk: "Run this official ak command?",
+    globalForceWarning: "WARNING: ak blocked the {target} global install because the target already exists or drift was detected. Global runtime files may contain user-installed or modified Skills. --force may replace or remove them; AgentKit creates recovery snapshots, but manual review may still be required.",
+    projectForceWarning: "WARNING: ak blocked the {target} project install because the target already exists or drift was detected. --force may replace or remove modified files.",
+    confirmForceInstall: "Force reinstall this target after the warning above?",
+    forceInstallPlan: "Explicit force reinstall plan:",
+    forceInstallDeclined: "Force reinstall declined; the existing target was not overwritten.",
+    forceNeedsConsent: "Force reinstall requires a separate interactive confirmation; --yes does not grant overwrite consent.",
+    runningAkCommand: "Running the official ak command with verbose diagnostics…",
+    akCommandComplete: "Official ak command completed.",
+    cancelledFiles: "Cancelled; no files were changed.",
+    savedChoice: "Saved project choice: {path}",
+    installComplete: "Install complete. Restart the selected runtime, then invoke a Skill from the selected Kit.",
+    projectRegistrationFailed: "Install succeeded, but this project could not be added to the ak registry: {message}",
+    binaryCheck: "Binary update check:",
+    binaryVersions: "Installed: {current} | {channel} latest: {latest}",
+    binaryAlreadyCurrent: "The ak binary is already current for this channel.",
+    binaryDowngradeWarning: "WARNING: {channel} {latest} is older than the installed {current}. ak self-update does not downgrade.",
+    binaryDowngradeRisk: "Downgrading may make newer AgentKit state incompatible with the older CLI.",
+    downgradePlan: "Explicit downgrade plan using the official signed installer:",
+    confirmDowngrade: "Are you sure you want to replace {current} with the older {latest}?",
+    downgradeNeedsConsent: "Downgrade requires an interactive confirmation, or both --allow-downgrade and --yes.",
+    cancelledDowngrade: "Downgrade cancelled; the binary was not changed.",
+    downgradeComplete: "Downgrade complete. Installed ak version: {version}",
+    binaryNoChange: "The official updater completed without changing the binary.",
+    binaryPlan: "Binary update plan:",
+    dryRunBinary: "Dry run complete; the binary was not changed.",
+    applyBinary: "Apply the signed binary update?",
+    cancelledBinary: "Cancelled; the binary was not changed.",
+    binaryComplete: "Binary update complete.",
+    loadingRegistry: "Loading projects from the ak registry…",
+    loadedRegistry: "Loaded registered AgentKit projects.",
+    deepScanning: "Scanning the selected folder for AgentKit projects…",
+    deepScanComplete: "Project scan complete.",
+    customDeepScanAction: "Choose a project manually…",
+    deepScanResult: "Found {count} additional updateable project(s) in the selected folder.",
+    deepScanRootsPrompt: "Choose a parent directory to scan (type to filter, use arrows and Enter; not / or your whole home)",
+    inventory: "Detected update inventory:",
+    registeredProjects: "Projects from ak projects list:",
+    unregisteredProjects: "Other discovered projects:",
+    otherInstalls: "Global scope:",
+    globalCandidate: "{kit} global scope ({runtimes})",
+    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)",
+    confirmSelectedUpdates: "What should happen with the {count} selected target(s)?",
+    previewSelectedUpdates: "Continue to preview ({count})",
+    noProjectsInRegistry: "No updateable registered projects were found.",
+    updateAllBack: "← Back to release channel",
+    discoveryWarning: "Discovery warning: {message}",
+    noUpdateCandidates: "No updateable Engineer or Marketing Kit installs were detected.",
+    updateAllPreview: "Previewing selected updates:",
+    updateAllApplyPlan: "Update-all apply plan:",
+    applyAll: "Apply every selected update sequentially?",
+    updateProgress: "[{current}/{total}] Updating {label}",
+    cancelledAll: "Cancelled; no selected update was applied.",
+    updateAllComplete: "Selected updates completed. Restart the affected runtimes.",
+    updatePreview: "Kit update preview:",
+    globalUpdateSafety: "Global update is preserve-only: ak skips user-modified files, and the helper never adds --force.",
+    applyPlan: "Apply plan:",
+    applyKit: "Apply this Kit update?",
+    cancelledUpdate: "Cancelled; no update was applied.",
+    updateComplete: "Update complete. Restart the selected runtime and verify a Skill from the selected Kit.",
+    exportPlan: "Export plan:",
+    runExport: "Run this official ak export command?",
+    exportComplete: "Export complete.",
+    done: "Done",
+    promptCancelled: "Operation cancelled; no helper action was applied.",
+    error: "ERROR: {message}",
+    issuePreview: "A redacted GitHub issue report is ready:",
+    createIssue: "Create this issue in {repo}?",
+    issueSkipped: "GitHub issue was not created.",
+    issueDuplicate: "A matching issue already exists: {url}",
+    issueCreated: "GitHub issue created: {url}",
+    issueFailed: "Could not create the GitHub issue: {message}",
+    issueManual: "Report it manually: https://github.com/thieung/agentkit-helper/issues/new",
+    issueRepoUnavailable: "GitHub issue reporting is unavailable because repository {repo} cannot be accessed.",
+    issueRepoSetup: "Publish that repository first, or set AK_HELPER_ISSUE_REPO=owner/repository.",
+  },
+  vi: {
+    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})",
+    installAction: "Cài Kit",
+    updateAction: "Cập nhật Kit",
+    selfUpdateAction: "Cập nhật ak binary",
+    updateAllAction: "Cập nhật mọi AgentKit install đã detect",
+    exportAction: "Export Kit (không cài vào runtime)",
+    doctorAction: "Chạy health check",
+    backToLanguage: "← Quay lại chọn ngôn ngữ",
+    chooseProject: "Chọn thư mục project",
+    currentProjectScope: "Dùng project hiện tại ({path})",
+    globalScope: "Dùng Kit ở scope user/global",
+    binaryScope: "Chỉ cập nhật binary ak",
+    scopePrompt: "AgentKit sẽ quản lý Kit này ở scope nào?",
+    unsafeCwd: "Thư mục hiện tại ({cwd}) không được dùng làm project scope.",
+    projectDirectory: "Thư mục project",
+    kitPrompt: "Bạn muốn dùng Kit nào?",
+    engineerKit: "Engineer Kit",
+    marketingKit: "Marketing Kit",
+    targetPrompt: "Các runtime nào sẽ nhận {kit}?",
+    updateTargetPrompt: "Các runtime nào sẽ cập nhật {kit}?",
+    allRuntimes: "Tất cả runtime được hỗ trợ",
+    dshUpdateUnsupported: "dsh — ak update chưa hỗ trợ",
+    exportTargetPrompt: "Export tạo một bản sao, không cài vào runtime. Chọn dạng export:",
+    savedTargetNeedsUpdateRuntime: "Target đã lưu của project là {target} và chỉ dùng cho install. Update chỉ hỗ trợ {supported}. Hãy chạy lại với --runtime <target> hoặc chọn lại trong chế độ interactive.",
+    agyExport: "agy (chỉ export global)",
+    portableExport: "portable (chọn thư mục output)",
+    exportDirectory: "Thư mục output cho export",
+    channelPrompt: "Chọn release channel?",
+    back: "← Quay lại",
+    installPlan: "Kế hoạch cài đặt:",
+    betaKitStableBinaryWarning: "WARNING: ak {version} đang cài có vẻ là stable. Cài Kit beta với --yes có thể cập nhật ak binary sang beta trước.",
+    betaKitLifecycleReason: "AgentKit enforce lifecycle check này để đáp ứng CLI version mà Kit beta yêu cầu.",
+    binaryPreviewPrerequisite: "Cần cập nhật signed binary channel {channel} lên {version} trước khi preview đầy đủ các Kit đã chọn.",
+    applyBinaryPrerequisite: "Cập nhật ak binary ngay rồi tiếp tục preview các Kit đã chọn?",
+    binaryPrerequisitePlan: "Binary prerequisite:",
+    binaryPrerequisiteDryRun: "Dry run dừng tại đây vì Kit preview cần binary mới hơn. Chưa có thay đổi nào được áp dụng.",
+    binaryPrerequisiteComplete: "Đã cập nhật binary prerequisite. Tiếp tục preview Kit bằng ak {version}.",
+    binaryPrerequisiteDeclined: "Đã từ chối cập nhật binary; chưa chạy Kit preview.",
+    dryRunFiles: "Dry run hoàn tất; không có file nào bị thay đổi.",
+    runAk: "Chạy command ak chính thức này?",
+    globalForceWarning: "WARNING: ak đã chặn cài global cho {target} vì target đã tồn tại hoặc phát hiện drift. Global runtime có thể chứa Skill do user cài hoặc chỉnh sửa. --force có thể thay thế hoặc xóa các file này; AgentKit có tạo recovery snapshot nhưng vẫn có thể cần kiểm tra thủ công.",
+    projectForceWarning: "WARNING: ak đã chặn cài project cho {target} vì target đã tồn tại hoặc phát hiện drift. --force có thể thay thế hoặc xóa file đã chỉnh sửa.",
+    confirmForceInstall: "Vẫn force reinstall target này sau cảnh báo trên?",
+    forceInstallPlan: "Kế hoạch force reinstall đã được xác nhận:",
+    forceInstallDeclined: "Đã từ chối force reinstall; target hiện tại không bị ghi đè.",
+    forceNeedsConsent: "Force reinstall cần một xác nhận interactive riêng; --yes không đồng nghĩa cho phép ghi đè.",
+    runningAkCommand: "Đang chạy command ak chính thức với verbose diagnostics…",
+    akCommandComplete: "Command ak chính thức đã hoàn tất.",
+    cancelledFiles: "Đã hủy; không có file nào bị thay đổi.",
+    savedChoice: "Đã lưu lựa chọn project: {path}",
+    installComplete: "Cài đặt hoàn tất. Hãy khởi động lại runtime rồi gọi một Skill từ Kit đã chọn.",
+    projectRegistrationFailed: "Cài đặt thành công, nhưng chưa thể thêm project này vào ak registry: {message}",
+    binaryCheck: "Kiểm tra cập nhật binary:",
+    binaryVersions: "Đang cài: {current} | {channel} mới nhất: {latest}",
+    binaryAlreadyCurrent: "ak binary đã là bản hiện tại của channel này.",
+    binaryDowngradeWarning: "WARNING: {channel} {latest} thấp hơn bản đang cài {current}. ak self-update không downgrade.",
+    binaryDowngradeRisk: "Downgrade có thể khiến AgentKit state mới không tương thích với CLI cũ hơn.",
+    downgradePlan: "Kế hoạch downgrade tường minh bằng official signed installer:",
+    confirmDowngrade: "Bạn có chắc muốn thay {current} bằng bản thấp hơn {latest}?",
+    downgradeNeedsConsent: "Downgrade cần xác nhận interactive, hoặc dùng đồng thời --allow-downgrade và --yes.",
+    cancelledDowngrade: "Đã hủy downgrade; binary không bị thay đổi.",
+    downgradeComplete: "Downgrade hoàn tất. Phiên bản ak đang cài: {version}",
+    binaryNoChange: "Official updater hoàn tất nhưng không thay đổi binary.",
+    binaryPlan: "Kế hoạch cập nhật binary:",
+    dryRunBinary: "Dry run hoàn tất; binary không bị thay đổi.",
+    applyBinary: "Áp dụng bản cập nhật binary đã ký?",
+    cancelledBinary: "Đã hủy; binary không bị thay đổi.",
+    binaryComplete: "Cập nhật binary hoàn tất.",
+    loadingRegistry: "Đang tải project từ ak registry…",
+    loadedRegistry: "Đã tải các AgentKit project được đăng ký.",
+    deepScanning: "Đang tìm AgentKit project trong thư mục đã chọn…",
+    deepScanComplete: "Đã tìm project xong.",
+    customDeepScanAction: "Chọn project thủ công…",
+    deepScanResult: "Tìm thấy thêm {count} project có thể update trong thư mục đã chọn.",
+    deepScanRootsPrompt: "Chọn thư mục cha cần scan (gõ để lọc, dùng ↑/↓ và Enter; không dùng / hoặc toàn bộ home)",
+    inventory: "Danh sách update đã detect:",
+    registeredProjects: "Project từ ak projects list:",
+    unregisteredProjects: "Project khác đã discover:",
+    otherInstalls: "Global scope:",
+    globalCandidate: "{kit} global scope ({runtimes})",
+    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)",
+    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.",
+    updateAllBack: "← Quay lại chọn release channel",
+    discoveryWarning: "Cảnh báo discovery: {message}",
+    noUpdateCandidates: "Không detect được Engineer hoặc Marketing Kit install nào có thể update.",
+    updateAllPreview: "Đang preview các update đã chọn:",
+    updateAllApplyPlan: "Kế hoạch Update all:",
+    applyAll: "Áp dụng tuần tự mọi update đã chọn?",
+    updateProgress: "[{current}/{total}] Đang update {label}",
+    cancelledAll: "Đã hủy; chưa áp dụng update nào đã chọn.",
+    updateAllComplete: "Đã update xong các mục được chọn. Hãy khởi động lại runtime liên quan.",
+    updatePreview: "Xem trước cập nhật Kit:",
+    globalUpdateSafety: "Global update dùng preserve-only: ak bỏ qua file do user chỉnh sửa và helper không bao giờ thêm --force.",
+    applyPlan: "Kế hoạch áp dụng:",
+    applyKit: "Áp dụng bản cập nhật Kit này?",
+    cancelledUpdate: "Đã hủy; chưa áp dụng cập nhật.",
+    updateComplete: "Cập nhật hoàn tất. Hãy khởi động lại runtime và kiểm tra một Skill từ Kit đã chọn.",
+    exportPlan: "Kế hoạch export:",
+    runExport: "Chạy command export ak chính thức này?",
+    exportComplete: "Export hoàn tất.",
+    done: "Hoàn tất",
+    promptCancelled: "Đã hủy thao tác; helper chưa áp dụng thay đổi nào.",
+    error: "LỖI: {message}",
+    issuePreview: "Report GitHub issue đã được lọc thông tin nhạy cảm:",
+    createIssue: "Tạo issue này trong {repo}?",
+    issueSkipped: "Chưa tạo GitHub issue.",
+    issueDuplicate: "Đã có issue tương tự: {url}",
+    issueCreated: "Đã tạo GitHub issue: {url}",
+    issueFailed: "Không thể tạo GitHub issue: {message}",
+    issueManual: "Báo lỗi thủ công tại: https://github.com/thieung/agentkit-helper/issues/new",
+    issueRepoUnavailable: "Không thể report GitHub issue vì repository {repo} không truy cập được.",
+    issueRepoSetup: "Hãy publish repository đó trước, hoặc đặt AK_HELPER_ISSUE_REPO=owner/repository.",
+  },
+};
+
+export function t(language, key, values = {}) {
+  const template = messages[language]?.[key] ?? messages.en[key] ?? key;
+  return template.replace(/\{(\w+)\}/g, (_, name) => String(values[name] ?? `{${name}}`));
+}

package/lib/navigation.mjs

@@ -0,0 +1,22 @@
+export const BACK = Symbol("back");
+
+export async function walkSelections(steps) {
+  const values = {};
+  let index = 0;
+
+  while (index < steps.length) {
+    const step = steps[index];
+    const value = await step.select(values);
+    if (value === BACK) {
+      delete values[step.key];
+      if (index === 0) return BACK;
+      index -= 1;
+      delete values[steps[index].key];
+      continue;
+    }
+    values[step.key] = value;
+    index += 1;
+  }
+
+  return values;
+}

package/lib/project.mjs

@@ -0,0 +1,37 @@
+import { homedir } from "node:os";
+import { parse, resolve } from "node:path";
+import { realpath, stat } from "node:fs/promises";
+
+export function isUnsafeProjectPath(path, home = homedir()) {
+  const absolute = resolve(path);
+  return absolute === parse(absolute).root || absolute === resolve(home);
+}
+
+export async function resolveProjectPath(input, cwd = process.cwd(), home = homedir()) {
+  const project = resolve(input || cwd);
+  if (isUnsafeProjectPath(project, home)) {
+    throw new Error(
+      `not using ${project} as project scope; choose --project <path>, --global, or update --binary-only`,
+    );
+  }
+
+  let metadata;
+  try {
+    metadata = await stat(project);
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      throw new Error(`project directory does not exist: ${project}`);
+    }
+    throw error;
+  }
+  if (!metadata.isDirectory()) {
+    throw new Error(`project path is not a directory: ${project}`);
+  }
+  const canonicalProject = await realpath(project);
+  if (isUnsafeProjectPath(canonicalProject, home)) {
+    throw new Error(
+      `not using ${project} as project scope because it resolves to ${canonicalProject}`,
+    );
+  }
+  return canonicalProject;
+}

package/lib/prompts.mjs

@@ -0,0 +1,149 @@
+import {
+  cancel,
+  confirm as clackConfirm,
+  intro,
+  isCancel,
+  multiselect,
+  outro,
+  path as clackPath,
+  select,
+  spinner,
+  text,
+} from "@clack/prompts";
+import { stdin, stdout } from "node:process";
+import { colorText } from "./colors.mjs";
+import { BACK } from "./navigation.mjs";
+
+let sessionStarted = false;
+let promptCopy = {
+  intro: "AgentKit Helper",
+  cancelled: "Operation cancelled; no helper action was applied.",
+};
+
+export class PromptCancelledError extends Error {
+  constructor() {
+    super("interactive session cancelled");
+    this.name = "PromptCancelledError";
+  }
+}
+
+function requireTty() {
+  if (!stdin.isTTY || !stdout.isTTY) {
+    throw new Error("interactive input is unavailable; pass explicit flags and --yes");
+  }
+}
+
+function startSession() {
+  requireTty();
+  if (!sessionStarted) {
+    intro(promptCopy.intro);
+    sessionStarted = true;
+  }
+}
+
+function unwrap(value) {
+  if (!isCancel(value)) return value;
+  cancel(promptCopy.cancelled);
+  throw new PromptCancelledError();
+}
+
+function highlightPrompt(message) {
+  return colorText(message, "prompt");
+}
+
+export async function choose(message, choices, defaultIndex = 0) {
+  startSession();
+  return unwrap(await select({
+    message: highlightPrompt(message),
+    options: choices,
+    initialValue: choices[defaultIndex]?.value,
+  }));
+}
+
+export async function chooseWithBack(message, choices, defaultIndex = 0, backLabel = "← Back") {
+  return choose(message, [
+    ...choices,
+    { label: backLabel, value: BACK },
+  ], defaultIndex);
+}
+
+export async function multiChoose(message, choices, initialValues = choices.map((choice) => choice.value)) {
+  startSession();
+  return unwrap(await multiselect({
+    message: highlightPrompt(message),
+    options: choices,
+    initialValues,
+    required: true,
+  }));
+}
+
+export async function multiChooseWithBack(
+  message,
+  choices,
+  initialValues = choices.map((choice) => choice.value),
+  backLabel = "← Back (select with Space, then confirm with Enter)",
+) {
+  const values = await multiChoose(message, [
+    ...choices,
+    { label: backLabel, value: BACK },
+  ], initialValues);
+  return values.includes(BACK) ? BACK : values;
+}
+
+export async function ask(message) {
+  startSession();
+  const value = unwrap(await text({
+    message: highlightPrompt(message),
+    validate(input) {
+      if (!input.trim()) return `${message} is required`;
+    },
+  }));
+  return value.trim();
+}
+
+export async function askDirectory(message, { root = process.cwd() } = {}) {
+  startSession();
+  return unwrap(await clackPath({
+    message: highlightPrompt(message),
+    root,
+    initialValue: root,
+    directory: true,
+  }));
+}
+
+export function confirmPromptOptions(message, initialValue = true) {
+  return { message: highlightPrompt(message), initialValue };
+}
+
+export async function confirm(message, initialValue = true) {
+  startSession();
+  return unwrap(await clackConfirm(confirmPromptOptions(message, initialValue)));
+}
+
+export async function withSpinner(message, completeMessage, task) {
+  if (!stdin.isTTY || !stdout.isTTY) return task();
+  startSession();
+  const progress = spinner();
+  progress.start(highlightPrompt(message));
+  try {
+    const result = await task();
+    progress.stop(highlightPrompt(completeMessage));
+    return result;
+  } catch (error) {
+    progress.error(highlightPrompt(message));
+    throw error;
+  }
+}
+
+export function warning(message) {
+  const output = colorText(message, "warning", { stream: process.stderr });
+  process.stderr.write(`${output}\n`);
+}
+
+export function setPromptCopy(copy) {
+  promptCopy = { ...promptCopy, ...copy };
+}
+
+export function finishInteractive(message) {
+  if (sessionStarted) outro(message);
+}