@pithy-sh/cli 0.1.0

package/src/platform/editor.ts

@@ -0,0 +1,333 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { delimiter, join } from "node:path";
+import { NotFoundError, ValidationError } from "@pithy-sh/core/src/error/pithyError";
+
+/**
+ * The one place Pithy decides what "open this in your editor" means (#157).
+ *
+ * Three rules live here, and none of them looks like a rule at a call site — which is exactly why they
+ * belong at the thing being called rather than beside each caller:
+ *
+ * **The order is `$VISUAL`, then `$EDITOR`, then a platform default.** Both variables, in that order,
+ * because that is the convention every other tool an adopter uses already follows: `$EDITOR` is the
+ * line-editor fallback and `$VISUAL` is the full-screen one, so a developer whose `$EDITOR` is `ed` and
+ * whose `$VISUAL` is `nvim` means the second. The platform default is `notepad` on Windows and `nano`
+ * (else `vi`) elsewhere. Windows is half the reason this module exists: #131 was the same area, and the
+ * branch nobody has a host for is the branch nobody writes.
+ *
+ * **An editor that returns before the adopter has finished typing is refused, by name, with the flag to
+ * add.** `EDITOR=code` exits the moment the window opens. A caller that spawns it and waits gets
+ * control back in about forty milliseconds, validates a file nobody has touched yet, reports success,
+ * and — for a command that writes what came back — writes the unedited file over the edited one while
+ * the adopter is still typing into the window. There is no way to detect this after the fact: a
+ * fast-exiting editor and a fast adopter are indistinguishable. So it is caught before the spawn.
+ *
+ * The list below is an enumeration, and enumerations are the weaker kind of gate — but it is an
+ * enumeration of *fixes*, not of prohibitions. Each entry exists to name the flag, which is the only
+ * thing the adopter actually needs; an editor absent from it is not asserted to be safe, it is simply
+ * one Pithy has nothing helpful to say about. The invariant the gate states is in its name:
+ * {@link requireEditor} returns an editor that **blocks**.
+ *
+ * **A refusal, never a hang.** With no terminal there is no adopter to close the window, so a spawned
+ * editor in CI waits forever and takes the job's timeout with it. The refusal names the file's absolute
+ * path, in `message`: `detail` is stripped by the HTTP codec and never rendered to a terminal, and the
+ * path is the whole of what the operator can act on.
+ *
+ * A second command that opens an editor routes through here. `platform/editor.test.ts` has the gate
+ * that keeps that true — `$VISUAL` and `$EDITOR` are read in this file and nowhere else in the tree.
+ */
+
+/** Which environment variable named the editor, or that neither did. Named in every refusal. */
+export type EditorSource = "VISUAL" | "EDITOR" | "default";
+
+/** A resolved editor: what to spawn, what to pass it, and where it came from. */
+export interface ResolvedEditor {
+  /** The executable, with no arguments and no quotes — as spawned. */
+  readonly command: string;
+  /** The arguments that came with it, in order. The file is appended after these. */
+  readonly args: readonly string[];
+  /** Which of the two variables named it, or `default` when neither did. */
+  readonly source: EditorSource;
+}
+
+/** Injectable seams, so every branch is testable from any host. */
+export interface EditorEnvironment {
+  /** Environment map, defaulting to `process.env` — read for `VISUAL` and `EDITOR`. */
+  env?: NodeJS.ProcessEnv;
+  /** The platform, defaulting to `process.platform`. */
+  platform?: NodeJS.Platform;
+  /** Whether a command is on `PATH`, defaulting to a `PATH` walk. Only the POSIX default consults it. */
+  hasCommand?: (command: string) => boolean;
+  /** Whether a human is at the terminal, defaulting to stdin **and** stdout both being TTYs. */
+  interactive?: boolean;
+}
+
+/**
+ * Editors that open a window and return immediately, mapped to the flags that make them wait.
+ *
+ * The **first** flag is the one the refusal recommends; the rest are accepted spellings of the same
+ * thing. Keys are matched against the command's base name, lowercased and with a Windows extension
+ * removed, so `/usr/local/bin/code`, `Code.EXE` and `code` are one editor.
+ */
+const WAIT_FLAGS: Record<string, readonly string[]> = {
+  atom: ["--wait", "-w"],
+  code: ["--wait", "-w"],
+  "code-insiders": ["--wait", "-w"],
+  codium: ["--wait", "-w"],
+  cursor: ["--wait", "-w"],
+  fleet: ["--wait", "-w"],
+  goland: ["--wait", "-w"],
+  gvim: ["-f", "--nofork"],
+  idea: ["--wait", "-w"],
+  mate: ["-w", "--wait"],
+  mvim: ["-f", "--nofork"],
+  notepad__: ["-multiInst", "-nosession"],
+  open: ["-W", "--wait-apps"],
+  phpstorm: ["--wait", "-w"],
+  pycharm: ["--wait", "-w"],
+  rider: ["--wait", "-w"],
+  rubymine: ["--wait", "-w"],
+  subl: ["--wait", "-w"],
+  sublime_text: ["--wait", "-w"],
+  vscodium: ["--wait", "-w"],
+  webstorm: ["--wait", "-w"],
+  windsurf: ["--wait", "-w"],
+  zed: ["--wait", "-w"],
+};
+
+/**
+ * Notepad++'s executable is `notepad++`, and `+` is not a key anyone will read correctly beside the
+ * rest. It is normalized to the key above rather than spelled inline twice.
+ */
+const NOTEPAD_PLUS_PLUS = "notepad++";
+
+/** Windows extensions a command may carry. Stripped before the lookup: `code.cmd` is `code`. */
+const WINDOWS_EXTENSIONS = [".exe", ".cmd", ".bat", ".com"];
+
+/**
+ * Resolve the editor, refusing one that does not wait.
+ *
+ * The refusal is here rather than in the caller for the reason the whole module exists: an editor that
+ * returns immediately is not a resolution failure the caller can recover from, and a caller that gets a
+ * `ResolvedEditor` back must be able to trust that waiting on it means something.
+ */
+export function resolveEditor(options: EditorEnvironment = {}): ResolvedEditor {
+  const env = options.env ?? process.env;
+  const platform = options.platform ?? process.platform;
+
+  for (const source of ["VISUAL", "EDITOR"] as const) {
+    // A variable set to nothing is a variable that names no editor. `export EDITOR=` is an ordinary
+    // line in a shell profile, and spawning the empty string is an ENOENT with nothing in it to read.
+    const value = env[source]?.trim() ?? "";
+    if (value.length === 0) continue;
+    const [command = "", ...args] = splitCommand(value);
+    return requireWaiting({ command, args, source });
+  }
+  return { command: defaultEditor(platform, options.hasCommand ?? onPath), args: [], source: "default" };
+}
+
+/**
+ * Resolve the editor for `file`, refusing first when there is no terminal to open it in.
+ *
+ * **Order matters, and it is the non-obvious way round.** A CI job with `EDITOR=code` set has two
+ * things wrong with it, and only one of them is the thing in its way: told to add `--wait`, it adds
+ * `--wait`, and the next run hangs on a window nothing will ever close. The missing terminal is
+ * answered first for the same reason every diagnostic names the cause and not the symptom.
+ *
+ * `file` is named in that refusal, absolute, so the answer to "then how do I edit it" is in the error
+ * rather than in a second command.
+ */
+export function requireEditor(file: string, options: EditorEnvironment = {}): ResolvedEditor {
+  const interactive = options.interactive ?? (Boolean(process.stdin.isTTY) && Boolean(process.stdout.isTTY));
+  if (!interactive) {
+    throw new ValidationError({
+      message: `No terminal here, so there is no editor to open ${file} in.`,
+      action: "Run this at a terminal, or edit that file directly.",
+      detail: `editor requested for '${file}' with no TTY on stdin and stdout`,
+    });
+  }
+  return resolveEditor(options);
+}
+
+/** A child process, as far as this module is concerned: it closes, or it fails to start. */
+export interface EditorProcess {
+  on(event: "close", listener: (code: number | null) => void): void;
+  on(event: "error", listener: (error: Error) => void): void;
+}
+
+/** How the editor is spawned. A seam, so the Windows branch is testable from a POSIX host. */
+export type SpawnEditor = (
+  command: string,
+  args: readonly string[],
+  options: { stdio: "inherit"; shell: boolean },
+) => EditorProcess;
+
+/** What {@link runEditor} needs beyond the editor itself. */
+export interface RunEditorOptions {
+  /** The platform, defaulting to `process.platform`. Decides whether a shell is involved. */
+  platform?: NodeJS.Platform;
+  /** How to spawn, defaulting to `node:child_process`'s `spawn`. */
+  spawn?: SpawnEditor;
+}
+
+/**
+ * Run a resolved editor on `file` and wait for it to close. Resolves with the exit status.
+ *
+ * `stdio: "inherit"`, always: a terminal editor **is** the terminal for as long as it runs, and a piped
+ * stdin is a `vi` that cannot be typed into. There is nothing to capture — the output is the adopter's
+ * screen — and capturing it would be capturing a file full of secrets as it is drawn.
+ *
+ * **A signal is not a clean exit.** `close` carries a null code when the editor was killed, and reading
+ * that as zero would take a `kill -9` mid-edit for a finished one and write whatever the half-saved
+ * file happened to hold.
+ *
+ * **Windows goes through a shell, and that is not laziness.** Every GUI editor there is a `.cmd` shim —
+ * `code.cmd`, `subl.cmd` — and Node refuses to spawn one directly (it has since the argument-injection
+ * fix). With `shell: true` the whole command line becomes one string that `cmd.exe /d /s /c` re-splits,
+ * so anything with a space in it has to carry its own quotes: the file lives under
+ * `%APPDATA%\pithy\<project>\`, and a Windows home directory with a space in it is the common case, not
+ * the exotic one. `/s` strips exactly the outermost pair, so the inner quotes survive to cmd's own
+ * splitting. A `"` cannot appear in a Windows path at all, so there is nothing left to escape.
+ */
+export async function runEditor(editor: ResolvedEditor, file: string, options: RunEditorOptions = {}): Promise<number> {
+  const platform = options.platform ?? process.platform;
+  const spawnEditor = options.spawn ?? defaultSpawn;
+  const windows = platform === "win32";
+  const command = windows ? quoteForCmd(editor.command) : editor.command;
+  const args = windows ? [...editor.args, quoteForCmd(file)] : [...editor.args, file];
+
+  return new Promise<number>((resolve, reject) => {
+    const child = spawnEditor(command, args, { stdio: "inherit", shell: windows });
+    child.on("error", (cause: Error) => {
+      reject(
+        new NotFoundError(
+          {
+            message: `Could not run your editor, ${editor.command}.`,
+            action:
+              editor.source === "default"
+                ? "Set EDITOR to an editor that is installed."
+                : `Check that ${editor.source} names something on your PATH.`,
+            detail: `spawning editor '${editor.command}' from ${editor.source} failed`,
+          },
+          { cause },
+        ),
+      );
+    });
+    // A signal leaves `code` null. Anything but a clean zero is the caller's to treat as an abandon.
+    child.on("close", (code: number | null) => resolve(code ?? 1));
+  });
+}
+
+/**
+ * Resolve an editor and run it on `file` — the whole thing, for a caller with nothing else to decide.
+ *
+ * A caller that has to run the editor **more than once** on the same file (an edit that has to be
+ * re-opened) resolves once with {@link requireEditor} and then calls {@link runEditor}, so a changed
+ * `$EDITOR` mid-session cannot swap editors between rounds.
+ */
+export async function openInEditor(file: string, options: EditorEnvironment & RunEditorOptions = {}): Promise<number> {
+  // `async`, so a refusal is a rejection rather than a synchronous throw. A caller awaiting this has
+  // one failure channel; giving it two is how a refusal escapes an `await …catch` and kills the process.
+  return runEditor(requireEditor(file, options), file, options);
+}
+
+/** The platform default: `notepad` on Windows, `nano` where it is installed, `vi` everywhere else. */
+function defaultEditor(platform: NodeJS.Platform, hasCommand: (command: string) => boolean): string {
+  // Windows never probes for a POSIX editor: a Git-for-Windows shell can well have `nano` on its PATH,
+  // and answering with it for a `cmd.exe` user is an editor they have no way to leave.
+  if (platform === "win32") return "notepad";
+  // `nano` first because it says how to quit on screen; `vi` because POSIX requires it to be there.
+  return hasCommand("nano") ? "nano" : "vi";
+}
+
+/** Whether `command` is an executable on `PATH`. The default {@link EditorEnvironment.hasCommand}. */
+function onPath(command: string): boolean {
+  const path = process.env.PATH ?? "";
+  return path
+    .split(delimiter)
+    .filter(Boolean)
+    .some((directory) => existsSync(join(directory, command)));
+}
+
+/**
+ * Split an editor variable into a command and its arguments, honoring quotes.
+ *
+ * `EDITOR` is a command line, not a filename: `code --wait` is the value the refusal below asks people
+ * to set, and `"/Applications/Sublime Text.app/…/subl" --wait` is what a macOS adopter has. Splitting on
+ * whitespace alone would make the second one a command called `"/Applications/Sublime` — an ENOENT that
+ * says nothing about what is wrong.
+ *
+ * Deliberately not a shell parser. No expansion, no substitution, no operators: the value is split into
+ * words, and quotes group a word. Anything more would be running the adopter's variable as a script.
+ */
+function splitCommand(value: string): string[] {
+  const words: string[] = [];
+  let word = "";
+  let quote: '"' | "'" | null = null;
+  let started = false;
+
+  for (const character of value) {
+    if (quote !== null) {
+      if (character === quote) quote = null;
+      else word += character;
+      continue;
+    }
+    if (character === '"' || character === "'") {
+      quote = character;
+      started = true;
+      continue;
+    }
+    if (/\s/.test(character)) {
+      if (started) words.push(word);
+      word = "";
+      started = false;
+      continue;
+    }
+    word += character;
+    started = true;
+  }
+  if (started) words.push(word);
+  return words;
+}
+
+/** The lookup key for a command: its base name, lowercased, without a Windows extension. */
+function editorKey(command: string): string {
+  const base = command.split(/[/\\]/).pop() ?? command;
+  const lowered = base.toLowerCase();
+  const stripped = WINDOWS_EXTENSIONS.reduce(
+    (name, extension) => (name.endsWith(extension) ? name.slice(0, -extension.length) : name),
+    lowered,
+  );
+  return stripped === NOTEPAD_PLUS_PLUS ? "notepad__" : stripped;
+}
+
+/** Refuse an editor known to return before the edit is finished, naming the flag that fixes it. */
+function requireWaiting(editor: ResolvedEditor): ResolvedEditor {
+  const flags = WAIT_FLAGS[editorKey(editor.command)];
+  if (flags === undefined || editor.args.some((argument) => flags.includes(argument))) return editor;
+  const flag = flags[0] as string;
+  return raiseNoWait(editor, flag);
+}
+
+/** The refusal itself, kept apart so the wording is in one place and reads as one sentence. */
+function raiseNoWait(editor: ResolvedEditor, flag: string): never {
+  const base = editor.command.split(/[/\\]/).pop() ?? editor.command;
+  throw new ValidationError({
+    message: `${editor.source} is '${editor.command}', which opens a window and returns before you are done.`,
+    action: `Set ${editor.source}="${base} ${flag}" and run this again.`,
+    detail: `editor '${editor.command}' from ${editor.source} carries no wait flag (${flag})`,
+  });
+}
+
+/** Wrap a command-line word for `cmd.exe` when it needs it. Windows paths cannot contain a quote. */
+function quoteForCmd(word: string): string {
+  return /\s/.test(word) ? `"${word}"` : word;
+}
+
+/** The real spawn, kept behind the seam so a test never starts a process. */
+const defaultSpawn: SpawnEditor = (command, args, options) =>
+  spawn(command, [...args], { stdio: options.stdio, shell: options.shell });

