@paradigma-inc/flywheel 0.1.84 → 0.1.86

package/src/completion-install.mjs

@@ -0,0 +1,680 @@
+import {
+  mkdir,
+  readFile,
+  rename,
+  rm,
+  unlink,
+  writeFile,
+} from "node:fs/promises";
+import path from "node:path";
+
+import { generateCompletionScript as generateUsageCompletionScript } from "./completion.mjs";
+
+const SUPPORTED_INSTALL_SHELLS = [
+  "bash",
+  "zsh",
+  "fish",
+  "powershell",
+  "nu",
+  "nushell",
+];
+
+const SUPPORTED_INSTALL_SHELL_LIST = SUPPORTED_INSTALL_SHELLS.join(", ");
+
+export const MANAGED_COMPLETION_MARKER = [
+  "# Generated by `flywheel completion install`; do not edit this file directly.",
+  "# Re-run `flywheel completion install <shell>` to refresh it.",
+].join("\n");
+
+const PROFILE_BLOCK_START = "# >>> flywheel completion >>>";
+const PROFILE_BLOCK_OWNER = "# managed by `flywheel completion install`";
+const PROFILE_BLOCK_END = "# <<< flywheel completion <<<";
+
+function pathForPlatform(platform = process.platform) {
+  return platform === "win32" ? path.win32 : path;
+}
+
+function homeDir(env, platform) {
+  const home =
+    platform === "win32"
+      ? env.USERPROFILE || env.HOME
+      : env.HOME || env.USERPROFILE;
+  if (!home) {
+    throw new Error(
+      "HOME or USERPROFILE is required to resolve completion paths.",
+    );
+  }
+  return home;
+}
+
+function xdgDataHome(env, platform, pathApi) {
+  if (platform === "win32") {
+    return (
+      env.APPDATA || pathApi.join(homeDir(env, platform), "AppData", "Roaming")
+    );
+  }
+  return (
+    env.XDG_DATA_HOME || pathApi.join(homeDir(env, platform), ".local", "share")
+  );
+}
+
+function xdgConfigHome(env, platform, pathApi) {
+  if (platform === "win32") {
+    return (
+      env.APPDATA || pathApi.join(homeDir(env, platform), "AppData", "Roaming")
+    );
+  }
+  return env.XDG_CONFIG_HOME || pathApi.join(homeDir(env, platform), ".config");
+}
+
+function resolveDirectory(value, cwd, pathApi) {
+  return pathApi.isAbsolute(value) ? value : pathApi.resolve(cwd, value);
+}
+
+function pathsEqual(left, right, platform, pathApi) {
+  const normalizedLeft = pathApi.normalize(left);
+  const normalizedRight = pathApi.normalize(right);
+  return platform === "win32"
+    ? normalizedLeft.toLowerCase() === normalizedRight.toLowerCase()
+    : normalizedLeft === normalizedRight;
+}
+
+function readFileIfPresent(filePath) {
+  return readFile(filePath, "utf8").catch((error) => {
+    if (error && error.code === "ENOENT") return null;
+    throw error;
+  });
+}
+
+function escapeDoubleQuotedShell(value) {
+  return String(value).replace(/(["\\$`])/g, "\\$1");
+}
+
+function escapeSingleQuoted(value) {
+  return String(value).replaceAll("'", "''");
+}
+
+function escapeFishSingleQuoted(value) {
+  return String(value).replace(/([\\'])/g, "\\$1");
+}
+
+function quoteNuString(value) {
+  const text = String(value);
+  let hashes = "#";
+  while (text.includes(`'${hashes}`)) {
+    hashes += "#";
+  }
+  return `r${hashes}'${text}'${hashes}`;
+}
+
+function ensureTrailingNewline(value) {
+  return value.endsWith("\n") ? value : `${value}\n`;
+}
+
+function quoteCliHintArgument(value) {
+  const text = String(value);
+  if (/^[A-Za-z0-9_/:=+.,@%-]+$/.test(text)) {
+    return text;
+  }
+  return `'${text.replaceAll("'", "'\\''")}'`;
+}
+
+function profileUpdateHintCommand({ shell, target, requestedDir }) {
+  const commandParts = [
+    "flywheel",
+    "completion",
+    "install",
+    quoteCliHintArgument(shell),
+  ];
+  if (requestedDir) {
+    commandParts.push("--dir", quoteCliHintArgument(target.dir));
+  }
+  commandParts.push("--update-profile", "--yes");
+  return commandParts.join(" ");
+}
+
+function renderProfileBlock(blockText) {
+  return [
+    PROFILE_BLOCK_START,
+    PROFILE_BLOCK_OWNER,
+    ensureTrailingNewline(blockText).trimEnd(),
+    PROFILE_BLOCK_END,
+    "",
+  ].join("\n");
+}
+
+async function writeFileAtomically(filePath, text, pathApi) {
+  const dir = pathApi.dirname(filePath);
+  const base = pathApi.basename(filePath);
+  const tempPath = pathApi.join(
+    dir,
+    `.${base}.${process.pid}.${Date.now()}.tmp`,
+  );
+  await mkdir(dir, { recursive: true });
+  try {
+    await writeFile(tempPath, text);
+    await rename(tempPath, filePath);
+  } catch (error) {
+    await rm(tempPath, { force: true }).catch(() => {});
+    throw error;
+  }
+}
+
+async function applyProfileInstall({ profilePath, blockText, pathApi }) {
+  const existing = await readFileIfPresent(profilePath);
+  await mkdir(pathApi.dirname(profilePath), { recursive: true });
+  await writeFile(
+    profilePath,
+    upsertManagedProfileBlock(existing ?? "", blockText),
+  );
+}
+
+async function applyProfileUninstall(profilePath) {
+  const existing = await readFileIfPresent(profilePath);
+  if (existing === null) return;
+  await writeFile(profilePath, removeManagedProfileBlock(existing));
+}
+
+async function confirmProfileChange({
+  confirmProfileUpdate,
+  shell,
+  profilePath,
+  action,
+}) {
+  if (!confirmProfileUpdate) {
+    return false;
+  }
+  return await confirmProfileUpdate({
+    shell,
+    profilePath,
+    action,
+    message:
+      action === "install"
+        ? `Update ${shell} profile file at ${profilePath}?`
+        : `Remove Flywheel completion block from ${profilePath}?`,
+    default: false,
+  });
+}
+
+function defaultWriters({ stdout, stderr }) {
+  return {
+    writeStdout: stdout ?? ((chunk) => process.stdout.write(chunk)),
+    writeStderr: stderr ?? ((chunk) => process.stderr.write(chunk)),
+  };
+}
+
+function generatorOptionsForShell(shell) {
+  return {
+    shell,
+    includeBashCompletionLib: shell === "bash",
+  };
+}
+
+function defaultCompletionInstallDir({ shell, env, platform, pathApi }) {
+  const dataHome = xdgDataHome(env, platform, pathApi);
+  const configHome = xdgConfigHome(env, platform, pathApi);
+  if (shell === "bash") {
+    return pathApi.join(
+      env.BASH_COMPLETION_USER_DIR || pathApi.join(dataHome, "bash-completion"),
+      "completions",
+    );
+  }
+  if (shell === "zsh") {
+    return pathApi.join(dataHome, "zsh", "site-functions");
+  }
+  if (shell === "fish") {
+    return pathApi.join(configHome, "fish", "completions");
+  }
+  if (shell === "powershell") {
+    return platform === "win32"
+      ? pathApi.join(dataHome, "Flywheel", "Completions")
+      : pathApi.join(dataHome, "flywheel", "completions");
+  }
+  return pathApi.join(configHome, "nushell", "autoload");
+}
+
+function resolveTargetAndProfile({ shell, dir, env, platform, cwd }) {
+  const target = resolveCompletionInstallTarget({
+    shell,
+    dir,
+    env,
+    platform,
+    cwd,
+  });
+  const profile = resolveProfileUpdate({
+    shell: target.shell,
+    completionPath: target.path,
+    completionDir: target.dir,
+    defaultTarget: target.defaultTarget,
+    env,
+    platform,
+  });
+  return { target, profile };
+}
+
+function assertNonInteractiveProfileAllowed({
+  updateProfile,
+  dryRun,
+  yes,
+  isInteractive,
+  profile,
+}) {
+  if (
+    updateProfile === true &&
+    dryRun !== true &&
+    yes !== true &&
+    isInteractive !== true &&
+    profile.required
+  ) {
+    throw new Error("--update-profile requires --yes in non-interactive mode");
+  }
+}
+
+export function normalizeInstallShell(value) {
+  if (value === "nushell") {
+    return "nu";
+  }
+  if (SUPPORTED_INSTALL_SHELLS.includes(value)) {
+    return value;
+  }
+  throw new Error(
+    `Unsupported shell "${value}". Supported shells: ${SUPPORTED_INSTALL_SHELL_LIST}.`,
+  );
+}
+
+export function completionInstallFileName(shell) {
+  switch (normalizeInstallShell(shell)) {
+    case "bash":
+      return "flywheel";
+    case "zsh":
+      return "_flywheel";
+    case "fish":
+      return "flywheel.fish";
+    case "powershell":
+      return "flywheel.ps1";
+    case "nu":
+      return "flywheel.nu";
+    default:
+      throw new Error(`Unsupported shell "${shell}".`);
+  }
+}
+
+export function resolveCompletionInstallTarget({
+  shell,
+  dir,
+  env = process.env,
+  platform = process.platform,
+  cwd = process.cwd(),
+} = {}) {
+  const normalizedShell = normalizeInstallShell(shell);
+  const pathApi = pathForPlatform(platform);
+  const fileName = completionInstallFileName(normalizedShell);
+  const defaultTargetDir = defaultCompletionInstallDir({
+    shell: normalizedShell,
+    env,
+    platform,
+    pathApi,
+  });
+  if (dir) {
+    const resolvedDir = resolveDirectory(String(dir), cwd, pathApi);
+    return {
+      shell: normalizedShell,
+      path: pathApi.join(resolvedDir, fileName),
+      dir: resolvedDir,
+      defaultTarget: pathsEqual(
+        resolvedDir,
+        defaultTargetDir,
+        platform,
+        pathApi,
+      ),
+    };
+  }
+
+  return {
+    shell: normalizedShell,
+    path: pathApi.join(defaultTargetDir, fileName),
+    dir: defaultTargetDir,
+    defaultTarget: true,
+  };
+}
+
+export function resolveProfileUpdate({
+  shell,
+  completionPath,
+  completionDir,
+  defaultTarget,
+  env = process.env,
+  platform = process.platform,
+} = {}) {
+  const normalizedShell = normalizeInstallShell(shell);
+  const pathApi = pathForPlatform(platform);
+  const home = homeDir(env, platform);
+  const configHome = xdgConfigHome(env, platform, pathApi);
+
+  if (normalizedShell === "fish" && defaultTarget) {
+    return { required: false, message: "No profile update required for fish." };
+  }
+  if (normalizedShell === "fish") {
+    const escapedCompletionDir = escapeFishSingleQuoted(completionDir);
+    return {
+      required: true,
+      profilePath: pathApi.join(configHome, "fish", "config.fish"),
+      blockText: `if not contains -- '${escapedCompletionDir}' $fish_complete_path\n  set -a fish_complete_path '${escapedCompletionDir}'\nend\n`,
+    };
+  }
+  if (normalizedShell === "nu" && defaultTarget) {
+    return {
+      required: false,
+      message: "No profile update required for nu autoload target.",
+    };
+  }
+  if (normalizedShell === "bash") {
+    const escaped = escapeDoubleQuotedShell(completionPath);
+    return {
+      required: true,
+      profilePath: pathApi.join(home, ".bashrc"),
+      blockText: `if [ -f "${escaped}" ]; then\n  . "${escaped}"\nfi\n`,
+    };
+  }
+  if (normalizedShell === "zsh") {
+    return {
+      required: true,
+      profilePath: pathApi.join(env.ZDOTDIR || home, ".zshrc"),
+      blockText: `fpath=("${escapeDoubleQuotedShell(completionDir)}" $fpath)\nautoload -Uz compinit\ncompinit\n`,
+    };
+  }
+  if (normalizedShell === "powershell") {
+    const profilePath =
+      platform === "win32"
+        ? pathApi.join(home, "Documents", "PowerShell", "profile.ps1")
+        : pathApi.join(configHome, "powershell", "profile.ps1");
+    return {
+      required: true,
+      profilePath,
+      blockText: `. '${escapeSingleQuoted(completionPath)}'\n`,
+    };
+  }
+  return {
+    required: true,
+    profilePath:
+      platform === "win32"
+        ? pathApi.join(configHome, "nushell", "config.nu")
+        : pathApi.join(configHome, "nushell", "config.nu"),
+    blockText: `source ${quoteNuString(completionPath)}\n`,
+  };
+}
+
+export function buildManagedCompletionFile({ shell, generatedScript }) {
+  const normalizedShell = normalizeInstallShell(shell);
+  const script = ensureTrailingNewline(String(generatedScript));
+  if (normalizedShell !== "zsh" || !script.startsWith("#compdef")) {
+    return `${MANAGED_COMPLETION_MARKER}\n${script}`;
+  }
+  const firstLineEnd = script.indexOf("\n");
+  if (firstLineEnd === -1) {
+    return `${script}\n${MANAGED_COMPLETION_MARKER}\n`;
+  }
+  return `${script.slice(0, firstLineEnd + 1)}${MANAGED_COMPLETION_MARKER}\n${script.slice(firstLineEnd + 1)}`;
+}
+
+export function isManagedCompletionFile({ shell, text }) {
+  const normalizedShell = normalizeInstallShell(shell);
+  if (String(text).startsWith(MANAGED_COMPLETION_MARKER)) {
+    return true;
+  }
+  if (normalizedShell !== "zsh") {
+    return false;
+  }
+  const firstLineEnd = String(text).indexOf("\n");
+  if (firstLineEnd === -1) {
+    return false;
+  }
+  const firstLine = String(text).slice(0, firstLineEnd);
+  const remaining = String(text).slice(firstLineEnd + 1);
+  return (
+    firstLine.startsWith("#compdef") &&
+    remaining.startsWith(MANAGED_COMPLETION_MARKER)
+  );
+}
+
+export function upsertManagedProfileBlock(existingText, blockText) {
+  const renderedBlock = renderProfileBlock(blockText);
+  const start = existingText.indexOf(PROFILE_BLOCK_START);
+  if (start !== -1) {
+    const end = existingText.indexOf(PROFILE_BLOCK_END, start);
+    if (end === -1) {
+      throw new Error(
+        "Found an unterminated Flywheel completion profile block.",
+      );
+    }
+    let removeEnd = end + PROFILE_BLOCK_END.length;
+    if (existingText.slice(removeEnd, removeEnd + 2) === "\r\n") {
+      removeEnd += 2;
+    } else if (existingText[removeEnd] === "\n") {
+      removeEnd += 1;
+    }
+    return `${existingText.slice(0, start)}${renderedBlock}${existingText.slice(removeEnd)}`;
+  }
+
+  const separator =
+    existingText === "" || existingText.endsWith("\n") ? "" : "\n";
+  return `${existingText}${separator}${renderedBlock}`;
+}
+
+export function removeManagedProfileBlock(existingText) {
+  const start = existingText.indexOf(PROFILE_BLOCK_START);
+  if (start === -1) {
+    return existingText;
+  }
+  const end = existingText.indexOf(PROFILE_BLOCK_END, start);
+  if (end === -1) {
+    throw new Error("Found an unterminated Flywheel completion profile block.");
+  }
+  let removeEnd = end + PROFILE_BLOCK_END.length;
+  if (existingText.slice(removeEnd, removeEnd + 2) === "\r\n") {
+    removeEnd += 2;
+  } else if (existingText[removeEnd] === "\n") {
+    removeEnd += 1;
+  }
+  return `${existingText.slice(0, start)}${existingText.slice(removeEnd)}`;
+}
+
+export async function installCompletion({
+  shell,
+  dir,
+  force = false,
+  dryRun = false,
+  updateProfile = false,
+  yes = false,
+  isInteractive = process.stdin.isTTY === true && process.stdout.isTTY === true,
+  env = process.env,
+  platform = process.platform,
+  cwd = process.cwd(),
+  stdout,
+  stderr,
+  confirmProfileUpdate,
+  generateCompletionScript = generateUsageCompletionScript,
+} = {}) {
+  const normalizedShell = normalizeInstallShell(shell);
+  const pathApi = pathForPlatform(platform);
+  const { writeStderr } = defaultWriters({ stdout, stderr });
+  const { target, profile } = resolveTargetAndProfile({
+    shell: normalizedShell,
+    dir,
+    env,
+    platform,
+    cwd,
+  });
+
+  assertNonInteractiveProfileAllowed({
+    updateProfile,
+    dryRun,
+    yes,
+    isInteractive,
+    profile,
+  });
+
+  const existing = await readFileIfPresent(target.path);
+  if (
+    existing !== null &&
+    !isManagedCompletionFile({ shell: normalizedShell, text: existing }) &&
+    force !== true
+  ) {
+    throw new Error(
+      `Completion file already exists and is not managed by Flywheel: ${target.path}. Re-run with --force to replace it.`,
+    );
+  }
+
+  const generatedScript = await generateCompletionScript(
+    generatorOptionsForShell(normalizedShell),
+  );
+  const managedText = buildManagedCompletionFile({
+    shell: normalizedShell,
+    generatedScript,
+  });
+
+  if (dryRun) {
+    writeStderr(
+      `Would install ${normalizedShell} completion to ${target.path}\n`,
+    );
+    if (updateProfile && profile.required) {
+      writeStderr(`Would update profile file ${profile.profilePath}\n`);
+    } else if (updateProfile && !profile.required) {
+      writeStderr(`${profile.message}\n`);
+    }
+    return { shell: normalizedShell, path: target.path, dryRun: true };
+  }
+
+  await writeFileAtomically(target.path, managedText, pathApi);
+  writeStderr(`Installed ${normalizedShell} completion to ${target.path}\n`);
+
+  if (!updateProfile) {
+    if (profile.required) {
+      const command = profileUpdateHintCommand({
+        shell,
+        target,
+        requestedDir: dir,
+      });
+      writeStderr(
+        `Profile not updated. To enable profile wiring, run: ${command}\n`,
+      );
+    }
+    return { shell: normalizedShell, path: target.path };
+  }
+
+  if (!profile.required) {
+    writeStderr(`${profile.message}\n`);
+    return { shell: normalizedShell, path: target.path };
+  }
+
+  const shouldUpdate =
+    yes === true ||
+    (isInteractive === true &&
+      (await confirmProfileChange({
+        confirmProfileUpdate,
+        shell: normalizedShell,
+        profilePath: profile.profilePath,
+        action: "install",
+      })));
+  if (shouldUpdate) {
+    await applyProfileInstall({ ...profile, pathApi });
+    writeStderr(
+      `Updated ${normalizedShell} profile file at ${profile.profilePath}\n`,
+    );
+  } else {
+    writeStderr(`Profile not updated: ${profile.profilePath}\n`);
+  }
+  return { shell: normalizedShell, path: target.path };
+}
+
+export async function uninstallCompletion({
+  shell,
+  dir,
+  dryRun = false,
+  updateProfile = false,
+  yes = false,
+  isInteractive = process.stdin.isTTY === true && process.stdout.isTTY === true,
+  env = process.env,
+  platform = process.platform,
+  cwd = process.cwd(),
+  stdout,
+  stderr,
+  confirmProfileUpdate,
+} = {}) {
+  const normalizedShell = normalizeInstallShell(shell);
+  const { writeStderr } = defaultWriters({ stdout, stderr });
+  const { target, profile } = resolveTargetAndProfile({
+    shell: normalizedShell,
+    dir,
+    env,
+    platform,
+    cwd,
+  });
+
+  assertNonInteractiveProfileAllowed({
+    updateProfile,
+    dryRun,
+    yes,
+    isInteractive,
+    profile,
+  });
+
+  const existing = await readFileIfPresent(target.path);
+  if (
+    existing !== null &&
+    !isManagedCompletionFile({ shell: normalizedShell, text: existing })
+  ) {
+    throw new Error(
+      `Completion file exists but is not managed by Flywheel: ${target.path}. Refusing to remove it.`,
+    );
+  }
+
+  if (dryRun) {
+    writeStderr(
+      `Would remove ${normalizedShell} completion at ${target.path}\n`,
+    );
+    if (updateProfile && profile.required) {
+      writeStderr(`Would remove profile block from ${profile.profilePath}\n`);
+    } else if (updateProfile && !profile.required) {
+      writeStderr(`${profile.message}\n`);
+    }
+    return { shell: normalizedShell, path: target.path, dryRun: true };
+  }
+
+  if (existing !== null) {
+    await unlink(target.path);
+    writeStderr(`Removed ${normalizedShell} completion at ${target.path}\n`);
+  } else {
+    writeStderr(
+      `No managed ${normalizedShell} completion found at ${target.path}\n`,
+    );
+  }
+
+  if (!updateProfile) {
+    return { shell: normalizedShell, path: target.path };
+  }
+
+  if (!profile.required) {
+    writeStderr(`${profile.message}\n`);
+    return { shell: normalizedShell, path: target.path };
+  }
+
+  const shouldUpdate =
+    yes === true ||
+    (isInteractive === true &&
+      (await confirmProfileChange({
+        confirmProfileUpdate,
+        shell: normalizedShell,
+        profilePath: profile.profilePath,
+        action: "uninstall",
+      })));
+  if (shouldUpdate) {
+    await applyProfileUninstall(profile.profilePath);
+    writeStderr(
+      `Removed Flywheel completion block from ${profile.profilePath}\n`,
+    );
+  } else {
+    writeStderr(`Profile not updated: ${profile.profilePath}\n`);
+  }
+  return { shell: normalizedShell, path: target.path };
+}