create-pathfinder 1.3.0

package/src/cli.mjs

@@ -0,0 +1,156 @@
+/**
+ * Command-line surface: parse arguments, refuse unsafe situations, report.
+ *
+ * No CLI framework. The flag set is four booleans and the whole parser is a
+ * loop; a dependency tree for that would be indefensible in a project whose
+ * identity is "not a framework."
+ */
+
+import { findGitRoot, findKitRoot, COPY_LIST } from "./kit.mjs";
+import { applyPlan, planInstall } from "./install.mjs";
+
+const USAGE = `Usage: npx create-pathfinder [options]
+
+Installs the Pathfinder workflow kit into the current Git repository.
+
+Copies: ${COPY_LIST.join(", ")}
+
+Options:
+  --dry-run    Report what would be written; change nothing.
+  --force      Overwrite files that already exist. Off by default.
+  -h, --help   Show this message.
+`;
+
+export function run(argv, { cwd, out, err }) {
+  const options = parseArguments(argv);
+
+  if (options.error) {
+    err(`create-pathfinder: ${options.error}\n\n${USAGE}`);
+    return 2;
+  }
+
+  if (options.help) {
+    out(USAGE);
+    return 0;
+  }
+
+  // Refused rather than allowed with a warning: this tool writes several
+  // hundred files, and without version control the user has no way to inspect
+  // or undo what it did.
+  const gitRoot = findGitRoot(cwd);
+  if (gitRoot === null) {
+    err(
+      `create-pathfinder: ${cwd} is not inside a Git repository.\n\n` +
+        "The kit is installed into version control so you can review the\n" +
+        "files it adds and undo them if you change your mind. Run `git init`\n" +
+        "here first, or cd into an existing repository, then run this again.\n",
+    );
+    return 1;
+  }
+
+  const kitRoot = findKitRoot();
+  if (kitRoot === null) {
+    err(
+      "create-pathfinder: this package is missing the kit files it should copy.\n" +
+        "That is a packaging bug, not something you did. Please report it at\n" +
+        "https://github.com/rikilamadrid/pathfinder/issues\n",
+    );
+    return 1;
+  }
+
+  if (kitRoot === gitRoot) {
+    err(
+      "create-pathfinder: this is the Pathfinder kit repository itself.\n" +
+        "There is nothing to install here. Run it in the project you want the\n" +
+        "kit copied into.\n",
+    );
+    return 1;
+  }
+
+  const plan = planInstall(kitRoot, cwd, { force: options.force });
+  const result = applyPlan(plan, { dryRun: options.dryRun });
+
+  report({ result, plan, cwd, gitRoot, options, out, err });
+  return result.errors.length > 0 ? 1 : 0;
+}
+
+function parseArguments(argv) {
+  const options = { dryRun: false, force: false, help: false, error: null };
+
+  for (const argument of argv) {
+    switch (argument) {
+      case "--dry-run":
+        options.dryRun = true;
+        break;
+      case "--force":
+        options.force = true;
+        break;
+      case "-h":
+      case "--help":
+        options.help = true;
+        break;
+      default:
+        options.error = `unknown option \`${argument}\``;
+        return options;
+    }
+  }
+
+  return options;
+}
+
+/**
+ * Say what happened, in full.
+ *
+ * Skipped files are listed individually, not counted. The whole promise of the
+ * default mode is that it left your work alone, and a bare "42 skipped" does
+ * not let anyone check that claim.
+ */
+function report({ result, plan, cwd, gitRoot, options, out, err }) {
+  const lines = [];
+  const verb = options.dryRun ? "Would install" : "Installed";
+
+  lines.push(`${verb} the Pathfinder kit into ${cwd}`);
+  if (gitRoot !== cwd) {
+    lines.push(`Note: the repository root is ${gitRoot}, not this directory.`);
+  }
+  lines.push("");
+
+  const written = options.dryRun ? plan.filter((i) => i.status === "write").length : result.written;
+  lines.push(`  ${written} file${plural(written)} ${options.dryRun ? "to write" : "written"}`);
+
+  if (result.overwritten > 0) {
+    lines.push(`  ${result.overwritten} file${plural(result.overwritten)} overwritten (--force)`);
+  }
+
+  const skipped = plan.filter((item) => item.status === "skip");
+  if (skipped.length > 0) {
+    lines.push(`  ${skipped.length} file${plural(skipped.length)} left untouched because they already exist:`);
+    for (const item of skipped) lines.push(`      ${item.relativePath}`);
+    lines.push("");
+    lines.push("  Nothing above was modified. Re-run with --force to replace them.");
+  }
+
+  if (written === 0 && skipped.length === plan.length) {
+    lines.push("");
+    lines.push("The kit is already installed here.");
+  } else {
+    lines.push("");
+    lines.push("Next step — give your agent this prompt:");
+    lines.push("");
+    lines.push("  Use skills/kickstart-pathfinder/SKILL.md. Help me initialize this");
+    lines.push("  project. Do not install packages or write product code yet.");
+  }
+
+  out(lines.join("\n") + "\n");
+
+  if (result.errors.length > 0) {
+    const failures = result.errors
+      .map((error) => `  ${error.relativePath}: ${error.message}`)
+      .join("\n");
+    err(`\ncreate-pathfinder: ${result.errors.length} file${plural(result.errors.length)} could not be written:\n${failures}\n`);
+  }
+}
+
+function plural(count) {
+  return count === 1 ? "" : "s";
+}

