@forwardimpact/pathway 0.2.0 → 0.4.0

package/app/formatters/job/dom.js

@@ -2,18 +2,7 @@
  * Job formatting for DOM/web output
  */
 
-import {
-  div,
-  h1,
-  h2,
-  p,
-  a,
-  span,
-  button,
-  section,
-  details,
-  summary,
-} from "../../lib/render.js";
+import { div, h1, h2, p, a, span, section } from "../../lib/render.js";
 import { createBackLink } from "../../components/nav.js";
 import {
   createDetailSection,
@@ -25,6 +14,7 @@ import {
 } from "../../components/radar-chart.js";
 import { createSkillMatrix } from "../../components/skill-matrix.js";
 import { createBehaviourProfile } from "../../components/behaviour-profile.js";
+import { createMarkdownTextarea } from "../../components/markdown-textarea.js";
 import { markdownToHtml } from "../../lib/markdown.js";
 import { formatJobDescription } from "./description.js";
 
@@ -39,6 +29,7 @@ import { formatJobDescription } from "./description.js";
  * @param {Object} [options.discipline] - Discipline entity for job description
  * @param {Object} [options.grade] - Grade entity for job description
  * @param {Object} [options.track] - Track entity for job description
+ * @param {string} [options.jobTemplate] - Mustache template for job description
  * @returns {HTMLElement}
  */
 export function jobToDOM(view, options = {}) {
@@ -50,9 +41,10 @@ export function jobToDOM(view, options = {}) {
     discipline,
     grade,
     track,
+    jobTemplate,
   } = options;
 
-  const hasEntities = discipline && grade && track;
+  const hasEntities = discipline && grade && jobTemplate;
 
   return div(
     { className: "job-detail-page" },
@@ -108,6 +100,7 @@ export function jobToDOM(view, options = {}) {
           discipline,
           grade,
           track,
+          template: jobTemplate,
         })
       : null,
 
@@ -140,14 +133,6 @@ export function jobToDOM(view, options = {}) {
                 ),
               })
             : null,
-
-          // Handoff Checklists
-          view.checklists && hasChecklistItems(view.checklists)
-            ? createDetailSection({
-                title: "📋 Handoff Checklists",
-                content: createChecklistSections(view.checklists),
-              })
-            : null,
         )
       : null,
 
@@ -164,6 +149,7 @@ export function jobToDOM(view, options = {}) {
           discipline,
           grade,
           track,
+          template: jobTemplate,
         })
       : null,
   );
@@ -211,84 +197,6 @@ function getScoreColor(score) {
   return "#ef4444"; // Red
 }
 
-/**
- * Check if any checklist has items
- * @param {Object} checklists - Checklists object keyed by handoff type
- * @returns {boolean}
- */
-function hasChecklistItems(checklists) {
-  for (const items of Object.values(checklists)) {
-    if (items && items.length > 0) {
-      return true;
-    }
-  }
-  return false;
-}
-
-/**
- * Create collapsible checklist sections for all handoffs
- * @param {Object} checklists - Checklists object keyed by handoff type
- * @returns {HTMLElement}
- */
-function createChecklistSections(checklists) {
-  const handoffLabels = {
-    plan_to_code: "📋 → 💻 Plan → Code",
-    code_to_review: "💻 → ✅ Code → Review",
-  };
-
-  const sections = Object.entries(checklists)
-    .filter(([_, items]) => items && items.length > 0)
-    .map(([handoff, groups]) => {
-      const label = handoffLabels[handoff] || handoff;
-      const totalItems = groups.reduce((sum, g) => sum + g.items.length, 0);
-
-      return details(
-        { className: "checklist-section" },
-        summary(
-          { className: "checklist-section-header" },
-          span({ className: "checklist-section-label" }, label),
-          span({ className: "badge badge-default" }, `${totalItems} items`),
-        ),
-        div(
-          { className: "checklist-section-content" },
-          ...groups.map((group) => createChecklistGroup(group)),
-        ),
-      );
-    });
-
-  return div({ className: "checklist-sections" }, ...sections);
-}
-
-/**
- * Create a checklist group for a capability
- * @param {Object} group - Group with capability, level, and items
- * @returns {HTMLElement}
- */
-function createChecklistGroup(group) {
-  const emoji = group.capability.emoji || "📌";
-  const capabilityName = group.capability.name || group.capability.id;
-
-  return div(
-    { className: "checklist-group" },
-    div(
-      { className: "checklist-group-header" },
-      span({ className: "checklist-emoji" }, emoji),
-      span({ className: "checklist-capability" }, capabilityName),
-      span({ className: "badge badge-secondary" }, group.level),
-    ),
-    div(
-      { className: "checklist-items" },
-      ...group.items.map((item) =>
-        div(
-          { className: "checklist-item" },
-          span({ className: "checklist-checkbox" }, "☐"),
-          span({}, item),
-        ),
-      ),
-    ),
-  );
-}
-
 /**
  * Create the job description section with copy button
  * @param {Object} params
@@ -296,87 +204,35 @@ function createChecklistGroup(group) {
  * @param {Object} params.discipline - The discipline
  * @param {Object} params.grade - The grade
  * @param {Object} params.track - The track
+ * @param {string} params.template - Mustache template for job description
  * @returns {HTMLElement} The job description section element
  */
