@forwardimpact/pathway 0.3.0 → 0.5.0

package/app/css/pages/job-builder.css

@@ -89,46 +89,4 @@
     font-weight: 600;
     color: var(--color-primary);
   }
-
-  /* Job description section */
-  .job-description-container {
-    display: flex;
-    flex-direction: column;
-    gap: var(--space-md);
-  }
-
-  .job-description-header {
-    display: flex;
-    justify-content: space-between;
-    align-items: center;
-    flex-wrap: wrap;
-    gap: var(--space-md);
-  }
-
-  .job-description-header .text-muted {
-    margin: 0;
-    flex: 1;
-    min-width: 200px;
-  }
-
-  .job-description-textarea {
-    width: 100%;
-    min-height: 400px;
-    padding: var(--space-md);
-    font-family:
-      ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, monospace;
-    font-size: var(--font-size-sm);
-    line-height: 1.6;
-    background-color: var(--color-bg);
-    border: 1px solid var(--color-border);
-    border-radius: var(--radius-md);
-    resize: vertical;
-    color: var(--color-text);
-  }
-
-  .job-description-textarea:focus {
-    outline: none;
-    border-color: var(--color-primary);
-    box-shadow: 0 0 0 3px rgba(59, 130, 246, 0.1);
-  }
 }

package/app/css/tokens.css

@@ -130,6 +130,9 @@
     --font-family:
       system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto,
       sans-serif;
+    --font-family-mono:
+      "JetBrains Mono", ui-monospace, SFMono-Regular, "SF Mono", Menlo,
+      Consolas, monospace;
     --font-size-xs: 0.75rem;
     --font-size-sm: 0.875rem;
     --font-size-base: 1rem;

package/app/formatters/agent/dom.js

@@ -16,6 +16,7 @@ import {
   details,
   summary,
 } from "../../lib/render.js";
+import { createCodeDisplay } from "../../components/code-display.js";
 import { formatAgentProfile } from "./profile.js";
 import { formatAgentSkill } from "./skill.js";
 import { getStageEmoji } from "../stage/shared.js";
