@forwardimpact/pathway 0.1.0

package/app/formatters/stage/shared.js

@@ -0,0 +1,111 @@
+/**
+ * Stage presentation helpers
+ *
+ * Shared utilities for formatting stage data across DOM and CLI outputs.
+ */
+
+import { truncate } from "../shared.js";
+
+/**
+ * Tool display configuration
+ * @type {Object<string, {icon: string, label: string}>}
+ */
+const TOOL_CONFIG = {
+  search: { icon: "🔍", label: "Search" },
+  fetch: { icon: "🌐", label: "Fetch" },
+  codebase: { icon: "📂", label: "Codebase" },
+  read: { icon: "📖", label: "Read" },
+  edit: { icon: "✏️", label: "Edit" },
+  terminal: { icon: "💻", label: "Terminal" },
+};
+
+/**
+ * @typedef {Object} StageListItem
+ * @property {string} id
+ * @property {string} name
+ * @property {string} emoji
+ * @property {string} description
+ * @property {string} truncatedDescription
+ * @property {Array<{id: string, icon: string, label: string}>} tools
+ * @property {Array<{target: string, label: string}>} handoffs
+ */
+
+/**
+ * Transform stages for list view
+ * @param {Array} stages - Raw stage entities
+ * @param {number} [descriptionLimit=150] - Maximum description length
+ * @returns {{ items: StageListItem[] }}
+ */
+export function prepareStagesList(stages, descriptionLimit = 150) {
+  const items = stages.map((stage) => {
+    const tools = stage.availableTools || [];
+    return {
+      id: stage.id,
+      name: stage.name,
+      emoji: stage.emoji,
+      description: stage.description,
+      truncatedDescription: truncate(stage.description, descriptionLimit),
+      tools: tools.map((toolId) => ({
+        id: toolId,
+        icon: TOOL_CONFIG[toolId]?.icon || "🔧",
+        label: TOOL_CONFIG[toolId]?.label || toolId,
+      })),
+      handoffs: (stage.handoffs || []).map((h) => ({
+        target: h.targetStage,
+        label: h.label,
+      })),
+    };
+  });
+
+  return { items };
+}
+
+/**
+ * @typedef {Object} StageDetailView
+ * @property {string} id
+ * @property {string} name
+ * @property {string} description
+ * @property {Array<{id: string, icon: string, label: string}>} tools
+ * @property {string[]} constraints
+ * @property {string[]} entryCriteria
+ * @property {string[]} exitCriteria
+ * @property {Array<{target: string, label: string, prompt: string}>} handoffs
+ */
+
+/**
+ * Transform stage for detail view
+ * @param {Object} stage - Raw stage entity
+ * @returns {StageDetailView}
+ */
+export function prepareStageDetail(stage) {
+  const tools = stage.availableTools || [];
+  return {
+    id: stage.id,
+    name: stage.name,
+    description: stage.description,
+    tools: tools.map((toolId) => ({
+      id: toolId,
+      icon: TOOL_CONFIG[toolId]?.icon || "🔧",
+      label: TOOL_CONFIG[toolId]?.label || toolId,
+    })),
+    constraints: stage.constraints || [],
+    entryCriteria: stage.entryCriteria || [],
+    exitCriteria: stage.exitCriteria || [],
+    handoffs: (stage.handoffs || []).map((h) => ({
+      target: h.targetStage,
+      label: h.label,
+      prompt: h.prompt,
+    })),
+  };
+}
+
+/**
+ * Get the stage emoji from loaded stages data
+ * @param {Object[]} stages - Loaded stages array
+ * @param {string} stageId - Stage identifier
+ * @returns {string}
+ */
+export function getStageEmoji(stages, stageId) {
+  const stage = stages.find((s) => s.id === stageId);
+  return stage?.emoji || "🔄";
+}

package/app/formatters/track/dom.js

