create-pathfinder 1.4.0 → 1.5.0

package/src/clipboard.mjs

@@ -0,0 +1,134 @@
+/**
+ * Writing one string to the system clipboard, and never reading it back.
+ *
+ * Three rules shape this file.
+ *
+ * **It is a convenience, so it may not fail.** Every way this can go wrong — no
+ * tool installed, no display to talk to, a tool that exits non-zero, a tool that
+ * hangs — degrades to "not copied" and a printed prompt the user can select the
+ * old way. Nothing here can change an install's exit code.
+ *
+ * **No dependency.** A clipboard package would be the first runtime dependency
+ * in a project whose identity is "not a framework," bought for a feature that
+ * has to be optional anyway. Platform-native commands cost a table.
+ *
+ * **Write only.** There is no read function, and there should never be one. The
+ * clipboard is where people keep passwords for thirty seconds.
+ */
+
+import { spawnSync } from "node:child_process";
+
+import { onPath } from "./detect.mjs";
+
+/** Long enough for a real tool, short enough that a wedged one is not the install. */
+const TIMEOUT_MS = 3000;
+
+/**
+ * The clipboard writers worth trying, in the order they are tried.
+ *
+ * Ordered per platform, but *selected* by availability, which is what makes WSL
+ * work without a special case: it reports `linux`, has neither Wayland nor X,
+ * and does have `clip.exe`, so it falls through the three Linux entries and
+ * lands on the fourth. Probing the platform string alone would have told it to
+ * give up after `xsel`.
+ *
+ * Every command takes its text on **stdin**. None of them takes it as an
+ * argument, which is not a coincidence — it is the property that makes this
+ * safe, because the prompt never becomes part of a command line.
+ */
+const WRITERS = Object.freeze({
+  darwin: [{ command: "pbcopy", args: [] }],
+  win32: [{ command: "clip", args: [] }],
+  default: [
+    { command: "wl-copy", args: [] },
+    { command: "xclip", args: ["-selection", "clipboard"] },
+    { command: "xsel", args: ["--clipboard", "--input"] },
+    // WSL, and any Linux that can reach a Windows host's clipboard.
+    { command: "clip.exe", args: [] },
+  ],
+});
+
+/**
+ * The clipboard command this machine can actually run, or null.
+ *
+ * Null is an ordinary answer, not an error: a headless server has no clipboard,
+ * and saying so is more useful than trying four commands and reporting the
+ * fourth one's stderr.
+ *
+ * @returns {{command: string, args: string[]} | null}
+ */
+export function clipboardCommand({ env = {}, platform = process.platform } = {}) {
+  const candidates = WRITERS[platform] ?? WRITERS.default;
+  return candidates.find((writer) => onPath(writer.command, env, platform)) ?? null;
+}
+
+/**
+ * Put `text` on the clipboard. Say whether it worked.
+ *
+ * Never throws. A spawn that fails, a tool that exits non-zero, a timeout, and
+ * a machine with no clipboard tool at all are four different reasons and one
+ * outcome, and the caller prints a single line about it either way.
+ *
+ * @param {string} text
+ * @returns {{ok: true, command: string} | {ok: false, reason: string}}
+ */
+export function copyToClipboard(text, { env = {}, platform = process.platform } = {}) {
+  const writer = clipboardCommand({ env, platform });
+  if (writer === null) return { ok: false, reason: "no clipboard tool is available here" };
+
+  let result;
+  try {
+    result = spawnSync(writer.command, writer.args, {
+      // An array, never a shell string. The text goes down stdin and is never
+      // interpolated into a command line, so a prompt containing a backtick, a
+      // semicolon, or a newline is data on every platform.
+      shell: false,
+      // The same environment the command was *found* in. Resolving `pbcopy`
+      // against one PATH and then running it against another is how a probe
+      // ends up disagreeing with the thing it probed for.
+      env,
+      input: text,
+      timeout: TIMEOUT_MS,
+      // Captured, not inherited: xclip's complaint about a missing DISPLAY must
+      // not appear to be something Pathfinder said.
+      stdio: ["pipe", "pipe", "pipe"],
+      encoding: "utf8",
+    });
+  } catch (error) {
+    // spawnSync generally reports rather than throws, but a bad argv or an
+    // exhausted process table can still land here, and a convenience feature
+    // is not allowed to take the install down with it.
+    return { ok: false, reason: describe(writer.command, error?.message) };
+  }
+
+  if (result.error) {
+    const timedOut = result.error.code === "ETIMEDOUT" || result.signal !== null;
+    return {
+      ok: false,
+      reason: timedOut
+        ? `${writer.command} did not finish`
+        : describe(writer.command, result.error.message),
+    };
+  }
+
+  if (result.status !== 0) {
+    // The tool's own first line of stderr is the most useful thing available —
+    // "Error: Can't open display" is the actual answer — but it is quoted, so
+    // it reads as the tool's words rather than Pathfinder's.
+    const detail = firstLine(result.stderr);
+    return {
+      ok: false,
+      reason: detail === "" ? `${writer.command} failed` : `${writer.command} said: ${detail}`,
+    };
+  }
+
+  return { ok: true, command: writer.command };
+}
+
+function describe(command, message) {
+  return message ? `${command} could not be run: ${firstLine(message)}` : `${command} could not be run`;
+}
+
+function firstLine(text) {
+  return String(text ?? "").split("\n")[0].trim();
+}