@@ -53,13 +54,12 @@ export function agentDeploymentToDOM({
     // Profile section
     section(
       { className: "agent-section" },
-      div(
-        { className: "section-header" },
-        h2({}, "Agent Profile"),
-        createCopyButton(profileContent),
-      ),
-      p({ className: "filename" }, profile.filename),
-      createCodeBlock(profileContent),
+      h2({}, "Agent Profile"),
+      createCodeDisplay({
+        content: profileContent,
+        filename: profile.filename,
+        maxHeight: 600,
+      }),
     ),
 
     // Role Agents section
@@ -145,48 +145,6 @@ function createDownloadButton(
   return btn;
 }
 
-/**
- * Create a copy button for content
- * @param {string} content - Content to copy
- * @returns {HTMLElement}
- */
-function createCopyButton(content) {
-  const btn = button({ className: "btn btn-sm copy-btn" }, "📋 Copy");
-
-  btn.addEventListener("click", async () => {
-    try {
-      await navigator.clipboard.writeText(content);
-      btn.textContent = "✓ Copied";
-      setTimeout(() => {
-        btn.textContent = "📋 Copy";
-      }, 2000);
-    } catch {
-      btn.textContent = "Failed";
-      setTimeout(() => {
-        btn.textContent = "📋 Copy";
-      }, 2000);
-    }
-  });
-
-  return btn;
-}
-
-/**
- * Create a code block with content
- * @param {string} content - Code content
- * @returns {HTMLElement}
- */
-function createCodeBlock(content) {
-  const pre = document.createElement("pre");
-  pre.className = "code-block";
-
-  const code = document.createElement("code");
-  code.textContent = content;
-
-  pre.appendChild(code);
-  return pre;
-}
-
 /**
  * Create a skill card with content and copy button
  * @param {Object} skill - Skill with frontmatter and body
@@ -198,12 +156,11 @@ function createSkillCard(skill) {
 
   return div(
     { className: "skill-card" },
-    div(
-      { className: "skill-header" },
-      span({ className: "skill-filename" }, filename),
-      createCopyButton(content),
-    ),
-    createCodeBlock(content),
+    createCodeDisplay({
+      content,
+      filename,
+      maxHeight: 300,
+    }),
   );
 }
 
@@ -235,8 +192,10 @@ function createRoleAgentCard(agent) {
         { className: "text-muted role-description" },
         agent.frontmatter.description,
       ),
-      div({ className: "role-agent-actions" }, createCopyButton(content)),
-      createCodeBlock(content),
+      createCodeDisplay({
+        content,
+        maxHeight: 400,
+      }),
     ),
   );
 }
@@ -254,13 +213,10 @@ function createCliCommand(agentName) {
 
   const command = `npx pathway agent ${discipline} ${track} --output=.github --all-roles`;
 
-  const container = div(
-    { className: "cli-command" },
-    createCodeBlock(command),
-    createCopyButton(command),
-  );
-
-  return container;
+  return createCodeDisplay({
+    content: command,
+    language: "bash",
+  });
 }
 
 /**
@@ -445,13 +401,12 @@ export function stageAgentToDOM(stageAgent, profile, options = {}) {
     // Profile section
     section(
       { className: "agent-section" },
-      div(
-        { className: "section-header" },
-        h3({}, "Agent Profile"),
-        createCopyButton(profileContent),
-      ),
-      p({ className: "filename" }, profile.filename),
-      createCodeBlock(profileContent),
+      h3({}, "Agent Profile"),
+      createCodeDisplay({
+        content: profileContent,
+        filename: profile.filename,
+        maxHeight: 600,
+      }),
     ),
 
     // Download button

package/app/formatters/agent/profile.js

@@ -10,6 +10,71 @@
 
 import Mustache from "mustache";
 
+import { trimValue, trimRequired, trimFields } from "../shared.js";
+
+/**
+ * Prepare agent profile data for template rendering
+ * Normalizes string values by trimming trailing newlines for consistent template output.
+ * @param {Object} params
+ * @param {Object} params.frontmatter - YAML frontmatter data
+ * @param {string} params.frontmatter.name - Agent name
+ * @param {string} params.frontmatter.description - Agent description
+ * @param {boolean} params.frontmatter.infer - Whether to auto-select
+ * @param {Array} [params.frontmatter.handoffs] - Handoff definitions
+ * @param {Object} params.bodyData - Structured body data
+ * @param {string} params.bodyData.title - Agent title
+ * @param {string} params.bodyData.stageDescription - Stage description text
+ * @param {string} params.bodyData.identity - Core identity text
+ * @param {string} [params.bodyData.priority] - Priority/philosophy statement
+ * @param {Array<{name: string, dirname: string, useWhen: string}>} params.bodyData.skillIndex - Skill index entries
+ * @param {Array<{index: number, text: string}>} params.bodyData.beforeMakingChanges - Numbered steps
+ * @param {string} [params.bodyData.delegation] - Delegation guidance
+ * @param {string} params.bodyData.operationalContext - Operational context text
+ * @param {string} params.bodyData.workingStyle - Working style markdown section
+ * @param {string} [params.bodyData.beforeHandoff] - Before handoff checklist markdown
+ * @param {string[]} params.bodyData.constraints - List of constraints
+ * @returns {Object} Data object ready for Mustache template
+ */
+function prepareAgentProfileData({ frontmatter, bodyData }) {
+  // Trim array fields using helpers
+  const handoffs = trimFields(frontmatter.handoffs, { prompt: "required" });
+  const beforeMakingChanges = trimFields(bodyData.beforeMakingChanges, {
+    text: "required",
+  });
+
+  // Trim simple string arrays
+  const constraints = (bodyData.constraints || []).map((c) => trimRequired(c));
+
+  // Trim skill index entries
+  const skillIndex = (bodyData.skillIndex || []).map((s) => ({
+    name: trimRequired(s.name),
+    dirname: trimRequired(s.dirname),
+    useWhen: trimRequired(s.useWhen),
+  }));
+
+  return {
+    // Frontmatter
+    name: frontmatter.name,
+    description: trimRequired(frontmatter.description),
+    infer: frontmatter.infer,
+    handoffs,
+
+    // Body data - trim all string fields
+    title: bodyData.title,
+    stageDescription: trimValue(bodyData.stageDescription),
+    identity: trimValue(bodyData.identity),
+    priority: trimValue(bodyData.priority),
+    skillIndex,
+    hasSkills: skillIndex.length > 0,
+    beforeMakingChanges,
+    delegation: trimValue(bodyData.delegation),
+    operationalContext: trimValue(bodyData.operationalContext),
+    workingStyle: trimValue(bodyData.workingStyle),
+    beforeHandoff: trimValue(bodyData.beforeHandoff),
+    constraints,
+  };
+}
+
 /**
  * Format agent profile as .agent.md file content using Mustache template
  * @param {Object} profile - Profile with frontmatter and bodyData
@@ -24,7 +89,7 @@ import Mustache from "mustache";
  * @param {string} profile.bodyData.stageDescription - Stage description text
  * @param {string} profile.bodyData.identity - Core identity text
  * @param {string} [profile.bodyData.priority] - Priority/philosophy statement (optional)
- * @param {string[]} profile.bodyData.capabilities - List of capability names
+ * @param {Array<{name: string, dirname: string, useWhen: string}>} profile.bodyData.skillIndex - Skill index entries
  * @param {Array<{index: number, text: string}>} profile.bodyData.beforeMakingChanges - Numbered steps
  * @param {string} [profile.bodyData.delegation] - Delegation guidance (optional)
  * @param {string} profile.bodyData.operationalContext - Operational context text
@@ -35,14 +100,6 @@ import Mustache from "mustache";
  * @returns {string} Complete .agent.md file content
  */
 export function formatAgentProfile({ frontmatter, bodyData }, template) {
-  const data = {
-    // Frontmatter
-    name: frontmatter.name,
-    description: frontmatter.description,
-    infer: frontmatter.infer,
-    handoffs: frontmatter.handoffs || [],
-    // Body data
-    ...bodyData,
-  };
+  const data = prepareAgentProfileData({ frontmatter, bodyData });
   return Mustache.render(template, data);
 }

package/app/formatters/agent/skill.js

@@ -10,6 +10,47 @@
 
 import Mustache from "mustache";
 
+import { trimValue, splitLines, trimFields } from "../shared.js";
+
+/**
+ * Prepare agent skill data for template rendering
+ * Normalizes string values by trimming trailing newlines for consistent template output.
+ * @param {Object} params
+ * @param {Object} params.frontmatter - YAML frontmatter data
+ * @param {string} params.frontmatter.name - Skill name (required)
+ * @param {string} params.frontmatter.description - Skill description (required)
+ * @param {string} [params.frontmatter.useWhen] - When to use this skill
+ * @param {string} params.title - Human-readable skill title for heading
+ * @param {Array} params.stages - Array of stage objects with stageName, focus, activities, ready
+ * @param {string} params.reference - Reference content (markdown)
+ * @param {Array} [params.toolReferences] - Array of tool reference objects
+ * @returns {Object} Data object ready for Mustache template
+ */
+function prepareAgentSkillData({
+  frontmatter,
+  title,
+  stages,
+  reference,
+  toolReferences,
+}) {
+  // Process stages - trim focus and array values
+  const processedStages = trimFields(stages, {
+    focus: "required",
+    activities: "array",
+    ready: "array",
+  });
+
+  return {
+    name: frontmatter.name,
+    descriptionLines: splitLines(frontmatter.description),
+    useWhenLines: splitLines(frontmatter.useWhen),
+    title,
+    stages: processedStages,
+    reference: trimValue(reference) || "",
+    toolReferences: toolReferences || [],
+  };
+}
+
 /**
  * Format agent skill as SKILL.md file content using Mustache template
  * @param {Object} skill - Skill with frontmatter, title, stages, reference
@@ -19,19 +60,20 @@ import Mustache from "mustache";
  * @param {string} skill.title - Human-readable skill title for heading
  * @param {Array} skill.stages - Array of stage objects with stageName, focus, activities, ready
  * @param {string} skill.reference - Reference content (markdown)
+ * @param {Array} [skill.toolReferences] - Array of tool reference objects
  * @param {string} template - Mustache template string
  * @returns {string} Complete SKILL.md file content
  */
 export function formatAgentSkill(
-  { frontmatter, title, stages, reference },
+  { frontmatter, title, stages, reference, toolReferences },
   template,
 ) {
-  const data = {
-    name: frontmatter.name,
-    descriptionLines: frontmatter.description.trim().split("\n"),
+  const data = prepareAgentSkillData({
+    frontmatter,
     title,
     stages,
-    reference: reference ? reference.trim() : "",
-  };
+    reference,
+    toolReferences,
+  });
   return Mustache.render(template, data);
 }

package/app/formatters/grade/dom.js

@@ -77,16 +77,16 @@ export function gradeToDOM(grade, { framework, showBackLink = true } = {}) {
             { className: "content-columns" },
             view.professionalTitle
               ? div(
-                  { className: "list-item" },
+                  { className: "card" },
                   p({ className: "label" }, "Professional Track"),
-                  p({}, view.professionalTitle),
+                  p({ className: "card-description" }, view.professionalTitle),
                 )
               : null,
             view.managementTitle
               ? div(
-                  { className: "list-item" },
+                  { className: "card" },
                   p({ className: "label" }, "Management Track"),
-                  p({}, view.managementTitle),
+                  p({ className: "card-description" }, view.managementTitle),
                 )
               : null,
           ),
@@ -102,9 +102,9 @@ export function gradeToDOM(grade, { framework, showBackLink = true } = {}) {
             { className: "content-columns" },
             ...Object.entries(view.expectations).map(([key, value]) =>
               div(
-                { className: "list-item" },
+                { className: "card" },
                 p({ className: "label" }, formatLevel(key)),
-                p({}, value),
+                p({ className: "card-description" }, value),
               ),
             ),
           ),

package/app/formatters/job/description.js

@@ -14,6 +14,7 @@ import {
   SKILL_LEVEL_ORDER,
   BEHAVIOUR_MATURITY_ORDER,
 } from "../../model/levels.js";
+import { trimValue, trimFields } from "../shared.js";
 
 /**
  * Prepare job data for template rendering
@@ -121,28 +122,32 @@ function prepareJobDescriptionData({ job, discipline, grade, track }) {
     };
   });
 
+  // Build qualification summary with placeholder replacement
+  const qualificationSummary =
+    (grade.qualificationSummary || "").replace(
+      /\{typicalExperienceRange\}/g,
+      grade.typicalExperienceRange || "",
+    ) || null;
+
   return {
     title: job.title,
     gradeId: grade.id,
     typicalExperienceRange: grade.typicalExperienceRange,
     trackName: track?.name || null,
-    roleSummary,
-    trackRoleContext: track?.roleContext || null,
-    expectationsParagraph: expectationsParagraph || null,
-    responsibilities: (job.derivedResponsibilities || []).map((r) => ({
-      capabilityName: r.capabilityName,
-      responsibility: r.responsibility,
-    })),
-    behaviours: sortedBehaviours.map((b) => ({
-      behaviourName: b.behaviourName,
-      maturityDescription: b.maturityDescription || "",
+    roleSummary: trimValue(roleSummary),
+    trackRoleContext: trimValue(track?.roleContext),
+    expectationsParagraph: trimValue(expectationsParagraph),
+    responsibilities: trimFields(job.derivedResponsibilities, {
+      responsibility: "required",
+    }),
+    behaviours: trimFields(sortedBehaviours, {
+      maturityDescription: "optional",
+    }),
+    skillLevels: skillLevels.map((level) => ({
+      ...level,
+      skills: trimFields(level.skills, { levelDescription: "optional" }),
     })),
-    skillLevels,
-    qualificationSummary:
-      (grade.qualificationSummary || "").replace(
-        /\{typicalExperienceRange\}/g,
-        grade.typicalExperienceRange || "",
-      ) || null,
+    qualificationSummary: trimValue(qualificationSummary),
   };
 }
 

package/app/formatters/job/dom.js

@@ -2,7 +2,7 @@
  * Job formatting for DOM/web output
  */
 
-import { div, h1, h2, p, a, span, button, section } from "../../lib/render.js";
+import { div, h1, h2, p, a, span, section } from "../../lib/render.js";
 import { createBackLink } from "../../components/nav.js";
 import {
   createDetailSection,
@@ -14,6 +14,7 @@ import {
 } from "../../components/radar-chart.js";
 import { createSkillMatrix } from "../../components/skill-matrix.js";
 import { createBehaviourProfile } from "../../components/behaviour-profile.js";
+import { createCodeDisplay } from "../../components/code-display.js";
 import { markdownToHtml } from "../../lib/markdown.js";
 import { formatJobDescription } from "./description.js";
 
@@ -223,77 +224,15 @@ export function createJobDescriptionSection({
     template,
   );
 
-  const copyButton = button(
-    {
-      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);
-        }
-      },
-    },
-    "Copy Markdown",
-  );
-
-  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: createCodeDisplay({
+      content: markdown,
+      description:
+        "Copy this markdown-formatted job description for use in job postings, documentation, or sharing.",
+      toHtml: markdownToHtml,
+      minHeight: 450,
+    }),
   });
 }
 

package/app/formatters/json-ld.js

@@ -228,7 +228,7 @@ export function stageToJsonLd(stage) {
     identifier: stage.id,
     name: stage.name,
     description: stage.description,
-    ...(stage.emoji && { emoji: stage.emoji }),
+    ...(stage.emojiIcon && { emojiIcon: stage.emojiIcon }),
     ...(stage.tools?.length > 0 && { tools: stage.tools }),
     ...(stage.constraints?.length > 0 && { constraints: stage.constraints }),
     ...(stage.handoffs && {

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