@@ -0,0 +1,128 @@
+/**
+ * Track formatting for DOM/web output
+ */
+
+import { div, h1, p } from "../../lib/render.js";
+import { createBackLink } from "../../components/nav.js";
+import { createBadge, createStatCard } from "../../components/card.js";
+import { createStatsGrid } from "../../components/grid.js";
+import {
+  createDetailSection,
+  createLinksList,
+} from "../../components/detail.js";
+import {
+  createJobBuilderButton,
+  createInterviewPrepButton,
+} from "../../components/action-buttons.js";
+import {
+  createBehaviourModifierTable,
+  createSkillModifierTableWithCapabilities,
+} from "../../components/modifier-table.js";
+import { getConceptEmoji } from "../../model/levels.js";
+import { prepareTrackDetail } from "./shared.js";
+
+/**
+ * Get track type badge(s)
+ * @param {Object} view
+ * @returns {HTMLElement[]}
+ */
+function getTrackTypeBadges(view) {
+  const badges = [];
+  if (view.isProfessional) {
+    badges.push(createBadge("Professional", "secondary"));
+  }
+  if (view.isManagement) {
+    badges.push(createBadge("Management", "default"));
+  }
+  return badges;
+}
+
+/**
+ * Format track detail as DOM elements
+ * @param {Object} track - Raw track entity
+ * @param {Object} context - Additional context
+ * @param {Array} context.skills - All skills
+ * @param {Array} context.behaviours - All behaviours
+ * @param {Array} context.disciplines - All disciplines
+ * @param {Object} [context.framework] - Framework data for emoji lookup
+ * @returns {HTMLElement}
+ */
+export function trackToDOM(
+  track,
+  { skills, behaviours, disciplines, framework },
+) {
+  const view = prepareTrackDetail(track, { skills, behaviours, disciplines });
+  const emoji = getConceptEmoji(framework, "track");
+  // Build modifier sections - group them together for print layout
+  const hasSkillModifiers = view.skillModifiers.length > 0;
+  const hasBehaviourModifiers = view.behaviourModifiers.length > 0;
+
+  const modifiersSection =
+    hasSkillModifiers || hasBehaviourModifiers
+      ? div(
+          { className: "print-columns" },
+          hasSkillModifiers
+            ? createDetailSection({
+                title: "Skill Modifiers",
+                content: createSkillModifierTableWithCapabilities(
+                  view.skillModifiers,
+                ),
+              })
+            : null,
+          hasBehaviourModifiers
+            ? createDetailSection({
+                title: "Behaviour Modifiers",
+                content: createBehaviourModifierTable(view.behaviourModifiers),
+              })
+            : null,
+        )
+      : null;
+
+  return div(
+    { className: "detail-page track-detail" },
+    // Header
+    div(
+      { className: "page-header" },
+      createBackLink("/track", "← Back to Tracks"),
+      h1({ className: "page-title" }, `${emoji} `, view.name),
+      div({ className: "page-meta" }, ...getTrackTypeBadges(view)),
+      p(
+        { className: "text-muted", style: "margin-top: 0.5rem" },
+        view.description,
+      ),
+      div(
+        { className: "page-actions" },
+        createJobBuilderButton({ paramName: "track", paramValue: track.id }),
+        createInterviewPrepButton({ paramName: "track", paramValue: track.id }),
+      ),
+    ),
+
+    // Valid disciplines (if restricted)
+    view.validDisciplines.length > 0
+      ? createDetailSection({
+          title: "Valid Disciplines",
+          content: createLinksList(view.validDisciplines, "/discipline"),
+        })
+      : null,
+
+    // Matching weights (stat cards)
+    track.matchingWeights
+      ? createDetailSection({
+          title: "Matching Weights",
+          content: createStatsGrid([
+            createStatCard({
+              value: `${(track.matchingWeights.skills * 100).toFixed(0)}%`,
+              label: "Skills Weight",
+            }),
+            createStatCard({
+              value: `${(track.matchingWeights.behaviours * 100).toFixed(0)}%`,
+              label: "Behaviours Weight",
+            }),
+          ]),
+        })
+      : null,
+
+    // Skill and Behaviour modifiers in columns for print
+    modifiersSection,
+  );
+}

package/app/formatters/track/markdown.js