package/src/platform/rc.ts

@@ -0,0 +1,118 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { existsSync, lstatSync, readlinkSync, realpathSync, statSync } from "node:fs";
+import { appendFile, chmod, mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir as osHomedir } from "node:os";
+import { dirname, isAbsolute, relative, resolve } from "node:path";
+import { ConflictError, ValidationError } from "@pithy-sh/core/src/error/pithyError";
+import { readOptionalFile } from "../project/readOptionalFile";
+
+/** Mode for an rc file we create from scratch: owner read/write, group/other read (POSIX `0644`). */
+const RC_FILE_MODE = 0o644;
+
+/**
+ * Read an rc file, returning `''` when it does not exist yet (the common first-install case).
+ *
+ * "Does not exist" is {@link readOptionalFile}'s decision, not this module's — an rc file that is there
+ * and will not open must not read as an empty one, because `removeFromRcFile` rewrites what it read.
+ *
+ * **The words are this file's, and they matter more here than almost anywhere** (#203). The two commands
+ * that read an rc file are `pithy alias` and `pithy doctor`: the two an adopter runs *because* something
+ * is already wrong. This used to rethrow node's own error, so a `.zshrc` that would not open answered a
+ * bare `EACCES` and a stack — the failure the error model exists to prevent, on the surface least able to
+ * absorb it. It names the file and what to do instead. Nothing of the file's contents goes in either: an
+ * rc file is where a developer keeps `export GITHUB_TOKEN=…`.
+ */
+export async function readRcFile(path: string): Promise<string> {
+  const contents = await readOptionalFile(path, {
+    unreadable: ({ code, cause }) =>
+      new ConflictError(
+        {
+          message: `Can't read ${path}.`,
+          action: "Fix the file's permissions, or add the Pithy alias to your shell config yourself.",
+          detail: `${code ?? "unknown error"} while reading ${path}`,
+        },
+        { cause },
+      ),
+  });
+  return contents ?? "";
+}
+
+/** True when `target` resolves to `home` itself or a path beneath it. */
+function isInsideHome(home: string, target: string): boolean {
+  const rel = relative(home, target);
+  return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+}
+
+/**
+ * Append text to an rc file, creating it (mode `0644`, with parent directories) when missing.
+ *
+ * Two safety refusals, per docs/CLI.md §2.5:
+ * - **Symlink escape.** If the path is a symlink whose real target lands outside the user's home
+ *   directory, refuse — following it could clobber a file the user never meant to expose.
+ * - **Read-only file.** If the file exists without an owner write bit, refuse with a clean error that
+ *   points to manual install, never a raw stack trace.
+ *
+ * The write itself is append-only: we never read-modify-write the whole file on install.
+ */
+export async function appendToRcFile(path: string, text: string): Promise<void> {
+  const home = existsSync(osHomedir()) ? realpathSync(osHomedir()) : osHomedir();
+
+  // Symlink-escape guard. lstat does not follow the link, so it fires even for a *dangling* symlink — the
+  // case a plain `existsSync` (which follows) would silently skip, letting us create a file at the escaped
+  // target. Resolve the target with realpath when it exists (following the whole chain), else from the raw
+  // link (dangling), and refuse when it lands outside the user's home directory.
+  const info = lstatSync(path, { throwIfNoEntry: false });
+  if (info?.isSymbolicLink()) {
+    let target: string;
+    try {
+      target = realpathSync(path);
+    } catch {
+      const raw = readlinkSync(path);
+      target = isAbsolute(raw) ? raw : resolve(dirname(path), raw);
+    }
+    if (!isInsideHome(home, target)) {
+      throw new ConflictError({
+        message: `${path} is a symlink that points outside your home directory.`,
+        action: "Refusing to follow it. Add the Pithy alias to your shell config yourself.",
+        detail: `Symlink target resolved to ${target}, outside ${home}.`,
+      });
+    }
+  }
+
+  // Permission guard: an existing file with no owner write bit is read-only to us. `statSync` follows the
+  // link, so this checks the real target (skipped for a dangling link, which has no target to write yet).
+  if (existsSync(path) && (statSync(path).mode & 0o200) === 0) {
+    throw new ValidationError({
+      message: `Can't write to ${path} — it's read-only.`,
+      action: "Make it writable, or add the Pithy alias to your shell config yourself.",
+    });
+  }
+
+  const existedBefore = existsSync(path);
+  if (!existedBefore && !info) await mkdir(dirname(path), { recursive: true });
+  await appendFile(path, text);
+  // Force the exact mode on a brand-new regular file we created, regardless of the process umask.
+  if (!existedBefore && !info) await chmod(path, RC_FILE_MODE);
+}
+
+/**
+ * Remove exactly the marker-delimited block (`open` … `close`, inclusive) from an rc file, leaving
+ * everything else byte-intact. Returns whether a block was found and removed. This is the one
+ * read-modify-write path — removal must parse and rewrite — but it touches only our own lines.
+ */
+export async function removeFromRcFile(path: string, open: string, close: string): Promise<boolean> {
+  if (!existsSync(path)) return false;
+  const contents = await readFile(path, "utf8");
+  const lines = contents.split("\n");
+  const openIdx = lines.indexOf(open);
+  const closeIdx = lines.indexOf(close);
+  if (openIdx === -1 || closeIdx === -1 || closeIdx < openIdx) return false;
+
+  // Also drop the single blank line we inserted before the block on install, if it is still there.
+  const start = openIdx > 0 && lines[openIdx - 1] === "" ? openIdx - 1 : openIdx;
+  lines.splice(start, closeIdx - start + 1);
+  await writeFile(path, lines.join("\n"));
+  return true;
+}