package/src/install.mjs

@@ -0,0 +1,99 @@
+/**
+ * The copier.
+ *
+ * Split in two on purpose. `planInstall` decides what would happen and touches
+ * 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.
+ */
+
+import { copyFileSync, existsSync, mkdirSync, readdirSync, statSync } from "node:fs";
+import { dirname, join, relative, sep } from "node:path";
+
+import { COPY_LIST, isExcluded } from "./kit.mjs";
+
+/**
+ * Decide the fate of every file in the kit. Reads only; writes nothing.
+ *
+ * Existing files are detected one file at a time rather than one top-level
+ * entry at a time. A project that already has `context/` gets the files it is
+ * missing and keeps the ones it wrote, instead of the whole directory being
+ * declared present and skipped.
+ *
+ * @returns {{relativePath: string, source: string, destination: string,
+ *            status: "write" | "skip" | "overwrite"}[]}
+ */
+export function planInstall(kitRoot, targetRoot, { force = false } = {}) {
+  const plan = [];
+
+  for (const entry of COPY_LIST) {
+    for (const source of walkFiles(join(kitRoot, entry))) {
+      const relativePath = relative(kitRoot, source).split(sep).join("/");
+      const destination = join(targetRoot, relativePath);
+      const exists = existsSync(destination);
+
+      plan.push({
+        relativePath,
+        source,
+        destination,
+        status: !exists ? "write" : force ? "overwrite" : "skip",
+      });
+    }
+  }
+
+  return plan.sort((a, b) => a.relativePath.localeCompare(b.relativePath));
+}
+
+/**
+ * Carry out a plan.
+ *
+ * Failures are collected rather than thrown, so one unwritable path reports
+ * itself alongside everything that did succeed instead of aborting the run
+ * halfway with no summary. Entries marked `skip` are never opened.
+ *
+ * @returns {{written: number, skipped: number, overwritten: number,
+ *            errors: {relativePath: string, message: string}[]}}
+ */
+export function applyPlan(plan, { dryRun = false } = {}) {
+  const result = { written: 0, skipped: 0, overwritten: 0, errors: [] };
+
+  for (const item of plan) {
+    if (item.status === "skip") {
+      result.skipped += 1;
+      continue;
+    }
+
+    if (!dryRun) {
+      try {
+        mkdirSync(dirname(item.destination), { recursive: true });
+        copyFileSync(item.source, item.destination);
+      } catch (error) {
+        result.errors.push({
+          relativePath: item.relativePath,
+          message: error.message,
+        });
+        continue;
+      }
+    }
+
+    if (item.status === "overwrite") result.overwritten += 1;
+    else result.written += 1;
+  }
+
+  return result;
+}
+
+/** Every file under `path`, recursively, minus junk. A file yields itself. */
+function* walkFiles(path) {
+  const stats = statSync(path);
+
+  if (!stats.isDirectory()) {
+    yield path;
+    return;
+  }
+
+  for (const child of readdirSync(path).sort()) {
+    if (isExcluded(child)) continue;
+    yield* walkFiles(join(path, child));
+  }
+}

package/src/kit.mjs