@@ -0,0 +1,105 @@
+/**
+ * Track formatting for markdown/CLI output
+ */
+
+import { tableToMarkdown } from "../shared.js";
+import { prepareTracksList, prepareTrackDetail } from "./shared.js";
+import { getConceptEmoji } from "../../model/levels.js";
+
+/**
+ * Format track list as markdown
+ * @param {Array} tracks - Raw track entities
+ * @param {Object} [framework] - Framework config for emojis
+ * @returns {string}
+ */
+export function trackListToMarkdown(tracks, framework) {
+  const { items } = prepareTracksList(tracks);
+  const emoji = framework ? getConceptEmoji(framework, "track") : "🛤️";
+  const lines = [`# ${emoji} Tracks`, ""];
+
+  for (const track of items) {
+    const types = [];
+    if (track.isProfessional) types.push("Professional");
+    if (track.isManagement) types.push("Management");
+    lines.push(`- **${track.name}**: ${types.join(", ")}`);
+  }
+  lines.push("");
+
+  return lines.join("\n");
+}
+
+/**
+ * Format track detail as markdown
+ * @param {Object} track - Raw track entity
+ * @param {Object} context - Additional context
+ * @param {Array} context.skills - All skills
+ * @param {Array} context.behaviours - All behaviours
+ * @param {Array} context.disciplines - All disciplines
+ * @param {Object} [context.framework] - Framework config for emojis
+ * @returns {string}
+ */
+export function trackToMarkdown(
+  track,
+  { skills, behaviours, disciplines, framework },
+) {
+  const view = prepareTrackDetail(track, { skills, behaviours, disciplines });
+
+  const types = [];
+  if (view.isProfessional) types.push("Professional");
+  if (view.isManagement) types.push("Management");
+
+  const emoji = framework ? getConceptEmoji(framework, "track") : "🛤️";
+  const lines = [
+    `# ${emoji} ${view.name}`,
+    "",
+    `**Type**: ${types.join(", ")}`,
+    "",
+    view.description,
+    "",
+  ];
+
+  // Skill modifiers - show expanded skills for capabilities
+  if (view.skillModifiers.length > 0) {
+    lines.push("## Skill Modifiers", "");
+    for (const m of view.skillModifiers) {
+      const modifierStr = m.modifier > 0 ? `+${m.modifier}` : `${m.modifier}`;
+      if (m.isCapability && m.skills && m.skills.length > 0) {
+        // Capability with expanded skills
+        lines.push(`### ${m.name} Capability (${modifierStr})`, "");
+        for (const skill of m.skills) {
+          lines.push(`- ${skill.name}`);
+        }
+        lines.push("");
+      } else if (m.isCapability) {
+        // Capability without expanded skills
+        lines.push(`- **All ${m.name} skills**: ${modifierStr}`);
+      } else {
+        // Individual skill
+        lines.push(`- **${m.name}**: ${modifierStr}`);
+      }
+    }
+    lines.push("");
+  }
+
+  // Behaviour modifiers
+  if (view.behaviourModifiers.length > 0) {
+    lines.push("## Behaviour Modifiers", "");
+    const modifierRows = view.behaviourModifiers.map((b) => [
+      b.name,
+      b.modifier > 0 ? `+${b.modifier}` : `${b.modifier}`,
+    ]);
+    lines.push(tableToMarkdown(["Behaviour", "Modifier"], modifierRows));
+    lines.push("");
+  }
+
+  // Valid disciplines
+  if (view.validDisciplines.length > 0) {
+    lines.push("## Valid Disciplines", "");
+    for (const d of view.validDisciplines) {
+      lines.push(`- ${d.name}`);
+    }
+    lines.push("");
+  }
+
+  return lines.join("\n");
+}

package/app/formatters/track/shared.js