package/src/detect.mjs

@@ -0,0 +1,183 @@
+/**
+ * What is already here, and what is available to run.
+ *
+ * Detection is advisory. Everything in this file answers a question of the form
+ * "is this present?" and nothing acts on the answer: a finding sets a default
+ * or a line in the report, never a file on disk. That boundary is the whole
+ * reason this is a separate module — a detector that could also configure
+ * something would make every future "it noticed X" into "it did X to me."
+ *
+ * Nothing here spawns a process. Availability is decided by scanning PATH with
+ * existsSync rather than by running `which`/`where` or the tool itself, which
+ * buys three things: detection cannot hang, cannot print another program's
+ * output over ours, and cannot become the dependency on the `git` binary that
+ * findGitRoot exists to avoid. The cost is that a PATH entry which is present
+ * but not executable reads as detected. That is the right direction to be
+ * wrong in, because a finding only ever offers a default the user can decline.
+ *
+ * Every probe is wrapped so a failure degrades to "not detected". An unreadable
+ * $HOME, a PATH full of directories that do not exist, a permissions error —
+ * none of them may abort an install.
+ */
+
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+
+import { findGitRoot } from "./kit.mjs";
+
+/**
+ * The tools worth reporting, in the order they are reported.
+ *
+ * This table says how to recognize a tool, and deliberately says nothing about
+ * what to do with one. Feature 11 owns the harness registry — where each writes
+ * and what it generates — and will consume these ids rather than restate them.
+ * Two of these four (VS Code, Cursor) are not skill harnesses at all and never
+ * will be; they are here because later features act on the editor, not the
+ * harness.
+ */
+const TOOLS = [
+  {
+    id: "claude-code",
+    label: "Claude Code",
+    commands: ["claude"],
+    homeMarkers: [".claude"],
+    projectMarkers: [".claude"],
+    termProgram: [],
+  },
+  {
+    id: "codex",
+    label: "Codex",
+    commands: ["codex"],
+    homeMarkers: [".codex", join(".agents", "skills")],
+    projectMarkers: [".agents"],
+    termProgram: [],
+  },
+  {
+    id: "vscode",
+    label: "VS Code",
+    commands: ["code"],
+    homeMarkers: [],
+    projectMarkers: [],
+    termProgram: ["vscode"],
+  },
+  {
+    id: "cursor",
+    label: "Cursor",
+    commands: ["cursor"],
+    homeMarkers: [".cursor"],
+    projectMarkers: [".cursor"],
+    termProgram: ["cursor"],
+  },
+];
+
+/**
+ * Everything the CLI knows about its environment before it asks anything.
+ *
+ * Reads the filesystem and the environment. Writes nothing, spawns nothing.
+ *
+ * @returns {{
+ *   git: {repositoryRoot: string|null, insideRepository: boolean, binary: boolean},
+ *   pathfinder: {installed: boolean, skillCount: number},
+ *   tools: {id: string, label: string, detected: boolean}[],
+ * }}
+ */
+export function detect({ cwd, env = {}, platform = process.platform } = {}) {
+  const home = homeDirectory(env);
+  const repositoryRoot = safe(() => findGitRoot(cwd), null);
+
+  return {
+    git: {
+      repositoryRoot,
+      insideRepository: repositoryRoot !== null,
+      binary: safe(() => onPath("git", env, platform), false),
+    },
+    pathfinder: safe(() => detectPathfinder(cwd), { installed: false, skillCount: 0 }),
+    tools: TOOLS.map((tool) => ({
+      id: tool.id,
+      label: tool.label,
+      detected: safe(() => detectTool(tool, { cwd, home, env, platform }), false),
+    })),
+  };
+}
+
+/** The labels of every detected tool, in table order. Convenience for the report. */
+export function detectedToolLabels(findings) {
+  return findings.tools.filter((tool) => tool.detected).map((tool) => tool.label);
+}
+
+function detectTool(tool, { cwd, home, env, platform }) {
+  const term = env.TERM_PROGRAM ?? "";
+  if (tool.termProgram.some((name) => name.toLowerCase() === term.toLowerCase())) return true;
+  if (tool.commands.some((command) => onPath(command, env, platform))) return true;
+  if (home !== null && tool.homeMarkers.some((marker) => existsSync(join(home, marker)))) return true;
+  return tool.projectMarkers.some((marker) => existsSync(join(cwd, marker)));
+}
+
+/**
+ * Does this directory already look like a Pathfinder project?
+ *
+ * Decided by counting skill directories rather than by testing for `CLAUDE.md`,
+ * which any agent-assisted project may have written for its own reasons.
+ * A `skills/<name>/SKILL.md` is a far more specific signature, and the count is
+ * worth having on its own — it is what makes "already installed (20 skills)"
+ * checkable by the person reading it.
+ */
+function detectPathfinder(cwd) {
+  const skillsDirectory = join(cwd, "skills");
+  if (!existsSync(skillsDirectory)) return { installed: false, skillCount: 0 };
+
+  const skillCount = readdirSync(skillsDirectory, { withFileTypes: true }).filter(
+    (entry) => entry.isDirectory() && existsSync(join(skillsDirectory, entry.name, "SKILL.md")),
+  ).length;
+
+  return { installed: skillCount > 0, skillCount };
+}
+
+/**
+ * Is `command` findable on PATH?
+ *
+ * The separator is derived from the passed platform rather than read from
+ * `node:path`, so a test can synthesize a Windows environment on any host.
+ * PATHEXT is honored for the same reason `git` is spelled `git.exe` there.
+ */
+export function onPath(command, env, platform) {
+  const searchPath = env.PATH ?? env.Path ?? "";
+  if (searchPath === "") return false;
+
+  const separator = platform === "win32" ? ";" : ":";
+  const extensions =
+    platform === "win32"
+      ? (env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD").split(";").filter(Boolean)
+      : [""];
+
+  for (const directory of searchPath.split(separator)) {
+    if (directory === "") continue;
+    for (const extension of extensions) {
+      if (existsSync(join(directory, command + extension))) return true;
+    }
+  }
+
+  return false;
+}
+
+/**
+ * The user's home directory, or null when the environment does not say.
+ *
+ * Null rather than a guess. A wrong home directory would make every
+ * home-marker probe silently answer about somewhere nobody lives, and "not
+ * detected" is the honest result when the environment is that impoverished —
+ * which is a real CI configuration, not a hypothetical one.
+ */
+function homeDirectory(env) {
+  return env.HOME || env.USERPROFILE || null;
+}
+
+/** Run a probe; treat any failure as "not detected". */
+function safe(probe, fallback) {
+  try {
+    const value = probe();
+    return value === undefined ? fallback : value;
+  } catch {
+    return fallback;
+  }
+}

package/src/editor.mjs

@@ -0,0 +1,136 @@
+/**
+ * Finding the editors this machine can actually launch, and launching one.
+ *
+ * The same three rules the clipboard follows, for the same reasons.
+ *
+ * **It is a convenience, so it may not fail.** No editor installed, a binary
+ * that cannot be executed, a launch that dies on the spot — all of it degrades
+ * to "not opened" and one printed line. The project is installed either way,
+ * and nothing here can change an install's exit code.
+ *
+ * **Only what was detected.** There is no way to name an editor, pass a path,
+ * or configure one. An editor Pathfinder did not find on PATH is an editor it
+ * does not offer, which is what keeps this from growing into a launcher.
+ *
+ * **Detached.** The CLI hands the project to the editor and forgets it. It does
+ * not wait for the editor to exit, does not hold its streams, and does not
+ * print its output as Pathfinder's — an installer that stays alive until you
+ * close your editor would be a bug that looks like a hang.
+ */
+
+import { spawn } from "node:child_process";
+import { once } from "node:events";
+
+import { onPath } from "./detect.mjs";
+
+/**
+ * The editors that can be offered, in the order they are offered.
+ *
+ * Alphabetical by label, deliberately. Some order has to exist, and every
+ * ordering that means something — most popular, best supported, the one we use
+ * — would make this table an endorsement. The alphabet endorses nothing, and
+ * it puts Cursor above VS Code, which is a useful reminder that neither is a
+ * Pathfinder requirement.
+ *
+ * Detection is by command on PATH and nothing else. `src/detect.mjs` reports
+ * these two tools more generously — a `.cursor` directory counts there — and
+ * that is right for a finding and wrong for a launch: a marker directory does
+ * not give you a binary to run.
+ */
+const EDITORS = Object.freeze([
+  Object.freeze({ id: "cursor", label: "Cursor", command: "cursor" }),
+  Object.freeze({ id: "vscode", label: "VS Code", command: "code" }),
+]);
+
+/**
+ * The editors this machine can launch. Possibly none, which is an ordinary
+ * answer: a server with no editor installed simply is not asked the question.
+ *
+ * @returns {ReadonlyArray<{id: string, label: string, command: string}>}
+ */
+export function detectEditors({ env = {}, platform = process.platform } = {}) {
+  return EDITORS.filter((editor) => onPath(editor.command, env, platform));
+}
+
+/**
+ * Ask `editor` to open `directory`, and say whether the launch got off the
+ * ground. Never throws.
+ *
+ * "Got off the ground" is the honest limit of what this can report. It resolves
+ * as soon as the child process exists — Node's `spawn` event — and deliberately
+ * not on its exit, because waiting for an editor to exit is waiting for the
+ * user to close their editor. An editor that starts and then fails on its own
+ * has its own way of saying so, on its own screen.
+ *
+ * @param {{label: string, command: string}} editor
+ * @param {string} directory
+ * @returns {Promise<{ok: true} | {ok: false, reason: string}>}
+ */
+export async function openInEditor(
+  editor,
+  directory,
+  { env = {}, platform = process.platform } = {},
+) {
+  const windows = platform === "win32";
+
+  // `code` and `cursor` are `.cmd` shims on Windows, which Node refuses to
+  // execute directly, so there it goes through the command processor. The
+  // quoting is ours rather than the shell's, because `windowsVerbatimArguments`
+  // hands this line through untouched — and it needs one more pair of quotes
+  // than looks right.
+  //
+  // `cmd /s /c` strips the first and last quote of everything after `/c`,
+  // unconditionally. Passing `"code" "C:\my project"` therefore loses the quote
+  // before `code` and the one after the path, leaving `code" "C:\my project` —
+  // a broken command line, and a silently unopened editor. Wrapping the whole
+  // thing in an outer pair spends those two quotes on the wrapper, so what
+  // survives the strip is the command line actually meant: the executable
+  // quoted, and a project path with spaces in it still a single argument.
+  //
+  // Everywhere else it is an argument array with no shell at all.
+  const command = windows ? env.ComSpec || env.COMSPEC || "cmd.exe" : editor.command;
+  const args = windows
+    ? ["/d", "/s", "/c", `""${editor.command}" "${directory}""`]
+    : [directory];
+
+  let child;
+  try {
+    child = spawn(command, args, {
+      shell: false,
+      // The environment the command was *found* in, for the same reason the
+      // clipboard does it: resolving `code` against one PATH and running it
+      // against another is how a probe disagrees with the thing it probed for.
+      env,
+      // Detached and ignored together. Its own process group so it outlives
+      // this one, and no inherited streams so the editor's startup chatter is
+      // never mistaken for something Pathfinder said.
+      detached: true,
+      stdio: "ignore",
+      windowsVerbatimArguments: windows,
+      windowsHide: true,
+    });
+  } catch (error) {
+    return { ok: false, reason: describe(editor.command, error?.message) };
+  }
+
+  try {
+    // Resolves on `spawn`, rejects on `error` — a missing or unexecutable
+    // binary reports ENOENT or EACCES here, before anything is unreferenced.
+    await once(child, "spawn");
+  } catch (error) {
+    return { ok: false, reason: describe(editor.command, error?.message) };
+  }
+
+  // Anything that goes wrong after a successful spawn belongs to the editor,
+  // not to the install — but an unhandled `error` event would still take this
+  // process down on its way out, so it is absorbed.
+  child.on("error", () => {});
+  child.unref();
+
+  return { ok: true };
+}
+
+function describe(command, message) {
+  const detail = String(message ?? "").split("\n")[0].trim();
+  return detail === "" ? `${command} could not be run` : `${command} could not be run: ${detail}`;
+}

package/src/git.mjs

@@ -0,0 +1,58 @@
+/**
+ * The one Git command this tool is allowed to run.
+ *
+ * `git init`, in the directory it was given, and nothing else. No `add`, no
+ * `commit`, no `config`, no branch manipulation, no `init` in a parent. The
+ * narrowness is the design: this module has no way to express a destructive
+ * operation, so no future edit to a caller can turn one on by passing a
+ * different argument.
+ *
+ * Invoked with an argument array, never a shell string, so a directory whose
+ * name contains a space, a quote, or a `;` is data rather than syntax.
+ *
+ * Output is captured rather than inherited. `git init` prints a `hint:` block
+ * about default branch names on many installations, and inheriting stdio would
+ * make that paragraph appear to be Pathfinder's own voice, in the middle of
+ * Pathfinder's own report. Success is reported in our words; failure hands back
+ * git's stderr, because there the detail is the actionable part.
+ */
+
+import { spawnSync } from "node:child_process";
+
+/**
+ * Initialize a repository in `cwd`.
+ *
+ * Never throws. A missing binary, a read-only path, and a permissions error are
+ * all outcomes to report, not exceptions to escape into a stack trace over the
+ * top of a half-finished install.
+ *
+ * @param {string} cwd
+ * @param {{spawn?: typeof spawnSync}} [options] - seam for tests; production
+ *   passes nothing.
+ * @returns {{ok: true} | {ok: false, message: string}}
+ */
+export function initRepository(cwd, { spawn = spawnSync } = {}) {
+  let result;
+
+  try {
+    result = spawn("git", ["init"], {
+      cwd,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"],
+      windowsHide: true,
+    });
+  } catch (error) {
+    return { ok: false, message: error.message };
+  }
+
+  // ENOENT arrives here rather than as a throw: the binary vanished between
+  // detection and use, or PATH said something that was not true.
+  if (result.error) return { ok: false, message: result.error.message };
+
+  if (result.status !== 0) {
+    const stderr = (result.stderr ?? "").trim();
+    return { ok: false, message: stderr || `\`git init\` exited with status ${result.status}` };
+  }
+
+  return { ok: true };
+}