package/src/platform/shell.ts

@@ -0,0 +1,83 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { existsSync } from "node:fs";
+import { homedir as osHomedir } from "node:os";
+import { basename, join } from "node:path";
+
+/** The shells whose alias syntax and rc-file location we know how to write. */
+export type ShellKind = "bash" | "zsh" | "fish" | "powershell" | "nushell";
+
+/** A resolved shell: which one, where its config lives, and the exact line that defines `p.`. */
+export interface ShellInfo {
+  /** The detected shell family. */
+  kind: ShellKind;
+  /** Absolute path to the rc/profile file the alias line belongs in. */
+  rcPath: string;
+  /** The shell-specific line that defines the `p.` alias (no markers). */
+  aliasSyntax: string;
+}
+
+/** Injectable seams so detection is testable without touching the real environment. */
+export interface DetectShellOptions {
+  /** The shell path, defaulting to `process.env.SHELL` (e.g. `/bin/zsh`). */
+  shell?: string;
+  /** The platform, defaulting to `process.platform`. */
+  platform?: NodeJS.Platform;
+  /** The user's home directory, defaulting to `os.homedir()`. */
+  homedir?: string;
+  /** Existence probe, defaulting to `fs.existsSync` — used for the macOS `.bash_profile` preference. */
+  fileExists?: (path: string) => boolean;
+}
+
+/** The bash/zsh single-quoted form; also the fallback we print for an unknown shell. */
+const POSIX_ALIAS = "alias p.='pithy'";
+
+/**
+ * Detect the current shell and resolve where its `p.` alias belongs.
+ *
+ * Detection is `basename($SHELL)` plus platform checks, per docs/CLI.md §2.4. bash on macOS prefers
+ * `.bash_profile` (the platform convention) and falls back to `.bashrc` only when it is absent. Windows
+ * with no unix shell resolves to PowerShell — whose alias MUST be a function, not `Set-Alias` (that
+ * rejects a `.` in the name). An unrecognized shell returns `null`: the caller prints manual instructions
+ * and writes nothing. We never guess an rc file.
+ */
+export async function detectShell(options: DetectShellOptions = {}): Promise<ShellInfo | null> {
+  const shell = options.shell ?? process.env.SHELL ?? "";
+  const platform = options.platform ?? process.platform;
+  const home = options.homedir ?? osHomedir();
+  const fileExists = options.fileExists ?? existsSync;
+  const base = basename(shell).toLowerCase();
+
+  if (base.endsWith("bash")) {
+    // macOS ships the `.bash_profile` convention; prefer it when it exists, else `.bashrc`.
+    const rcPath =
+      platform === "darwin" && fileExists(join(home, ".bash_profile"))
+        ? join(home, ".bash_profile")
+        : join(home, ".bashrc");
+    return { kind: "bash", rcPath, aliasSyntax: POSIX_ALIAS };
+  }
+
+  if (base.endsWith("zsh")) {
+    return { kind: "zsh", rcPath: join(home, ".zshrc"), aliasSyntax: POSIX_ALIAS };
+  }
+
+  if (base.endsWith("fish")) {
+    // fish has no `=` in its alias form.
+    return { kind: "fish", rcPath: join(home, ".config", "fish", "config.fish"), aliasSyntax: "alias p. pithy" };
+  }
+
+  if (base.endsWith("nu")) {
+    // nushell uses a spaced `=` form.
+    return { kind: "nushell", rcPath: join(home, ".config", "nushell", "config.nu"), aliasSyntax: "alias p. = pithy" };
+  }
+
+  // PowerShell: a unix shell was not detected but we are on Windows (or the shell names PowerShell
+  // explicitly). `Set-Alias` rejects a `.` in the name, so the alias must be a passthrough function.
+  if (platform === "win32" || base.endsWith("pwsh") || base.endsWith("powershell")) {
+    const rcPath = join(home, "Documents", "PowerShell", "Microsoft.PowerShell_profile.ps1");
+    return { kind: "powershell", rcPath, aliasSyntax: "function p. { pithy @args }" };
+  }
+
+  return null;
+}