create-pathfinder 1.4.1 → 1.5.0

package/src/harnesses/adapter.mjs

@@ -0,0 +1,288 @@
+/**
+ * Adapters: what they contain, and which ones Pathfinder is allowed to write.
+ *
+ * A canonical skill at `skills/<name>/SKILL.md` is the single behavior
+ * contract. An adapter is a generated discovery shim that a harness can find,
+ * carrying the canonical metadata and a pointer — and no behavior of its own.
+ * Two properties make that arrangement safe, and both are enforced here.
+ *
+ * **Body-independence.** `render` is a function of the canonical *frontmatter*
+ * only. Editing a skill body — the overwhelming majority of skill changes —
+ * produces a byte-identical adapter, so generated files can be committed and
+ * verified without turning every prose edit into a diff. Nothing in this file
+ * ever reads a canonical body.
+ *
+ * **Decidable ownership.** Pathfinder regenerates a file only when the file
+ * itself says Pathfinder wrote it. A user may legitimately have their own
+ * `.claude/skills/debug-issue/SKILL.md`, and a name match is not evidence of
+ * anything. The marker is the mechanism — not a hash, not a manifest, not the
+ * name. Nothing here deletes.
+ *
+ * Everything in this module is pure except `readSkillMetadata`, which reads one
+ * file. No planning, no writing, no CLI: those are Chunk 2's.
+ */
+
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+
+/** The marker token, and the format version this build writes and owns. */
+export const MARKER_TOKEN = "pathfinder:adapter";
+export const MARKER_VERSION = 1;
+
+/**
+ * The marker line, parsed strictly.
+ *
+ * The version is captured rather than matched, so a file written by a future
+ * format is *recognized* but not claimed: this build owns v1 and nothing else.
+ * Silently regenerating a format it does not understand would be the same
+ * mistake as owning a file by name.
+ */
+const MARKER_PATTERN = new RegExp(
+  `^<!--\\s*${MARKER_TOKEN} v(\\d+)(?:\\s+source=(\\S+))?\\s*-->$`,
+);
+
+/**
+ * The ownership classes. Every path under a harness skills directory is
+ * exactly one of these, and each maps to one behavior:
+ *
+ * | State       | Means                                          | Behavior                        |
+ * | ----------- | ---------------------------------------------- | ------------------------------- |
+ * | `absent`    | canonical skill, nothing on disk               | generate                        |
+ * | `stale`     | our marker, contents differ                    | regenerate, no flag needed      |
+ * | `current`   | our marker, byte-identical                     | nothing; report as up to date   |
+ * | `conflict`  | canonical name, no marker we own               | leave it, report by name        |
+ * | `orphan`    | our marker, name this version no longer ships  | report, never delete            |
+ * | `unmanaged` | anything else under the harness directory      | never read, never written       |
+ *
+ * `conflict` is the only state `--force` may act on, and the only one where a
+ * user's file is at stake. It covers a hand-written file *and* a marker whose
+ * version this build does not own — both are "someone else's file" as far as
+ * this code is concerned.
+ */
+export const ADAPTER_STATE = Object.freeze({
+  ABSENT: "absent",
+  STALE: "stale",
+  CURRENT: "current",
+  CONFLICT: "conflict",
+  ORPHAN: "orphan",
+  UNMANAGED: "unmanaged",
+});
+
+/** States Pathfinder may write without `--force`. */
+const OWNED_STATES = new Set([ADAPTER_STATE.ABSENT, ADAPTER_STATE.STALE, ADAPTER_STATE.CURRENT]);
+
+/**
+ * Where a canonical skill lives, relative to the project root.
+ *
+ * Always forward slashes. This string is rendered into the adapter body, so it
+ * is a fact about the document rather than about the host filesystem — a
+ * backslash here would make Windows-generated adapters differ from everyone
+ * else's, which is exactly the byte-determinism this layer promises not to
+ * break.
+ */
+export function canonicalPath(name) {
+  return `skills/${name}/SKILL.md`;
+}
+
+/** Where a harness looks for that skill, relative to the project root. */
+export function adapterPath(harness, name) {
+  return `${harness.skillsDir}/${name}/SKILL.md`;
+}
+
+/**
+ * Parse a canonical `SKILL.md`'s frontmatter into the metadata an adapter
+ * carries.
+ *
+ * Deliberately the same tolerance `.github/scripts/validate-kit.py` uses — a
+ * flat block of `key: value` lines between two `---` fences — so the installer
+ * and the validator cannot disagree about what a skill declares, and neither
+ * needs a YAML dependency. Values are taken verbatim: a description containing
+ * a colon keeps it, and nothing is re-worded, wrapped, or truncated.
+ *
+ * Throws rather than returning a partial result. A skill with no `description`
+ * would otherwise produce an adapter a harness silently ignores, and a loud
+ * failure naming the file is far cheaper than that.
+ *
+ * @returns {{name: string, description: string, argumentHint: string|null}}
+ */
+export function parseSkillFrontmatter(text, { source = "SKILL.md" } = {}) {
+  const lines = text.split(/\r?\n/);
+
+  if (lines[0]?.trimEnd() !== "---") {
+    throw new Error(`${source}: line 1 must be exactly \`---\``);
+  }
+
+  const close = lines.findIndex((line, index) => index > 0 && line.trimEnd() === "---");
+  if (close === -1) {
+    throw new Error(`${source}: frontmatter has no closing \`---\``);
+  }
+
+  const data = new Map();
+  for (const line of lines.slice(1, close)) {
+    if (line.trim() === "") continue;
+    const match = /^([A-Za-z0-9_-]+):\s*(.*)$/.exec(line);
+    if (!match) {
+      throw new Error(`${source}: frontmatter line is not a \`key: value\` pair: ${line}`);
+    }
+    data.set(match[1], match[2].trim());
+  }
+
+  for (const key of ["name", "description"]) {
+    if (!data.get(key)) throw new Error(`${source}: frontmatter \`${key}\` is missing or empty`);
+  }
+
+  return {
+    name: data.get("name"),
+    description: data.get("description"),
+    argumentHint: data.get("argument-hint") || null,
+  };
+}
+
+/** Read one canonical skill's metadata. */
+export function readSkillMetadata(path, { source = path } = {}) {
+  return parseSkillFrontmatter(readFileSync(path, "utf8"), { source });
+}
+
+/**
+ * Every skill this version of the kit ships, in name order.
+ *
+ * Read from the kit rather than from the destination project, because the kit
+ * is what defines the set: a stale directory left behind in someone's project
+ * must not be able to add itself to the list of things Pathfinder claims to
+ * own. It is also what makes an orphan detectable at all.
+ *
+ * @returns {{name: string, description: string, argumentHint: string|null}[]}
+ */
+export function readCanonicalSkills(kitRoot) {
+  const skillsRoot = join(kitRoot, "skills");
+  if (!existsSync(skillsRoot)) return [];
+
+  return readdirSync(skillsRoot, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .sort()
+    .filter((name) => existsSync(join(skillsRoot, name, "SKILL.md")))
+    .map((name) =>
+      readSkillMetadata(join(skillsRoot, name, "SKILL.md"), {
+        source: canonicalPath(name),
+      }),
+    );
+}
+
+/**
+ * Render the adapter bytes for one skill.
+ *
+ * Same input, same bytes, on every platform: lines are joined with `\n`
+ * explicitly and never `os.EOL`, and nothing here consults the clock, the
+ * environment, or the canonical body.
+ *
+ * `harness` is taken and validated but does not currently change the output —
+ * both harnesses in the plan read `SKILL.md` with `name`/`description`
+ * frontmatter, so one renderer serves both. It stays in the signature because
+ * the first harness that needs a different file format supplies its own
+ * renderer, and callers should already be passing the harness by then.
+ *
+ * @returns {string} the complete file contents, LF, one trailing newline
+ */
+export function render(harness, { name, description, argumentHint = null } = {}) {
+  if (!harness?.skillsDir) throw new Error("render: a harness is required");
+  assertRenderableName(name);
+  if (!description) throw new Error(`render: skill \`${name}\` has no description`);
+
+  const canonical = canonicalPath(name);
+
+  return [
+    "---",
+    `name: ${name}`,
+    `description: ${description}`,
+    ...(argumentHint ? [`argument-hint: ${argumentHint}`] : []),
+    "---",
+    "",
+    `<!-- ${MARKER_TOKEN} v${MARKER_VERSION} source=${canonical} -->`,
+    "<!-- Generated by create-pathfinder. Do not edit; re-run `npx create-pathfinder`. -->",
+    "",
+    `Read \`${canonical}\` in this repository and follow it exactly.`,
+    "",
+    "That file is the canonical, tool-neutral definition of this skill. This file",
+    "exists only so this tool can discover it, and contains no behavior of its own.",
+    "",
+    `If \`${canonical}\` does not exist, stop and tell the user the`,
+    "Pathfinder kit is not installed in this repository. Do not improvise the skill.",
+    "",
+  ].join("\n");
+}
+
+/**
+ * The marker a file carries, or null.
+ *
+ * Searched line by line rather than with a multiline regex so a marker quoted
+ * inside a fenced block or a longer line cannot be mistaken for the real one.
+ *
+ * @returns {{version: number, source: string|null}|null}
+ */
+export function readMarker(content) {
+  if (typeof content !== "string") return null;
+
+  for (const line of content.split(/\r?\n/)) {
+    const match = MARKER_PATTERN.exec(line.trim());
+    if (match) return { version: Number(match[1]), source: match[2] ?? null };
+  }
+
+  return null;
+}
+
+/** Does this file carry a marker in the format this build owns? */
+export function isPathfinderAdapter(content) {
+  return readMarker(content)?.version === MARKER_VERSION;
+}
+
+/**
+ * Decide what Pathfinder may do with one path under a harness skills
+ * directory.
+ *
+ * Takes the file's current contents rather than a path, so the decision is a
+ * pure function of what is on disk and can be tested exhaustively without one.
+ * `existing` is null when nothing is there.
+ *
+ * @param {{name: string, isCanonicalSkill: boolean,
+ *          existing: string|null, expected?: string|null}} input
+ * @returns {{name: string, state: string, marker: {version: number, source: string|null}|null,
+ *            owned: boolean, forceReplaceable: boolean}}
+ */
+export function classifyAdapter({ name, isCanonicalSkill, existing = null, expected = null }) {
+  const marker = readMarker(existing);
+  const ours = marker?.version === MARKER_VERSION;
+
+  const state = (() => {
+    // A marked file naming a skill this version does not ship. Reported so it
+    // cannot rot unnoticed, and left alone: deleting in someone else's
+    // repository is a different authority than writing, and is not claimed.
+    if (!isCanonicalSkill) return ours ? ADAPTER_STATE.ORPHAN : ADAPTER_STATE.UNMANAGED;
+    if (existing === null) return ADAPTER_STATE.ABSENT;
+    if (!ours) return ADAPTER_STATE.CONFLICT;
+    return existing === expected ? ADAPTER_STATE.CURRENT : ADAPTER_STATE.STALE;
+  })();
+
+  return {
+    name,
+    state,
+    marker,
+    owned: OWNED_STATES.has(state),
+    forceReplaceable: state === ADAPTER_STATE.CONFLICT,
+  };
+}
+
+/**
+ * A name that can be rendered into a path and a document.
+ *
+ * Narrow on purpose. The name arrives from a file the installer did not write
+ * and is interpolated into `skills/<name>/SKILL.md`, so a separator or a `..`
+ * would turn a metadata bug into a path that escapes the directory it was
+ * meant to describe.
+ */
+function assertRenderableName(name) {
+  if (!name) throw new Error("render: skill has no name");
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(name) || name.includes("..")) {
+    throw new Error(`render: skill name is not usable as a path segment: ${name}`);
+  }
+}