@@ -0,0 +1,181 @@
+/**
+ * Track presentation helpers
+ *
+ * Shared utilities for formatting track data across DOM and markdown outputs.
+ */
+
+import { isCapability, getSkillsByCapability } from "../../model/modifiers.js";
+import { truncate } from "../shared.js";
+
+/**
+ * Sort tracks by type: professional tracks first, then management tracks.
+ * Within each type, preserves original order.
+ * @param {Array} tracks - Raw track entities
+ * @returns {Array} Sorted tracks array
+ */
+export function sortTracksByType(tracks) {
+  return [...tracks].sort((a, b) => {
+    const aFlags = getTrackTypeFlags(a);
+    const bFlags = getTrackTypeFlags(b);
+
+    // Professional tracks come first
+    if (aFlags.isProfessional && !bFlags.isProfessional) return -1;
+    if (!aFlags.isProfessional && bFlags.isProfessional) return 1;
+
+    // Preserve original order within same type
+    return 0;
+  });
+}
+
+/**
+ * Determine track type flags from track data.
+ *
+ * Logic: Only one flag needs to be explicitly set to true; the other defaults to false.
+ * - If isManagement: true → management track (isProfessional = false)
+ * - If isProfessional: true (or neither set) → professional track (isManagement = false)
+ *
+ * @param {Object} track
+ * @param {boolean} [track.isProfessional] - Whether this is a professional/IC track
+ * @param {boolean} [track.isManagement] - Whether this is a management track
+ * @returns {{isProfessional: boolean, isManagement: boolean}}
+ */
+export function getTrackTypeFlags(track) {
+  // Management takes precedence if explicitly set to true
+  const isManagement = track.isManagement === true;
+  // Professional is true if management is not true (default behavior)
+  const isProfessional = !isManagement && track.isProfessional !== false;
+  return { isProfessional, isManagement };
+}
+
+/**
+ * @typedef {Object} TrackListItem
+ * @property {string} id
+ * @property {string} name
+ * @property {string} description
+ * @property {string} truncatedDescription
+ * @property {boolean} isProfessional
+ * @property {boolean} isManagement
+ */
+
+/**
+ * Transform tracks for list view
+ * @param {Array} tracks - Raw track entities
+ * @param {number} [descriptionLimit=120] - Maximum description length
+ * @returns {{ items: TrackListItem[] }}
+ */
+export function prepareTracksList(tracks, descriptionLimit = 120) {
+  const sortedTracks = sortTracksByType(tracks);
+  const items = sortedTracks.map((track) => {
+    const { isProfessional, isManagement } = getTrackTypeFlags(track);
+    return {
+      id: track.id,
+      name: track.name,
+      description: track.description,
+      truncatedDescription: truncate(track.description, descriptionLimit),
+      isProfessional,
+      isManagement,
+    };
+  });
+
+  return { items };
+}
+
+/**
+ * @typedef {Object} SkillModifierRow
+ * @property {string} id
+ * @property {string} name
+ * @property {number} modifier
+ * @property {boolean} isCapability
+ * @property {Array<{id: string, name: string}>} [skills]
+ */
+
+/**
+ * @typedef {Object} BehaviourModifierRow
+ * @property {string} id
+ * @property {string} name
+ * @property {number} modifier
+ */
+
+/**
+ * @typedef {Object} TrackDetailView
+ * @property {string} id
+ * @property {string} name
+ * @property {string} description
+ * @property {boolean} isProfessional
+ * @property {boolean} isManagement
+ * @property {SkillModifierRow[]} skillModifiers
+ * @property {BehaviourModifierRow[]} behaviourModifiers
+ * @property {Array<{id: string, name: string}>} validDisciplines
+ */
+
+/**
+ * Transform track for detail view
+ * @param {Object} track - Raw track entity
+ * @param {Object} context - Additional context
+ * @param {Array} context.skills - All skills
+ * @param {Array} context.behaviours - All behaviours
+ * @param {Array} context.disciplines - All disciplines
+ * @returns {TrackDetailView|null}
+ */
+export function prepareTrackDetail(track, { skills, behaviours, disciplines }) {
+  if (!track) return null;
+
+  const { isProfessional, isManagement } = getTrackTypeFlags(track);
+
+  // Build skill modifiers
+  const skillModifiers = track.skillModifiers
+    ? Object.entries(track.skillModifiers).map(([key, modifier]) => {
+        if (isCapability(key)) {
+          const capabilitySkills = getSkillsByCapability(skills, key);
+          return {
+            id: key,
+            name: key.charAt(0).toUpperCase() + key.slice(1),
+            modifier,
+            isCapability: true,
+            skills: capabilitySkills.map((s) => ({ id: s.id, name: s.name })),
+          };
+        } else {
+          const skill = skills.find((s) => s.id === key);
+          return {
+            id: key,
+            name: skill?.name || key,
+            modifier,
+            isCapability: false,
+          };
+        }
+      })
+    : [];
+
+  // Build behaviour modifiers
+  const behaviourModifiers = track.behaviourModifiers
+    ? Object.entries(track.behaviourModifiers).map(
+        ([behaviourId, modifier]) => {
+          const behaviour = behaviours.find((b) => b.id === behaviourId);
+          return {
+            id: behaviourId,
+            name: behaviour?.name || behaviourId,
+            modifier,
+          };
+        },
+      )
+    : [];
+
+  // Get valid disciplines
+  const validDisciplines = track.validDisciplines
+    ? track.validDisciplines
+        .map((id) => disciplines.find((d) => d.id === id))
+        .filter(Boolean)
+        .map((d) => ({ id: d.id, name: d.specialization || d.name }))
+    : [];
+
+  return {
+    id: track.id,
+    name: track.name,
+    description: track.description,
+    isProfessional,
+    isManagement,
+    skillModifiers,
+    behaviourModifiers,
+    validDisciplines,
+  };
+}