create-pathfinder 1.8.0 → 2.1.0

package/src/kit.mjs

@@ -8,7 +8,7 @@
  */
 
 import { existsSync, readFileSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
+import { dirname, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
@@ -49,6 +49,75 @@ export function isExcluded(basename) {
   return EXCLUDED.has(basename) || basename.startsWith("._");
 }
 
+/**
+ * Kit files that are deliberately not part of the kit, by kit-relative path.
+ *
+ * A different idea from EXCLUDED above, and kept separate for that reason.
+ * Those are OS and editor droppings that were never anybody's file. These are
+ * real, hand-written files that live inside a copy-list directory and must
+ * still never reach a destination project.
+ *
+ * All three are this repository's own working state, and every one of them
+ * would be actively wrong in somebody else's project.
+ *
+ * `context/tracker.md` is the original case. Work Tracking's off switch is the
+ * *absence* of that file in a destination project, so shipping this
+ * repository's own copy would hand every new project a configuration naming a
+ * tracker it does not own, pointing at a spec directory it does not have, with
+ * the off switch already defeated on first install.
+ *
+ * `context/current-feature.md` and `context/handoff.md` are transient session
+ * state, and they are here for the same reason one step further on: the kit
+ * stopped shipping a blank `current-feature.md` stencil, because `load-feature`
+ * writes the real one on first use and a placeholder is just a file a reader
+ * has to recognise as empty. Having stopped shipping the blank one, the thing
+ * to guard against is shipping a *filled-in* one — a destination project
+ * opening its first session to a note about whichever feature a Pathfinder
+ * maintainer had loaded on the day of the release.
+ *
+ * `context` is a *directory* entry in the copy list, so anything placed beneath
+ * it ships by default. Making the invariant enforced rather than intended is
+ * the same move `check_no_junk_tracked` made: an ignore rule is advisory, one
+ * `git add -f` defeats it, and `stage-kit.mjs` copies from the working tree
+ * without consulting it at all.
+ *
+ * Matched on the kit-relative path, never the basename — a project's own
+ * `tracker.md` somewhere else is not this file and must not be caught by it.
+ */
+const NEVER_SHIPS = new Set([
+  "context/tracker.md",
+  "context/current-feature.md",
+  "context/handoff.md",
+]);
+
+/**
+ * Is this kit-relative path one the kit must never hand over?
+ *
+ * @param {string} relativePath forward-slashed, relative to the kit root
+ */
+export function neverShips(relativePath) {
+  return NEVER_SHIPS.has(relativePath);
+}
+
+/**
+ * A `cpSync` filter that drops never-ships files from a recursive copy.
+ *
+ * Lives here rather than inline in `stage-kit.mjs` so the staging path and its
+ * test run the same code. A test that rebuilds the predicate proves only that
+ * `cpSync` honours `filter`; it cannot catch the path arithmetic below going
+ * wrong, which is the part with anything to get wrong in it.
+ *
+ * `cpSync` hands the filter absolute paths and calls it for the copy root
+ * itself, so the root resolves to `""` and is kept — filtering a directory out
+ * would take its whole subtree with it.
+ *
+ * @param {string} rootDir absolute path the kit-relative paths are relative to
+ * @returns {(source: string) => boolean} true to copy, false to skip
+ */
+export function neverShipsFilter(rootDir) {
+  return (source) => !neverShips(relative(rootDir, source).split(sep).join("/"));
+}
+
 const PACKAGE_ROOT = resolve(HERE, "..");
 
 /**

package/src/outcome.mjs

@@ -0,0 +1,147 @@
+/**
+ * What a run did, derived once.
+ *
+ * Two renderings print this install — `contractReport` owes byte-for-byte what
+ * 1.4.1 printed, `expressiveReport` owes a person a legible hierarchy — and
+ * they had each grown their own copy of the same four derivations: the
+ * mode-dependent written count, the skipped filter, the failure merge, and a
+ * per-harness adapter tally that appeared three times character-for-character.
+ * Four facts, ten spellings, and no mechanism keeping them in agreement. This
+ * module is the one spelling. The renderings stay two renderings; they just
+ * stop each deciding what the numbers are.
+ *
+ * Pure by construction: no filesystem, no `process`, no writing. Everything
+ * here is a function of the plans and results it is handed, which is what lets
+ * a summary be tested without building a temporary repository or a fake
+ * terminal.
+ *
+ * Two counters elsewhere are deliberately *not* folded in, and a later change
+ * that "finishes the job" will break them:
+ *
+ * - `countWritten` in `cli.mjs` runs mid-run, before adapters are applied, and
+ *   reports a different number — `written + overwritten`, labelled "copied" —
+ *   than the summary's `written`. It cannot read a result that does not exist
+ *   yet.
+ * - The streaming per-harness counts in `generateAdapters` accumulate as units
+ *   resolve, so milestones can print while the work is happening, and they
+ *   count conflicts, orphans, and up-to-date adapters differently from the
+ *   rows below. A summary computed at the end cannot drive a progress bar.
+ */
+
+/**
+ * Every derived fact both renderings need, and nothing either of them can
+ * compute for itself.
+ *
+ * @param {object} args
+ * @param {{relativePath: string, status: "write"|"skip"|"overwrite"}[]} args.plan
+ *   the kit copy plan, in `planInstall`'s sort
+ * @param {{written: number, skipped: number, overwritten: number,
+ *          errors: {relativePath: string, message: string}[]}} args.result
+ * @param {{plan: object[], result: object, blocked: boolean}} args.adapters
+ * @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 }) {
+  // 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.
+  const written = options.dryRun
+    ? plan.filter((item) => item.status === "write").length
+    : result.written;
+
+  const skipped = plan
+    .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]);
+
+  return Object.freeze({
+    written,
+    overwritten: result.overwritten,
+    skipped: Object.freeze(skipped),
+    // Nothing to write and every file already there. Not the same as `written
+    // === 0`, which a partly failed copy also satisfies.
+    alreadyInstalled: written === 0 && skipped.length === plan.length,
+    failures,
+    blocked: adapters.blocked,
+    // Summed from the result, never from `harnessRows`. The rows exclude paths
+    // 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 }),
+  });
+}
+
+/**
+ * What actually wants a human: a contested path, or an adapter pointing at a
+ * skill that is gone.
+ *
+ * Skipped files are deliberately not counted. A re-run over an existing install
+ * skips every file by design, and calling thirty-six routine skips "things to
+ * look at" would turn the one number that should mean something into noise
+ * nobody reads twice.
+ *
+ * Counted across the whole adapter plan rather than across `harnessRows`,
+ * 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(
+    (item) => item.action === "conflict" || item.action === "orphan",
+  ).length;
+}
+
+/**
+ * One row per selected harness, in the order the harnesses were given.
+ *
+ * The three-way distinction the report depends on is carried by the rows
+ * themselves, and all three collapse to a zero if it is lost:
+ *
+ * - no harness chosen — no rows, `blocked: false`
+ * - the kit copy failed — no rows, `blocked: true`
+ * - a harness that produced nothing — a row of zeroes
+ *
+ * The blocked case returns no rows explicitly rather than falling out of an
+ * 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.
+ */
+function harnessRows({ adapters, 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(
+        (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"),
+      });
+    }),
+  );
+}

package/templates/CHANGELOG.template.md

@@ -1,6 +1,7 @@
 # Changelog
 
-Use this file only when the destination project adopts a changelog.
+Use only when the project adopts a changelog.
+Record user-facing changes, not implementation history.
 
 ## [Unreleased]
 

package/templates/feature-spec.template.md

@@ -2,104 +2,42 @@
 
 ## Status
 
-Not Started
-
-## Overview
-
-Describe the smallest coherent outcome, where it fits, and why it matters.
-
-## Problem
-
-- What is missing, risky, confusing, inaccessible, unreliable, or inefficient?
-- Who or what is affected?
-- Why does this matter now?
+Proposed
 
 ## Goal
 
-State one user-visible or system-verifiable outcome.
-
-## Dependencies
+[One clear user-visible or system-verifiable outcome.]
 
-- Earlier feature, system, decision, prototype, or `None`.
+## Context
 
-## Tags
+Include only what materially helps someone implement this Feature.
 
-- Optional. `namespace:value`, e.g. `area:cli`, `type:infra`, `agent:suitable`.
-- Omit this section entirely, or write `None`, when the project does not use tags. Most do not.
-- Only meaningful when the project has configured work tracking; nothing else reads them.
+- Read: `[specific files, sections, or systems]`
+- Relevant area: `[path or component]`
+- Avoid: `[unrelated area, if useful]`
 
 ## Requirements
 
-- Requirement 1
-- Requirement 2
-- Requirement 3
-- Include relevant failure, permission, loading, empty, retry, responsive, accessibility, operational, or compatibility states only when applicable.
+- `[required behavior]`
+- `[important constraint]`
+- `[relevant edge or failure behavior, when applicable]`
 
 ## Out of Scope
 
-- Explicit exclusion
-- Later feature, if known
-- Unrelated refactors, dependencies, or polish
-
-## Experience or Operational Notes — When Applicable
-
-- User interaction, system behavior, responsive behavior, accessibility, observability, performance, security, or operational expectations.
-
-## Technical Notes
-
-Likely areas:
-
-- `[specific path or bounded area]`
-
-Implementation constraints:
-
-- Follow project context and approved prototype direction.
-- Do not silently resolve open architecture decisions.
-- Keep prototype and production code boundaries explicit.
-
-## Context Boundary
-
-Read:
-
-- `[specific context and code]`
-
-Avoid loading:
-
-- `[unrelated systems, old specs, generated output]`
-
-Split this feature further if its required context is not focused enough for reliable implementation and verification.
+- `[explicit exclusion]`
 
 ## Delivery Chunks
 
-1. `[stable, verifiable increment]`
-2. `[stable, verifiable increment]`
-3. `[optional stable increment]`
+1. `[small, stable, verifiable increment]`
+2. `[next increment, if needed]`
 
-Each chunk should leave the project stable.
+Use one chunk when the Feature is already small.
 
 ## Acceptance Criteria
 
-- The defined outcome works end to end within scope.
-- Relevant failure and edge behavior is handled.
-- Applicable quality requirements are met.
-- Required automated/manual checks pass.
-- The work can be reviewed independently.
-
-## Verification
-
-- Manual or operational checks:
-- Automated checks:
-- Edge cases:
-- Quality checks:
-
-## Learning Targets
-
-- Concepts worth explaining after completion:
-- Diagram or demonstration opportunity:
-- Quiz ideas:
+- `[observable result proving the Feature works]`
+- `[important verification result]`
 
-## Suggested Delivery Metadata
+## Notes / Decisions
 
-- Git action: `[follow project workflow]`
-- Suggested branch, when applicable: `[project naming convention]`
-- Suggested commit, when applicable: `[project convention]`
+- `[Feature-specific dependency, approved decision, constraint, or None]`

package/templates/history.template.md

@@ -0,0 +1,12 @@
+# Project History
+
+Compact record of completed work.
+
+## Completed
+
+### [YYYY-MM-DD] — [Feature or milestone]
+
+- Outcome: `[what changed for the project/user]`
+- Verification: `[brief result or evidence pointer]`
+- Commit/PR: `[sha, PR, or release reference]`
+- Follow-up: `[only if something remains, otherwise none]`

package/templates/lesson.template.md

@@ -1,71 +1,42 @@
 # Lesson — [Feature Name]
 
 - Date:
-- Branch:
-- Feature spec:
-- Commit or diff range:
-- Difficulty:
-- Estimated review time:
+- Feature:
+- Commit/diff:
 
-## 1. Feature in One Minute
+## What Changed
 
-What changed, why it exists, and the user or system value it creates.
+Explain what was implemented and why it matters.
 
-## 2. Mental Model
+## Mental Model
 
-Explain the feature through one clear model. Include a small Mermaid diagram when useful.
+Explain the simplest useful way to understand the Feature.
 
-## 3. Execution and Data Flow
+Include a small diagram only when it helps.
 
-Trace one representative interaction from input to visible result.
+## How It Works
 
-## 4. Important Files
+Trace one representative flow through the implementation.
 
-| File | Responsibility | Why it matters |
-| --- | --- | --- |
+## Important Files
 
-## 5. Key Decisions and Tradeoffs
+| File | Responsibility |
+| --- | --- |
 
-For each meaningful decision:
+Include only files that materially help understanding.
 
-- Decision
-- Evidence in the repository
-- Benefit
-- Cost
-- Credible alternative
-- When the alternative would be better
+## Key Decisions
 
-## 6. Concepts Worth Retaining
+- `[important decision and why it was made]`
 
-Limit this to the most transferable concepts.
+Include only decisions worth remembering.
 
-## 7. Quality Lens
+## Concepts to Retain
 
-### Testing
+- `[transferable concept]`
 
-### Accessibility
+## Check Your Understanding
 
-### Performance
-
-### Maintainability
-
-### Error and edge states
-
-## 8. Production-Scale Gap
-
-What would need to change for higher traffic, larger datasets, multiple teams, stricter security, or real-time collaboration?
-
-## 9. Interview Preparation
-
-- Likely question:
-- Strong answer outline:
-- Follow-up question:
-- Vocabulary to use carefully:
-
-## 10. Check Your Understanding
-
-Three short retrieval questions. Do not include answers here.
-
-## 11. Suggested Next Action
-
-Choose one: quiz, challenge, architecture lesson, spaced review, or no further work.
+1. `[question]`
+2. `[question]`
+3. `[question]`