package/src/harnesses/index.mjs

@@ -0,0 +1,122 @@
+/**
+ * The harness registry.
+ *
+ * A harness is a coding tool that discovers skills by reading files from a
+ * fixed directory in the project. This table says where each one looks and how
+ * a user invokes what it finds there — nothing more. It is a table, not a
+ * plugin system: a new harness is one object, and there is deliberately no
+ * loader, no manifest format, and no way for a user to register their own.
+ *
+ * Two entries today, and the second one cost exactly what this shape promised:
+ * one object. Adding Codex changed no renderer, no ownership rule, no planner,
+ * and no line of `cli.mjs` — the only difference between the harnesses is where
+ * the file goes.
+ *
+ * Detection is not re-implemented here. `src/detect.mjs` already probes for
+ * these tools and reports them by id, and duplicating that would create a
+ * second answer to "is Claude Code here?" that can disagree with the one the
+ * report prints. A harness therefore consumes the finding rather than
+ * repeating the probe.
+ */
+
+/**
+ * Every harness Pathfinder can generate adapters for.
+ *
+ * - `id` matches the tool id in `src/detect.mjs`, which is what makes
+ *   `detect` a lookup instead of a second probe.
+ * - `skillsDir` is written with forward slashes and joined per-platform by
+ *   whatever touches the filesystem. It is a relative path inside the
+ *   destination project, never absolute.
+ * - `invocation` is how a user calls the skill once the harness has found it.
+ *   Reporting only; nothing branches on it.
+ *
+ * @type {ReadonlyArray<{id: string, label: string, skillsDir: string,
+ *                       detect: (findings: object) => boolean,
+ *                       invocation: (name: string) => string}>}
+ */
+export const HARNESSES = Object.freeze([
+  Object.freeze({
+    id: "claude-code",
+    label: "Claude Code",
+    skillsDir: ".claude/skills",
+    detect: (findings) => toolDetected(findings, "claude-code"),
+    invocation: (name) => `/${name}`,
+  }),
+  Object.freeze({
+    id: "codex",
+    label: "Codex",
+    // Codex scans `.agents/skills` in every directory from the working
+    // directory up to the repository root, so one directory at the root is
+    // found from anywhere inside the project. Nothing extra is generated for
+    // subdirectories. The personal scope, `$HOME/.agents/skills`, is a
+    // different place and Pathfinder never writes there.
+    skillsDir: ".agents/skills",
+    detect: (findings) => toolDetected(findings, "codex"),
+    invocation: (name) => `$${name}`,
+  }),
+]);
+
+/** Valid `--agents` values, in registry order. For error messages and help. */
+export const HARNESS_IDS = Object.freeze(HARNESSES.map((harness) => harness.id));
+
+/** The harness with this id, or null. Unknown ids are the caller's to report. */
+export function findHarness(id) {
+  return HARNESSES.find((harness) => harness.id === id) ?? null;
+}
+
+/**
+ * The harness a person means when they type this, or null.
+ *
+ * Only reached when someone has said their tool is *not* one of the supported
+ * ones, so its whole job is to catch the case where it is after all — typing
+ * "claude" at a question that already offered Claude Code on the line above.
+ * Recording that as an unsupported tool would tell them Pathfinder cannot do
+ * the thing it just offered to do.
+ *
+ * Matching is exact against the names a harness actually goes by: its id, its
+ * label, and the first word of its label. Deliberately not a prefix or
+ * substring search, which would claim "code" for Codex when the person almost
+ * certainly meant VS Code — and refusing to record a name is only defensible
+ * when the alternative really is a duplicate.
+ */
+export function harnessNamed(name) {
+  const typed = normalizeName(name);
+  if (typed === "") return null;
+
+  return (
+    HARNESSES.find((harness) =>
+      [harness.id, harness.label, harness.label.split(" ")[0]]
+        .map(normalizeName)
+        .includes(typed),
+    ) ?? null
+  );
+}
+
+/** Case, spaces, and punctuation are not what distinguishes one tool from another. */
+function normalizeName(name) {
+  return String(name ?? "")
+    .toLowerCase()
+    .replace(/[^a-z0-9]/g, "");
+}
+
+/**
+ * The harnesses `detect()` found, in registry order.
+ *
+ * These form the *default* selection and are never applied without
+ * confirmation — detection offers, it does not decide.
+ */
+export function detectedHarnesses(findings) {
+  return HARNESSES.filter((harness) => harness.detect(findings));
+}
+
+/**
+ * Did detection see this tool?
+ *
+ * Tolerant of a findings object that predates a harness or was synthesized by
+ * a caller: an absent entry reads as "not detected" rather than throwing, for
+ * the same reason every probe in detect.mjs degrades that way.
+ */
+function toolDetected(findings, id) {
+  const tools = findings?.tools ?? [];
+  return tools.some((tool) => tool.id === id && tool.detected === true);
+}

package/src/install.mjs

@@ -5,12 +5,26 @@
  * nothing; `applyPlan` carries a plan out. That split is what makes --dry-run
  * honest — it runs the identical planning code the real install runs, rather
  * than a parallel description of it that can drift.
+ *
+ * Harness adapters get their own pair, `planAdapters` / `applyAdapterPlan`,
+ * under the same discipline. They are kept apart from the kit copy because
+ * they answer a different question — the kit copy asks "does this file exist
+ * yet?", and an adapter asks "did Pathfinder write this file?" — and because
+ * adapters are generated bytes rather than copied ones.
  */
 
-import { copyFileSync, existsSync, mkdirSync, readdirSync, statSync } from "node:fs";
+import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
 import { dirname, join, relative, sep } from "node:path";
 
 import { COPY_LIST, isExcluded } from "./kit.mjs";
+import {
+  ADAPTER_STATE,
+  adapterPath,
+  classifyAdapter,
+  isPathfinderAdapter,
+  readCanonicalSkills,
+  render,
+} from "./harnesses/adapter.mjs";
 
 /**
  * Decide the fate of every file in the kit. Reads only; writes nothing.
@@ -83,6 +97,200 @@ export function applyPlan(plan, { dryRun = false } = {}) {
   return result;
 }
 
+/**
+ * Decide the fate of every adapter path for the selected harnesses.
+ *
+ * The same plan/apply discipline the kit copy uses, and for the same reason:
+ * `--dry-run` reports by running this exact function, not a description of it.
+ * Reads only.
+ *
+ * The set of skills comes from the kit, so an adapter is planned for what this
+ * version ships and nothing else. Anything already under the harness directory
+ * that is not one of those names is looked at exactly once — to see whether it
+ * carries our marker, which makes it an orphan worth reporting — and is never
+ * written.
+ *
+ * @returns {{harness: object, name: string, relativePath: string, destination: string,
+ *            state: string, action: "write"|"replace"|"up-to-date"|"conflict"|"orphan"|"unreadable",
+ *            contents: string|null, message?: string}[]}
+ */
+export function planAdapters(harnesses, { kitRoot, targetRoot, force = false } = {}) {
+  const skills = readCanonicalSkills(kitRoot);
+  const canonicalNames = new Set(skills.map((skill) => skill.name));
+  const plan = [];
+
+  for (const harness of harnesses) {
+    for (const skill of skills) {
+      const relativePath = adapterPath(harness, skill.name);
+      const destination = join(targetRoot, ...relativePath.split("/"));
+      const contents = render(harness, skill);
+      const existing = readAdapter(destination);
+
+      if (existing.unreadable) {
+        plan.push({
+          harness,
+          name: skill.name,
+          relativePath,
+          destination,
+          state: ADAPTER_STATE.CONFLICT,
+          action: "unreadable",
+          contents: null,
+          message: existing.message,
+        });
+        continue;
+      }
+
+      const classified = classifyAdapter({
+        name: skill.name,
+        isCanonicalSkill: true,
+        existing: existing.content,
+        expected: contents,
+      });
+
+      plan.push({
+        harness,
+        name: skill.name,
+        relativePath,
+        destination,
+        state: classified.state,
+        action: actionFor(classified.state, force),
+        contents,
+      });
+    }
+
+    for (const name of orphanNames(harness, targetRoot, canonicalNames)) {
+      const relativePath = adapterPath(harness, name);
+      plan.push({
+        harness,
+        name,
+        relativePath,
+        destination: join(targetRoot, ...relativePath.split("/")),
+        state: ADAPTER_STATE.ORPHAN,
+        action: "orphan",
+        contents: null,
+      });
+    }
+  }
+
+  return plan;
+}
+
+/**
+ * What a classification means for this run.
+ *
+ * `--force` reaches exactly one state. It authorizes replacing a file
+ * Pathfinder does not own at a path it would otherwise generate — the same
+ * category of decision as replacing a kit file the user has edited, which is
+ * why it is the same flag rather than a second one.
+ */
+function actionFor(state, force) {
+  switch (state) {
+    case ADAPTER_STATE.ABSENT:
+    case ADAPTER_STATE.STALE:
+      return "write";
+    case ADAPTER_STATE.CURRENT:
+      return "up-to-date";
+    case ADAPTER_STATE.CONFLICT:
+      return force ? "replace" : "conflict";
+    default:
+      return "orphan";
+  }
+}
+
+/**
+ * Carry out an adapter plan.
+ *
+ * Failures are collected rather than thrown, exactly as the kit copy does, so
+ * one unwritable path reports itself next to everything that did succeed.
+ * Conflicts and orphans are outcomes, not errors: nothing went wrong, and the
+ * files they name are the ones this tool successfully left alone.
+ *
+ * @returns {{generated: number, replaced: number, unchanged: number,
+ *            conflicts: string[], orphans: string[],
+ *            errors: {relativePath: string, message: string}[]}}
+ */
+export function applyAdapterPlan(plan, { dryRun = false } = {}) {
+  const result = { generated: 0, replaced: 0, unchanged: 0, conflicts: [], orphans: [], errors: [] };
+
+  for (const item of plan) {
+    switch (item.action) {
+      case "up-to-date":
+        result.unchanged += 1;
+        continue;
+      case "conflict":
+        result.conflicts.push(item.relativePath);
+        continue;
+      case "orphan":
+        result.orphans.push(item.relativePath);
+        continue;
+      case "unreadable":
+        result.errors.push({ relativePath: item.relativePath, message: item.message });
+        continue;
+      default:
+        break;
+    }
+
+    if (!dryRun) {
+      try {
+        mkdirSync(dirname(item.destination), { recursive: true });
+        writeFileSync(item.destination, item.contents, "utf8");
+      } catch (error) {
+        result.errors.push({ relativePath: item.relativePath, message: error.message });
+        continue;
+      }
+    }
+
+    if (item.action === "replace") result.replaced += 1;
+    else result.generated += 1;
+  }
+
+  return result;
+}
+
+/**
+ * Read a file that may not be there.
+ *
+ * A missing file and a missing directory are the same answer — nothing is
+ * there — but an *unreadable* file is not. Treating a permissions error as
+ * absence would classify someone's file as "generate here", which is the one
+ * mistake this layer exists to prevent, so it becomes a reported error instead.
+ */
+function readAdapter(path) {
+  try {
+    return { content: readFileSync(path, "utf8"), unreadable: false };
+  } catch (error) {
+    if (error.code === "ENOENT" || error.code === "ENOTDIR") {
+      return { content: null, unreadable: false };
+    }
+    return { content: null, unreadable: true, message: error.message };
+  }
+}
+
+/**
+ * Names under the harness directory that carry our marker but are not skills
+ * this version ships.
+ *
+ * Reported, never deleted. Any failure to look — no directory, no permission —
+ * is simply "no orphans", because this is a courtesy check and must not be able
+ * to fail an install.
+ */
+function orphanNames(harness, targetRoot, canonicalNames) {
+  const skillsDirectory = join(targetRoot, ...harness.skillsDir.split("/"));
+
+  try {
+    return readdirSync(skillsDirectory, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory() && !canonicalNames.has(entry.name))
+      .map((entry) => entry.name)
+      .sort()
+      .filter((name) => {
+        const file = readAdapter(join(skillsDirectory, name, "SKILL.md"));
+        return file.content !== null && isPathfinderAdapter(file.content);
+      });
+  } catch {
+    return [];
+  }
+}
+
 /** Every file under `path`, recursively, minus junk. A file yields itself. */
 function* walkFiles(path) {
   const stats = statSync(path);