create-pathfinder 4.1.0 → 4.2.0

package/src/harnesses/hook.mjs

@@ -0,0 +1,142 @@
+/**
+ * Hook handlers: what they are, and which ones Pathfinder is allowed to write.
+ *
+ * A harness may expose a session lifecycle event. Where one does, Pathfinder
+ * can put a handler on disk for it — and that is the whole of what Pathfinder
+ * owns. It writes no settings file, registers nothing, and activates nothing:
+ * a generated handler is inert until a human adds native configuration
+ * pointing at it. That is why this module has no notion of a settings file, a
+ * hook registry, an event schema, or a cross-harness runtime, and must not
+ * grow one.
+ *
+ * Two differences from `adapter.mjs`, and only two:
+ *
+ * **There is no renderer.** An adapter is *rendered* from canonical
+ * frontmatter, which is what makes it body-independent and safe to commit. A
+ * handler's bytes *are* its behavior, so the canonical file beside this one is
+ * shipped verbatim. "Generation" here is a byte-for-byte copy of a file this
+ * package carries, which is also what makes the installed handler mechanically
+ * comparable to the canonical implementation.
+ *
+ * **The marker is a line comment.** The adapter marker is written for Markdown
+ * and spelled as an HTML comment; a script needs its own syntax and its own
+ * format version. Ownership is otherwise the identical discipline, decided by
+ * `classifyOwnership`, which both artifacts share.
+ *
+ * Nothing here deletes.
+ */
+
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+import { classifyOwnership, isOwnedState } from "./adapter.mjs";
+
+/** The marker token, and the format version this build writes and owns. */
+export const HOOK_MARKER_TOKEN = "pathfinder:hook";
+export const HOOK_MARKER_VERSION = 1;
+
+/**
+ * The marker line, parsed strictly.
+ *
+ * The version is captured rather than matched, for the same reason it is in
+ * `adapter.mjs`: a file written by a future format is recognized but not
+ * claimed. This build owns v1 and nothing else.
+ */
+const HOOK_MARKER_PATTERN = new RegExp(
+  `^//\\s*${HOOK_MARKER_TOKEN} v(\\d+)(?:\\s+name=(\\S+))?\\s*$`,
+);
+
+/**
+ * The marker a file carries, or null.
+ *
+ * Searched line by line rather than with a multiline regex so a marker quoted
+ * inside a string or a longer line cannot be mistaken for the real one.
+ *
+ * @returns {{version: number, name: string|null}|null}
+ */
+export function readHookMarker(content) {
+  if (typeof content !== "string") return null;
+
+  for (const line of content.split(/\r?\n/)) {
+    const match = HOOK_MARKER_PATTERN.exec(line.trim());
+    if (match) return { version: Number(match[1]), name: match[2] ?? null };
+  }
+
+  return null;
+}
+
+/** Does this file carry a marker in the format this build owns? */
+export function isPathfinderHook(content) {
+  return readHookMarker(content)?.version === HOOK_MARKER_VERSION;
+}
+
+/**
+ * The handlers a harness receives, in registry order.
+ *
+ * A harness with no `hooks` field receives none — which is every harness but
+ * Claude Code today, and is why a Codex destination gets no `.claude` artifact
+ * of any kind rather than a substitute for one.
+ */
+export function hooksFor(harness) {
+  return harness?.hooks ?? [];
+}
+
+/**
+ * The file names this version ships into one harness's hooks directory.
+ *
+ * Read from the registry rather than from the destination, for the reason
+ * `readCanonicalSkills` reads the kit: a stale file left behind in someone's
+ * project must not be able to add itself to the set Pathfinder claims to own,
+ * and this is what makes an orphan detectable at all.
+ */
+export function shippedHookFiles(harness) {
+  return new Set(hooksFor(harness).map((hook) => hook.file));
+}
+
+/** Where a harness looks for this handler, relative to the project root. */
+export function hookPath(harness, hook) {
+  return `${harness.hooksDir}/${hook.file}`;
+}
+
+/**
+ * The canonical bytes of one handler, exactly as they will be installed.
+ *
+ * Resolved against this module rather than against the kit root, because the
+ * handler is part of the *installer* — it ships inside the npm package under
+ * `src/`, and never through `copy-list.json`, which is uniform and would hand
+ * a Claude Code handler to every destination regardless of harness.
+ *
+ * Read on demand rather than cached: an install reads it once, and a stale
+ * module-level copy is a worse failure than a second `readFileSync`.
+ */
+export function readHookSource(hook) {
+  return readFileSync(hookSourcePath(hook), "utf8");
+}
+
+/** Where the canonical handler lives inside this package. Absolute. */
+export function hookSourcePath(hook) {
+  return fileURLToPath(new URL(`../hooks/${hook.name}.mjs`, import.meta.url));
+}
+
+/**
+ * Decide what Pathfinder may do with one path a handler would occupy.
+ *
+ * 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, isShippedHook?: boolean,
+ *          existing: string|null, expected?: string|null}} input
+ */
+export function classifyHook({ name, isShippedHook = true, existing = null, expected = null }) {
+  const marker = readHookMarker(existing);
+
+  const state = classifyOwnership({
+    existing,
+    expected,
+    ours: marker?.version === HOOK_MARKER_VERSION,
+    shipped: isShippedHook,
+  });
+
+  return { name, state, marker, owned: isOwnedState(state) };
+}

package/src/harnesses/index.mjs

@@ -2,10 +2,12 @@
  * 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.
+ * fixed directory in the project. This table says where each one looks, how a
+ * user invokes what it finds there, and — where the tool has a session
+ * lifecycle event — which handler files Pathfinder generates for it. 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,
@@ -30,9 +32,22 @@
  * - `invocation` is how a user calls the skill once the harness has found it.
  *   Reporting only; nothing branches on it.
  *
+ * - `hooksDir` and `hooks` are optional and describe session lifecycle
+ *   handlers this harness can run. A harness that omits them receives no
+ *   handler and no substitute for one — which is the honest answer for a tool
+ *   with no lifecycle primitive, not a gap to fill. `name` names the canonical
+ *   handler in `src/hooks/<name>.mjs`; `file` is its destination name, stable
+ *   so a human who activated it once keeps a valid activation across updates
+ *   with no settings rewrite.
+ *
+ *   Pathfinder owns the handler file and nothing else. It writes no settings
+ *   file, so a generated handler is inert until a human activates it.
+ *
  * @type {ReadonlyArray<{id: string, label: string, skillsDir: string,
  *                       detect: (findings: object) => boolean,
- *                       invocation: (name: string) => string}>}
+ *                       invocation: (name: string) => string,
+ *                       hooksDir?: string,
+ *                       hooks?: ReadonlyArray<{name: string, file: string}>}>}
  */
 export const HARNESSES = Object.freeze([
   Object.freeze({
@@ -41,6 +56,10 @@ export const HARNESSES = Object.freeze([
     skillsDir: ".claude/skills",
     detect: (findings) => toolDetected(findings, "claude-code"),
     invocation: (name) => `/${name}`,
+    hooksDir: ".claude/hooks",
+    hooks: Object.freeze([
+      Object.freeze({ name: "session-orientation", file: "pathfinder-session-orientation.mjs" }),
+    ]),
   }),
   Object.freeze({
     id: "codex",

package/src/hooks/session-orientation.mjs

@@ -0,0 +1,183 @@
+#!/usr/bin/env node
+// pathfinder:hook v1 name=session-orientation
+// Generated by create-pathfinder. Do not edit; re-run `npx create-pathfinder`.
+/**
+ * SessionStart orientation: surface Pathfinder work state to a starting session.
+ *
+ * Inert until you activate it. Pathfinder writes this file and nothing else —
+ * no settings file is created, merged, or read — so nothing runs it until you
+ * add native hook configuration pointing here yourself. Delete this file to
+ * remove it; an unreferenced handler never runs, and a reference to a missing
+ * handler is a non-blocking no-op.
+ *
+ * Emits a compact, read-only snapshot so the agent does not rediscover the
+ * current ticket, branch, and context availability by hand. It reports facts
+ * and one bounded verbatim excerpt; it interprets nothing. Role, Feature,
+ * ticket identity, and the next action are `whereami`'s reading of that same
+ * file, and this handler must not produce a second, divergent one.
+ *
+ * The excerpt is quoted, never parsed. `context/current-ticket.md` is written
+ * by `/ticket load` with no schema, and nothing validates its shape — bounded
+ * verbatim transport is what makes this handler immune to a file whose shape
+ * is not guaranteed. A parser here would break that, whatever it improved.
+ *
+ * Read-only by construction: it opens files for reading and runs exactly one
+ * Git command, with --no-optional-locks so not even the index cache is written.
+ *
+ * Fails open and silent: any error, or any directory that is not a Pathfinder
+ * project, exits 0 with no output. Orientation is a convenience, and a broken
+ * convenience must not announce itself into every session.
+ */
+
+import { readFileSync, existsSync, readdirSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { join, isAbsolute } from "node:path";
+
+const MAX_LINES = 40;
+const MAX_CHARS = 2000;
+
+/** Read stdin fully; the harness closes it. */
+function readStdin() {
+  try {
+    return readFileSync(0, "utf8");
+  } catch {
+    return "";
+  }
+}
+
+/** The directory the session is actually working in, worktrees included. */
+function resolveRoot(input) {
+  const candidates = [input?.cwd, process.env.CLAUDE_PROJECT_DIR, process.cwd()];
+  for (const candidate of candidates) {
+    if (typeof candidate === "string" && candidate && isAbsolute(candidate) && existsSync(candidate)) {
+      return candidate;
+    }
+  }
+  return null;
+}
+
+/** Pathfinder ships exactly two context files; this one is always among them. */
+function isPathfinderProject(root) {
+  return existsSync(join(root, "context", "ai-interaction.md"));
+}
+
+function gitLine(root) {
+  const result = spawnSync(
+    "git",
+    ["--no-optional-locks", "status", "--porcelain=v1", "--branch"],
+    { cwd: root, encoding: "utf8", timeout: 3000 },
+  );
+  if (result.status !== 0 || typeof result.stdout !== "string") return "unavailable";
+  const lines = result.stdout.split("\n").filter(Boolean);
+  const head = lines[0] ?? "";
+  const branch = head.startsWith("## ") ? head.slice(3).split("...")[0].trim() : "unknown";
+  const changed = lines.length - 1;
+  return `${branch} — ${changed === 0 ? "clean" : `${changed} changed`}`;
+}
+
+/** Availability only. Never content, never a count that implies a selection. */
+function availability(root) {
+  const marks = [];
+  const file = (name) =>
+    marks.push(`${name} ${existsSync(join(root, "context", name)) ? "yes" : "no"}`);
+  file("project-overview.md");
+  file("history.md");
+  file("tracker.md");
+  file("handoff.md");
+  for (const directory of ["features", "tickets"]) {
+    const path = join(root, "context", directory);
+    let count = null;
+    try {
+      if (existsSync(path)) {
+        count = readdirSync(path).filter((entry) => entry.endsWith(".md")).length;
+      }
+    } catch {
+      count = null;
+    }
+    marks.push(`${directory}/ ${count === null ? "no" : `${count} spec${count === 1 ? "" : "s"}`}`);
+  }
+  return marks.join(" · ");
+}
+
+/** The one file whereami reads, quoted verbatim and bounded. */
+function currentTicketExcerpt(root) {
+  const path = join(root, "context", "current-ticket.md");
+  if (!existsSync(path)) return { present: false, text: null, truncated: false };
+
+  let raw;
+  try {
+    raw = readFileSync(path, "utf8");
+  } catch {
+    return { present: true, text: null, truncated: false };
+  }
+  if (!raw.trim()) return { present: true, text: null, truncated: false };
+
+  const lines = raw.split("\n");
+  let truncated = lines.length > MAX_LINES;
+  let text = lines.slice(0, MAX_LINES).join("\n");
+  if (text.length > MAX_CHARS) {
+    text = text.slice(0, MAX_CHARS);
+    truncated = true;
+  }
+  return { present: true, text: text.trimEnd(), truncated };
+}
+
+function main() {
+  const input = (() => {
+    try {
+      return JSON.parse(readStdin());
+    } catch {
+      return {};
+    }
+  })();
+
+  const root = resolveRoot(input);
+  if (!root || !isPathfinderProject(root)) return;
+
+  // Claude Code sends the lifecycle source as `source`; the published reference
+  // calls it `session_start_reason`. Verified against a real payload — accept
+  // either, and prefer what the tool actually sends.
+  const source =
+    [input.source, input.session_start_reason].find((value) => typeof value === "string" && value) ??
+    "unknown";
+  const ticket = currentTicketExcerpt(root);
+
+  const out = [];
+  out.push("# Pathfinder work state (read-only orientation)");
+  out.push("");
+  out.push(`Session: ${source}`);
+  out.push(`Git:     ${gitLine(root)}`);
+  out.push(`Context: ${availability(root)}`);
+  out.push("Role:    none — no /role override can be active yet; do not assume one");
+  out.push("");
+
+  if (!ticket.present) {
+    out.push(
+      "context/current-ticket.md does not exist. No ticket is loaded. Treat Feature, ticket, and next action as `none`.",
+    );
+  } else if (ticket.text === null) {
+    out.push(
+      "context/current-ticket.md exists but is empty or unreadable. Treat Feature, ticket, and next action as `none` until it is read directly.",
+    );
+  } else {
+    out.push(
+      `context/current-ticket.md, verbatim${ticket.truncated ? " (truncated — read the file for the rest)" : ""}:`,
+    );
+    out.push("");
+    out.push(ticket.text);
+  }
+
+  out.push("");
+  out.push(
+    "Orientation only. Nothing above advances the workflow, assumes a role, or selects a next action; run /whereami for the interpreted snapshot.",
+  );
+
+  process.stdout.write(out.join("\n") + "\n");
+}
+
+try {
+  main();
+} catch {
+  // Fail open and silent.
+}
+process.exit(0);

package/src/install.mjs

@@ -11,6 +11,15 @@
  * 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.
+ *
+ * Session hook handlers get a third pair, `planHooks` / `applyHookPlan`. They
+ * ask an adapter's ownership question and answer it with the shared state
+ * table, but they are not folded into the adapter pair, for two reasons. A
+ * handler is not rendered from frontmatter — its canonical bytes are shipped
+ * verbatim — and only some harnesses have any, so counting one as an adapter
+ * would make the installer report a number that is not true. Nothing here
+ * writes, reads, or merges a settings file: a generated handler is inert until
+ * a human activates it.
  */
 
 import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
@@ -25,6 +34,14 @@ import {
   readCanonicalSkills,
   render,
 } from "./harnesses/adapter.mjs";
+import {
+  classifyHook,
+  hookPath,
+  hooksFor,
+  isPathfinderHook,
+  readHookSource,
+  shippedHookFiles,
+} from "./harnesses/hook.mjs";
 
 /**
  * Decide the fate of every file in the kit. Reads only; writes nothing.
@@ -143,7 +160,7 @@ export function planAdapters(harnesses, { kitRoot, targetRoot, force = false } =
       const relativePath = adapterPath(harness, skill.name);
       const destination = join(targetRoot, ...relativePath.split("/"));
       const contents = render(harness, skill);
-      const existing = readAdapter(destination);
+      const existing = readExistingFile(destination);
 
       if (existing.unreadable) {
         plan.push({
@@ -279,6 +296,144 @@ export function applyAdapterPlan(plan, { dryRun = false, onProgress } = {}) {
   return result;
 }
 
+/**
+ * Decide the fate of every hook handler for the selected harnesses.
+ *
+ * The same plan/apply discipline everything else here uses, and for the same
+ * reason: `--dry-run` reports the handler by running this exact function, not
+ * a description of it. Reads only.
+ *
+ * The set of handlers comes from the registry, so one is planned for what this
+ * version ships and nothing else. A harness with no lifecycle event has no
+ * handlers and contributes nothing to the plan — which is what keeps a Codex
+ * destination free of `.claude` artifacts, rather than a check somewhere for
+ * the string "claude".
+ *
+ * Anything else already in the harness's hooks directory is looked at exactly
+ * once — to see whether it carries our marker, which makes it an orphan worth
+ * reporting — and is never written and never removed. No settings file is
+ * read, written, or considered anywhere in here.
+ *
+ * @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 planHooks(harnesses, { targetRoot, force = false } = {}) {
+  const plan = [];
+
+  for (const harness of harnesses) {
+    for (const hook of hooksFor(harness)) {
+      const relativePath = hookPath(harness, hook);
+      const destination = join(targetRoot, ...relativePath.split("/"));
+      // The canonical bytes, shipped verbatim. There is no renderer: a
+      // handler's bytes are its behavior, which is also what makes the
+      // installed file mechanically comparable to the canonical one.
+      const contents = readHookSource(hook);
+      const existing = readExistingFile(destination);
+
+      if (existing.unreadable) {
+        plan.push({
+          harness,
+          name: hook.name,
+          relativePath,
+          destination,
+          state: ADAPTER_STATE.CONFLICT,
+          action: "unreadable",
+          contents: null,
+          message: existing.message,
+        });
+        continue;
+      }
+
+      const classified = classifyHook({
+        name: hook.name,
+        existing: existing.content,
+        expected: contents,
+      });
+
+      plan.push({
+        harness,
+        name: hook.name,
+        relativePath,
+        destination,
+        state: classified.state,
+        action: actionFor(classified.state, force),
+        contents,
+      });
+    }
+
+    for (const file of orphanHookFiles(harness, targetRoot)) {
+      plan.push({
+        harness,
+        name: file,
+        relativePath: `${harness.hooksDir}/${file}`,
+        destination: join(targetRoot, ...`${harness.hooksDir}/${file}`.split("/")),
+        state: ADAPTER_STATE.ORPHAN,
+        action: "orphan",
+        contents: null,
+      });
+    }
+  }
+
+  return plan;
+}
+
+/**
+ * Carry out a hook plan.
+ *
+ * Deliberately the same shape and the same outcome vocabulary as
+ * `applyAdapterPlan`: failures are collected rather than thrown, conflicts and
+ * orphans are outcomes rather than errors, and `onProgress` fires once per
+ * item after it resolves.
+ *
+ * @returns {{generated: number, replaced: number, unchanged: number,
+ *            conflicts: string[], orphans: string[],
+ *            errors: {relativePath: string, message: string}[]}}
+ */
+export function applyHookPlan(plan, { dryRun = false, onProgress } = {}) {
+  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;
+        onProgress?.({ item, ok: true });
+        continue;
+      case "conflict":
+        result.conflicts.push(item.relativePath);
+        onProgress?.({ item, ok: true });
+        continue;
+      case "orphan":
+        result.orphans.push(item.relativePath);
+        onProgress?.({ item, ok: true });
+        continue;
+      case "unreadable":
+        result.errors.push({ relativePath: item.relativePath, message: item.message });
+        onProgress?.({ item, ok: false });
+        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 });
+        onProgress?.({ item, ok: false });
+        continue;
+      }
+    }
+
+    if (item.action === "replace") result.replaced += 1;
+    else result.generated += 1;
+    onProgress?.({ item, ok: true });
+  }
+
+  return result;
+}
+
 /**
  * Read a file that may not be there.
  *
@@ -287,7 +442,7 @@ export function applyAdapterPlan(plan, { dryRun = false, onProgress } = {}) {
  * 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) {
+function readExistingFile(path) {
   try {
     return { content: readFileSync(path, "utf8"), unreadable: false };
   } catch (error) {
@@ -315,7 +470,7 @@ function orphanNames(harness, targetRoot, canonicalNames) {
       .map((entry) => entry.name)
       .sort()
       .filter((name) => {
-        const file = readAdapter(join(skillsDirectory, name, "SKILL.md"));
+        const file = readExistingFile(join(skillsDirectory, name, "SKILL.md"));
         return file.content !== null && isPathfinderAdapter(file.content);
       });
   } catch {
@@ -323,6 +478,39 @@ function orphanNames(harness, targetRoot, canonicalNames) {
   }
 }
 
+/**
+ * Files in the harness's hooks directory that carry our marker but are not
+ * handlers this version ships.
+ *
+ * Reported, never deleted — and here that is not merely consistency with the
+ * adapters. A human may have activated the handler by hand, and removing the
+ * file underneath that activation would knowingly point their settings at
+ * something that is gone. An orphaned handler that still works is strictly
+ * better, and removal stays the human's, in whichever order they like.
+ *
+ * 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 orphanHookFiles(harness, targetRoot) {
+  if (!harness.hooksDir) return [];
+
+  const shipped = shippedHookFiles(harness);
+  const directory = join(targetRoot, ...harness.hooksDir.split("/"));
+
+  try {
+    return readdirSync(directory, { withFileTypes: true })
+      .filter((entry) => entry.isFile() && !shipped.has(entry.name))
+      .map((entry) => entry.name)
+      .sort()
+      .filter((name) => {
+        const file = readExistingFile(join(directory, name));
+        return file.content !== null && isPathfinderHook(file.content);
+      });
+  } catch {
+    return [];
+  }
+}
+
 /** Every file under `path`, recursively, minus junk. A file yields itself. */
 function* walkFiles(path) {
   const stats = statSync(path);