-export function createJobDescriptionSection({ job, discipline, grade, track }) {
-  const markdown = formatJobDescription({
-    job,
-    discipline,
-    grade,
-    track,
-  });
-
-  const copyButton = button(
+export function createJobDescriptionSection({
+  job,
+  discipline,
+  grade,
+  track,
+  template,
+}) {
+  const markdown = formatJobDescription(
     {
-      className: "btn btn-primary copy-btn",
-      onClick: async () => {
-        try {
-          await navigator.clipboard.writeText(markdown);
-          copyButton.textContent = "✓ Copied!";
-          copyButton.classList.add("copied");
-          setTimeout(() => {
-            copyButton.textContent = "Copy Markdown";
-            copyButton.classList.remove("copied");
-          }, 2000);
-        } catch (err) {
-          console.error("Failed to copy:", err);
-          copyButton.textContent = "Copy failed";
-          setTimeout(() => {
-            copyButton.textContent = "Copy Markdown";
-          }, 2000);
-        }
-      },
+      job,
+      discipline,
+      grade,
+      track,
     },
-    "Copy Markdown",
+    template,
   );
 
-  const copyHtmlButton = button(
-    {
-      className: "btn btn-secondary copy-btn",
-      onClick: async () => {
-        try {
-          const html = markdownToHtml(markdown);
-          // Use ClipboardItem with text/html MIME type for rich text pasting in Word
-          const blob = new Blob([html], { type: "text/html" });
-          const clipboardItem = new ClipboardItem({ "text/html": blob });
-          await navigator.clipboard.write([clipboardItem]);
-          copyHtmlButton.textContent = "✓ Copied!";
-          copyHtmlButton.classList.add("copied");
-          setTimeout(() => {
-            copyHtmlButton.textContent = "Copy as HTML";
-            copyHtmlButton.classList.remove("copied");
-          }, 2000);
-        } catch (err) {
-          console.error("Failed to copy:", err);
-          copyHtmlButton.textContent = "Copy failed";
-          setTimeout(() => {
-            copyHtmlButton.textContent = "Copy as HTML";
-          }, 2000);
-        }
-      },
-    },
-    "Copy as HTML",
-  );
-
-  const textarea = document.createElement("textarea");
-  textarea.className = "job-description-textarea";
-  textarea.readOnly = true;
-  textarea.value = markdown;
-
   return createDetailSection({
     title: "Job Description",
-    content: div(
-      { className: "job-description-container" },
-      div(
-        { className: "job-description-header" },
-        p(
-          { className: "text-muted" },
-          "Copy this markdown-formatted job description for use in job postings, documentation, or sharing.",
-        ),
-        div({ className: "button-group" }, copyButton, copyHtmlButton),
-      ),
-      textarea,
-    ),
+    content: createMarkdownTextarea({
+      markdown,
+      description:
+        "Copy this markdown-formatted job description for use in job postings, documentation, or sharing.",
+      toHtml: markdownToHtml,
+      minHeight: 450,
+    }),
   });
 }
 
@@ -388,15 +244,25 @@ export function createJobDescriptionSection({ job, discipline, grade, track }) {
  * @param {Object} params.discipline - The discipline
  * @param {Object} params.grade - The grade
  * @param {Object} params.track - The track
+ * @param {string} params.template - Mustache template for job description
  * @returns {HTMLElement} The job description HTML element (print-only)
  */
-export function createJobDescriptionHtml({ job, discipline, grade, track }) {
-  const markdown = formatJobDescription({
-    job,
-    discipline,
-    grade,
-    track,
-  });
+export function createJobDescriptionHtml({
+  job,
+  discipline,
+  grade,
+  track,
+  template,
+}) {
+  const markdown = formatJobDescription(
+    {
+      job,
+      discipline,
+      grade,
+      track,
+    },
+    template,
+  );
 
   const html = markdownToHtml(markdown);
 

package/app/formatters/job/markdown.js

@@ -15,9 +15,10 @@ import { SKILL_LEVEL_ORDER } from "../../model/levels.js";
  * Format job detail as markdown
  * @param {Object} view - Job detail view from presenter
  * @param {Object} [entities] - Original entities (for job description)
+ * @param {string} [jobTemplate] - Mustache template for job description
  * @returns {string}
  */
-export function jobToMarkdown(view, entities = {}) {
+export function jobToMarkdown(view, entities = {}, jobTemplate) {
   const lines = [
     `# ${view.title}`,
     "",
@@ -77,23 +78,26 @@ export function jobToMarkdown(view, entities = {}) {
   }
 
   // Job Description (copyable markdown)
-  if (entities.discipline && entities.grade && entities.track) {
+  if (entities.discipline && entities.grade && jobTemplate) {
     lines.push("---", "");
     lines.push("## Job Description", "");
     lines.push("```markdown");
     lines.push(
-      formatJobDescription({
-        job: {
-          title: view.title,
-          skillMatrix: view.skillMatrix,
-          behaviourProfile: view.behaviourProfile,
-          expectations: view.expectations,
-          derivedResponsibilities: view.derivedResponsibilities,
+      formatJobDescription(
+        {
+          job: {
+            title: view.title,
+            skillMatrix: view.skillMatrix,
+            behaviourProfile: view.behaviourProfile,
+            expectations: view.expectations,
+            derivedResponsibilities: view.derivedResponsibilities,
+          },
+          discipline: entities.discipline,
+          grade: entities.grade,
+          track: entities.track,
         },
-        discipline: entities.discipline,
-        grade: entities.grade,
-        track: entities.track,
-      }),
+        jobTemplate,
+      ),
     );
     lines.push("```");
   }

package/app/formatters/shared.js

@@ -4,6 +4,64 @@
  * Common formatting functions used across different output formats (CLI, DOM, markdown)
  */
 
+/**
+ * Trim trailing newlines from a string value
+ * Used by template prepare functions for consistent output formatting.
+ * @param {string|null|undefined} value - Value to trim
+ * @returns {string|null} Trimmed value or null if empty
+ */
+export function trimValue(value) {
+  if (value == null) return null;
+  const trimmed = value.replace(/\n+$/, "");
+  return trimmed || null;
+}
+
+/**
+ * Trim a required field, preserving original if trim would result in empty
+ * Use for fields that must have a value.
+ * @param {string|null|undefined} value - Value to trim
+ * @returns {string} Trimmed value or original
+ */
+export function trimRequired(value) {
+  return trimValue(value) || value || "";
+}
+
+/**
+ * Trim and split a string into lines
+ * @param {string|null|undefined} value - Value to process
+ * @returns {string[]} Array of lines (empty array if no value)
+ */
+export function splitLines(value) {
+  const trimmed = trimValue(value);
+  return trimmed ? trimmed.split("\n") : [];
+}
+
+/**
+ * Transform an array of objects by applying trimValue to specified fields
+ * @param {Array<Object>} array - Array of objects to transform
+ * @param {Object<string, 'optional'|'required'|'array'>} fieldSpec - Fields to trim and their type
+ *   - 'optional': use trimValue (returns null if empty)
+ *   - 'required': use trimRequired (preserves original if empty)
+ *   - 'array': trim each element in array field
+ * @returns {Array<Object>} Transformed array
+ */
+export function trimFields(array, fieldSpec) {
+  if (!array) return [];
+  return array.map((item) => {
+    const result = { ...item };
+    for (const [field, type] of Object.entries(fieldSpec)) {
+      if (type === "optional") {
+        result[field] = trimValue(item[field]);
+      } else if (type === "required") {
+        result[field] = trimRequired(item[field]);
+      } else if (type === "array") {
+        result[field] = (item[field] || []).map((v) => trimRequired(v));
+      }
+    }
+    return result;
+  });
+}
+
 /**
  * Format level as text with dots (for CLI/markdown)
  * @param {number} level - 1-5
@@ -36,7 +94,7 @@ export function tableToMarkdown(headers, rows) {
 export function objectToMarkdownList(obj, indent = 0) {
   const prefix = "  ".repeat(indent);
   return Object.entries(obj)
-    .map(([key, value]) => `${prefix}- **${key}**: ${value}`)
+    .map(([key, value]) => `${prefix}- **${capitalize(key)}**: ${value}`)
     .join("\n");
 }
 
@@ -51,12 +109,17 @@ export function formatPercent(value) {
 
 /**
  * Capitalize first letter of each word
+ * Handles both snake_case and camelCase
  * @param {string} str
  * @returns {string}
  */
 export function capitalize(str) {
   if (!str) return "";
-  return str.replace(/_/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+  // Insert space before uppercase letters (for camelCase), then handle snake_case
+  return str
+    .replace(/([a-z])([A-Z])/g, "$1 $2")
+    .replace(/_/g, " ")
+    .replace(/\b\w/g, (c) => c.toUpperCase());
 }
 
 /**

package/app/formatters/skill/dom.js

@@ -18,8 +18,9 @@ import {
 } from "../../lib/render.js";
 import { createBackLink } from "../../components/nav.js";
 import { createLevelCell } from "../../components/detail.js";
+import { createMarkdownTextarea } from "../../components/markdown-textarea.js";
 import { SKILL_LEVEL_ORDER } from "../../model/levels.js";
-import { prepareSkillDetail, formatCapability } from "./shared.js";
+import { prepareSkillDetail } from "./shared.js";
 import { createJsonLdScript, skillToJsonLd } from "../json-ld.js";
 
 /**
@@ -61,7 +62,7 @@ export function skillToDOM(
         { className: "page-meta" },
         span(
           { className: "badge badge-default" },
-          formatCapability(view.capability),
+          `${view.capabilityEmoji} ${view.capability.toUpperCase()}`,
         ),
         view.isHumanOnly
           ? span(
@@ -97,6 +98,60 @@ export function skillToDOM(
       ),
     ),
 
+    // Recommended Tools
+    view.toolReferences.length > 0
+      ? div(
+          { className: "detail-section" },
+          heading2({ className: "section-title" }, "Recommended Tools"),
+          table(
+            { className: "tools-table" },
+            thead({}, tr({}, th({}, "Tool"), th({}, "Use When"))),
+            tbody(
+              {},
+              ...view.toolReferences.map((tool) =>
+                tr(
+                  {},
+                  td(
+                    {},
+                    tool.url
+                      ? a(
+                          {
+                            href: tool.url,
+                            target: "_blank",
+                            rel: "noopener noreferrer",
+                          },
+                          tool.name,
+                        )
+                      : tool.name,
+                  ),
+                  td({}, tool.useWhen),
+                ),
+              ),
+            ),
+          ),
+          showBackLink
+            ? p(
+                { className: "see-all-link" },
+                a({ href: "#/tool" }, "See all tools →"),
+              )
+            : null,
+        )
+      : null,
+
+    // Implementation Reference
+    view.implementationReference
+      ? div(
+          { className: "detail-section" },
+          heading2({ className: "section-title" }, "Implementation Patterns"),
+          createMarkdownTextarea({
+            markdown: view.implementationReference,
+            description:
+              "Project-specific implementation guidance for this skill.",
+            minHeight: 450,
+          }),
+        )
+      : null,
+
     // Used in Disciplines and Linked to Drivers in two columns
     view.relatedDisciplines.length > 0 || view.relatedDrivers.length > 0
       ? div(

package/app/formatters/skill/markdown.js

@@ -105,5 +105,23 @@ export function skillToMarkdown(
     lines.push("");
   }
 
+  // Recommended tools
+  if (view.toolReferences.length > 0) {
+    lines.push("## Recommended Tools", "");
+    const toolRows = view.toolReferences.map((tool) => [
+      tool.url ? `[${tool.name}](${tool.url})` : tool.name,
+      tool.useWhen,
+    ]);
+    lines.push(tableToMarkdown(["Tool", "Use When"], toolRows));
+    lines.push("");
+  }
+
+  // Implementation reference
+  if (view.implementationReference) {
+    lines.push("## Implementation Patterns", "");
+    lines.push(view.implementationReference);
+    lines.push("");
+  }
+
   return lines.join("\n");
 }

package/app/formatters/skill/shared.js

@@ -13,12 +13,12 @@ import { truncate } from "../shared.js";
 
 /**
  * Format capability name for display
- * @param {string} capability
+ * @param {string} capabilityName - The capability name to display
  * @returns {string}
  */
-export function formatCapability(capability) {
-  if (!capability) return "";
-  return capability.charAt(0).toUpperCase() + capability.slice(1);
+export function formatCapability(capabilityName) {
+  if (!capabilityName) return "";
+  return capabilityName;
 }
 
 /**
@@ -66,12 +66,15 @@ export function prepareSkillsList(
  * @property {string} name
  * @property {string} description
  * @property {string} capability
+ * @property {string} capabilityName
  * @property {boolean} isHumanOnly
  * @property {string} capabilityEmoji
  * @property {Object<string, string>} levelDescriptions
  * @property {Array<{id: string, name: string, skillType: string}>} relatedDisciplines
  * @property {Array<{id: string, name: string, modifier: number}>} relatedTracks
  * @property {Array<{id: string, name: string}>} relatedDrivers
+ * @property {Array<{name: string, url?: string, description: string, useWhen: string}>} toolReferences
+ * @property {string|null} implementationReference
  */
 
 /**
@@ -110,16 +113,21 @@ export function prepareSkillDetail(
     .filter((d) => d.contributingSkills?.includes(skill.id))
     .map((d) => ({ id: d.id, name: d.name }));
 
+  const capabilityEntity = capabilities.find((c) => c.id === skill.capability);
+
   return {
     id: skill.id,
     name: skill.name,
     description: skill.description,
     capability: skill.capability,
+    capabilityName: capabilityEntity?.name || skill.capability,
     isHumanOnly: skill.isHumanOnly || false,
     capabilityEmoji: getCapabilityEmoji(capabilities, skill.capability),
     levelDescriptions: skill.levelDescriptions,
     relatedDisciplines,
     relatedTracks,
     relatedDrivers,
+    toolReferences: skill.toolReferences || [],
+    implementationReference: skill.implementationReference || null,
   };
 }

package/app/formatters/stage/microdata.js

@@ -32,7 +32,7 @@ export function stageListToMicrodata(stages) {
           ? `→ ${stage.handoffs.map((h) => h.target).join(", ")}`
           : "";
       return `${openTag("article", { itemtype: "Stage", itemid: `#${stage.id}` })}
-${prop("h2", "name", `${stage.emoji || ""} ${stage.name}`)}
+${prop("h2", "name", `${stage.emoji} ${stage.name}`)}
 ${prop("p", "description", stage.truncatedDescription)}
 ${handoffText ? `<p>Handoffs: ${handoffText}</p>` : ""}
 </article>`;

package/app/formatters/stage/shared.js

@@ -80,5 +80,5 @@ export function prepareStageDetail(stage) {
  */
 export function getStageEmoji(stages, stageId) {
   const stage = stages.find((s) => s.id === stageId);
-  return stage?.emoji || "🔄";
+  return stage?.emoji;
 }

package/app/formatters/tool/shared.js

@@ -0,0 +1,72 @@
+/**
+ * Tool presentation helpers
+ *
+ * Shared utilities for formatting tool data across DOM and CLI outputs.
+ */
+
+/**
+ * @typedef {Object} ToolUsage
+ * @property {string} skillId
+ * @property {string} skillName
+ * @property {string} capabilityId
+ * @property {string} useWhen
+ */
+
+/**
+ * @typedef {Object} AggregatedTool
+ * @property {string} name
+ * @property {string} [url]
+ * @property {string} description
+ * @property {ToolUsage[]} usages
+ */
+
+/**
+ * Aggregate tools from all skills, deduplicating by name
+ * @param {Array} skills - All skills with toolReferences
+ * @returns {AggregatedTool[]}
+ */
+export function aggregateTools(skills) {
+  const toolMap = new Map();
+
+  for (const skill of skills) {
+    if (!skill.toolReferences) continue;
+
+    for (const tool of skill.toolReferences) {
+      const usage = {
+        skillId: skill.id,
+        skillName: skill.name,
+        capabilityId: skill.capability,
+        useWhen: tool.useWhen,
+      };
+
+      const existing = toolMap.get(tool.name);
+      if (existing) {
+        existing.usages.push(usage);
+      } else {
+        toolMap.set(tool.name, {
+          name: tool.name,
+          url: tool.url,
+          description: tool.description,
+          usages: [usage],
+        });
+      }
+    }
+  }
+
+  return Array.from(toolMap.values()).sort((a, b) =>
+    a.name.localeCompare(b.name),
+  );
+}
+
+/**
+ * Prepare tools list view data
+ * @param {Array} skills - All skills
+ * @returns {{ tools: AggregatedTool[], totalCount: number }}
+ */
+export function prepareToolsList(skills) {
+  const tools = aggregateTools(skills);
+  return {
+    tools,
+    totalCount: tools.length,
+  };
+}