@@ -0,0 +1,94 @@
+/**
+ * What the kit is, and where to find it.
+ *
+ * The copy list is the single fact this whole tool exists to act on. It is
+ * duplicated in exactly two other places — the README quickstart and
+ * NOT_A_FRAMEWORK.md — and nowhere else. Nothing here embeds a copy of the
+ * kit's content: the real directories are read at install time.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Everything a destination project receives, and nothing else.
+ *
+ * Read from copy-list.json rather than declared here, so the list is data with
+ * one home instead of a value restated in every file that needs it. The
+ * validator reads the same file and checks the README and npm's `files`
+ * against it; nothing has to parse this source code to learn the list.
+ *
+ * Deliberately absent from it: CHANGELOG.md and README.md (the kit's own
+ * history and front page, not the project's), .github/, assets/, site/,
+ * packages/, and .features/. A destination project that wants a changelog
+ * starts from templates/CHANGELOG.template.md instead.
+ *
+ * Read with readFileSync rather than a JSON import, which still requires an
+ * import attribute on the Node 18 this package supports.
+ */
+export const COPY_LIST = Object.freeze(
+  JSON.parse(readFileSync(join(HERE, "..", "copy-list.json"), "utf8")).entries,
+);
+
+/**
+ * Junk that is never part of the kit, matched by basename at any depth.
+ *
+ * These are git-ignored in the kit repository, so they exist in a maintainer's
+ * working tree but not in version control — and npm strips them from the
+ * published tarball on its own. Without this list the installer would copy
+ * `skills/.DS_Store` when run from a checkout and not when run from npm, which
+ * is the worst kind of difference: invisible, and only on someone else's
+ * machine.
+ */
+const EXCLUDED = new Set([".DS_Store", "Thumbs.db", "__MACOSX", ".git"]);
+
+export function isExcluded(basename) {
+  return EXCLUDED.has(basename) || basename.startsWith("._");
+}
+
+const PACKAGE_ROOT = resolve(HERE, "..");
+
+/**
+ * Locate the kit directories this tool should copy from.
+ *
+ * Two layouts are possible and both are checked, nearest first:
+ *
+ *   1. Published package — the kit ships inside the tarball alongside this
+ *      code. How it gets there is chunk 2's decision; this resolver only
+ *      requires that it ends up at the package root.
+ *   2. Development — running from a checkout of the kit itself, where the
+ *      package sits at packages/create-pathfinder/ and the kit is two levels up.
+ *
+ * Returns null when neither candidate holds a complete kit, which is a bug in
+ * the package rather than a user error, and is reported as such.
+ */
+export function findKitRoot() {
+  const candidates = [PACKAGE_ROOT, resolve(PACKAGE_ROOT, "..", "..")];
+  return candidates.find(isKitRoot) ?? null;
+}
+
+function isKitRoot(directory) {
+  return COPY_LIST.every((entry) => existsSync(join(directory, entry)));
+}
+
+/**
+ * Find the Git repository containing `startDirectory`, or null.
+ *
+ * Walks the filesystem rather than shelling out to `git`, so the tool works
+ * without the git binary on PATH and cannot be confused by its exit codes.
+ * `.git` is tested with existsSync rather than as a directory because linked
+ * worktrees and submodules use a `.git` *file* pointing elsewhere.
+ */
+export function findGitRoot(startDirectory) {
+  let current = resolve(startDirectory);
+
+  for (;;) {
+    if (existsSync(join(current, ".git"))) return current;
+    const parent = dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}

package/templates/CHANGELOG.template.md

@@ -0,0 +1,11 @@
+# Changelog
+
+Use this file only when the destination project adopts a changelog.
+
+## [Unreleased]
+
+### Added
+
+### Changed
+
+### Fixed

package/templates/feature-spec.template.md

@@ -0,0 +1,99 @@
+# [Feature Name]
+
+## 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?
+
+## Goal
+
+State one user-visible or system-verifiable outcome.
+
+## Dependencies
+
+- Earlier feature, system, decision, prototype, or `None`.
+
+## Requirements
+
+- Requirement 1
+- Requirement 2
+- Requirement 3
+- Include relevant failure, permission, loading, empty, retry, responsive, accessibility, operational, or compatibility states only 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.
+
+## Delivery Chunks
+
+1. `[stable, verifiable increment]`
+2. `[stable, verifiable increment]`
+3. `[optional stable increment]`
+
+Each chunk should leave the project stable.
+
+## 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:
+
+## Suggested Delivery Metadata
+
+- Git action: `[follow project workflow]`
+- Suggested branch, when applicable: `[project naming convention]`
+- Suggested commit, when applicable: `[project convention]`

package/templates/lesson.template.md

@@ -0,0 +1,71 @@
+# Lesson — [Feature Name]
+
+- Date:
+- Branch:
+- Feature spec:
+- Commit or diff range:
+- Difficulty:
+- Estimated review time:
+
+## 1. Feature in One Minute
+
+What changed, why it exists, and the user or system value it creates.
+
+## 2. Mental Model
+
+Explain the feature through one clear model. Include a small Mermaid diagram when useful.
+
+## 3. Execution and Data Flow
+
+Trace one representative interaction from input to visible result.
+
+## 4. Important Files
+
+| File | Responsibility | Why it matters |
+| --- | --- | --- |
+
+## 5. Key Decisions and Tradeoffs
+
+For each meaningful decision:
+
+- Decision
+- Evidence in the repository
+- Benefit
+- Cost
+- Credible alternative
+- When the alternative would be better
+
+## 6. Concepts Worth Retaining
+
+Limit this to the most transferable concepts.
+
+## 7. Quality Lens
+
+### Testing
+
+### Accessibility
+
+### 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.

package/templates/progress-entry.template.md

@@ -0,0 +1,23 @@
+## Progress Update — [Date]
+
+### Lesson
+
+- Feature:
+- Lesson file:
+- Evidence reviewed:
+
+### Concepts
+
+| Concept | Previous | New | Evidence |
+| --- | --- | --- | --- |
+
+### Misconceptions or Gaps
+
+- Gap:
+- Correction:
+- Recommended reinforcement:
+
+### Next Review
+
+- Topic:
+- Suggested timing or trigger: