create-pathfinder 4.0.0 → 4.2.0

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);

package/src/outcome.mjs

@@ -38,11 +38,15 @@
  * @param {{written: number, skipped: number, overwritten: number,
  *          errors: {relativePath: string, message: string}[]}} args.result
  * @param {{plan: object[], result: object, blocked: boolean}} args.adapters
+ * @param {{plan: object[], result: object, blocked: boolean}} [args.hooks]
+ *   the session hook handler plan and result, shaped exactly like `adapters`.
+ *   Optional, and absent means "no handler was planned" — a harness with no
+ *   lifecycle event has none, which is the ordinary case rather than an error.
  * @param {{label: string}[]} args.harnesses the selected harnesses, registry order
  * @param {{dryRun?: boolean}} args.options
  * @returns {Readonly<object>} frozen; rows and lists frozen with it
  */
-export function summarize({ plan, result, adapters, harnesses, options }) {
+export function summarize({ plan, result, adapters, hooks = NO_HOOKS, harnesses, options }) {
   // A dry run has no `result.written` to report, because nothing was written.
   // The plan is counted instead, which is the same number the run would have
   // produced had it been allowed to write.
@@ -54,9 +58,14 @@ export function summarize({ plan, result, adapters, harnesses, options }) {
     .filter((item) => item.status === "skip")
     .map((item) => item.relativePath);
 
-  // Copy errors before adapter errors, because that is the order they happened
-  // in and the order the failure list has always printed.
-  const failures = Object.freeze([...result.errors, ...adapters.result.errors]);
+  // Copy errors before adapter errors before handler errors, because that is
+  // the order they happened in and the order the failure list has always
+  // printed.
+  const failures = Object.freeze([
+    ...result.errors,
+    ...adapters.result.errors,
+    ...hooks.result.errors,
+  ]);
 
   return Object.freeze({
     written,
@@ -71,11 +80,35 @@ export function summarize({ plan, result, adapters, harnesses, options }) {
     // that errored and this does not, so the two disagree exactly when a write
     // fails — and this is the number the closing headline speaks for.
     built: adapters.result.generated + adapters.result.replaced,
-    attention: attentionCount(adapters),
-    harnessRows: harnessRows({ adapters, harnesses }),
+    // Counted apart from `built`, and never folded into it. A handler is not
+    // an adapter — it delegates to nothing and is inert until a human
+    // activates it — so adding one to the adapter count would make the closing
+    // line state a number that is not true.
+    handlers: hooks.result.generated + hooks.result.replaced,
+    attention: attentionCount(adapters) + attentionCount(hooks),
+    harnessRows: harnessRows({ adapters, hooks, harnesses }),
   });
 }
 
+/**
+ * What a run with no hook plan looks like.
+ *
+ * The same shape `generateHooks` returns, so a caller that has none and a
+ * caller whose harnesses have none reach identical code below.
+ */
+const NO_HOOKS = Object.freeze({
+  plan: Object.freeze([]),
+  result: Object.freeze({
+    generated: 0,
+    replaced: 0,
+    unchanged: 0,
+    conflicts: Object.freeze([]),
+    orphans: Object.freeze([]),
+    errors: Object.freeze([]),
+  }),
+  blocked: false,
+});
+
 /**
  * What actually wants a human: a contested path, or an adapter pointing at a
  * skill that is gone.
@@ -89,9 +122,9 @@ export function summarize({ plan, result, adapters, harnesses, options }) {
  * errored paths included, because a path that could not be written is still a
  * path somebody has to go and look at.
  */
-function attentionCount(adapters) {
-  if (adapters.blocked) return 0;
-  return adapters.plan.filter(
+function attentionCount(generated) {
+  if (generated.blocked) return 0;
+  return generated.plan.filter(
     (item) => item.action === "conflict" || item.action === "orphan",
   ).length;
 }
@@ -110,38 +143,57 @@ function attentionCount(adapters) {
  * empty plan, so that a harness which was chosen and never reached is never
  * described as having generated zero adapters.
  *
- * Paths that failed to write are excluded from every count and list here: an
- * adapter that could not be written was not generated, is not up to date, and
- * is not a conflict the user can resolve by re-running with `--force`. They are
- * reported once, as failures.
+ * Each row carries a harness's adapters and, under `handlers`, that harness's
+ * hook handlers — the same five facts twice, because they are the same five
+ * questions about two different kinds of generated file.
  */
-function harnessRows({ adapters, harnesses }) {
+function harnessRows({ adapters, hooks, harnesses }) {
   if (harnesses.length === 0 || adapters.blocked) return Object.freeze([]);
 
-  const failed = new Set(adapters.result.errors.map((error) => error.relativePath));
-
   return Object.freeze(
-    harnesses.map((harness) => {
-      // Identity, not label: the harness object on a plan item is the registry
-      // entry itself, and two entries could plausibly share a label one day.
-      const mine = adapters.plan.filter(
+    harnesses.map((harness) =>
+      Object.freeze({
+        harness,
+        ...tally(adapters, harness),
+        // The same five facts for this harness's hook handlers, under their
+        // own names. A harness with no lifecycle event has no handlers, and
+        // every one of these is then zero or empty — which is what a report
+        // needs in order to say nothing at all about them.
+        handlers: Object.freeze(tally(hooks, harness)),
+      }),
+    ),
+  );
+}
+
+/**
+ * One harness's share of a generated plan, as the five facts a report prints.
+ *
+ * Paths that failed to write are excluded from every count and list: a file
+ * that could not be written was not generated, is not up to date, and is not a
+ * conflict the user can resolve by re-running with `--force`. They are
+ * reported once, as failures.
+ */
+function tally(generated, harness) {
+  const failed = new Set(generated.result.errors.map((error) => error.relativePath));
+
+  // Identity, not label: the harness object on a plan item is the registry
+  // entry itself, and two entries could plausibly share a label one day.
+  const mine = generated.blocked
+    ? []
+    : generated.plan.filter(
         (item) => item.harness === harness && !failed.has(item.relativePath),
       );
-      const count = (action) => mine.filter((item) => item.action === action).length;
-      const paths = (action) =>
-        Object.freeze(
-          mine.filter((item) => item.action === action).map((item) => item.relativePath),
-        );
 
-      return Object.freeze({
-        harness,
-        generated: count("write"),
-        replaced: count("replace"),
-        unchanged: count("up-to-date"),
-        // `planAdapters` order, which is the order they will be printed in.
-        conflicts: paths("conflict"),
-        orphans: paths("orphan"),
-      });
-    }),
-  );
+  const count = (action) => mine.filter((item) => item.action === action).length;
+  const paths = (action) =>
+    Object.freeze(mine.filter((item) => item.action === action).map((item) => item.relativePath));
+
+  return {
+    generated: count("write"),
+    replaced: count("replace"),
+    unchanged: count("up-to-date"),
+    // Plan order, which is the order they will be printed in.
+    conflicts: paths("conflict"),
+    orphans: paths("orphan"),
+  };
 }