@forwardimpact/pathway 0.1.0

package/app/formatters/shared.js

@@ -0,0 +1,71 @@
+/**
+ * Shared formatting utilities
+ *
+ * Common formatting functions used across different output formats (CLI, DOM, markdown)
+ */
+
+/**
+ * Format level as text with dots (for CLI/markdown)
+ * @param {number} level - 1-5
+ * @param {string} name - Level name
+ * @returns {string}
+ */
+export function formatLevelText(level, name) {
+  return `${"●".repeat(level)}${"○".repeat(5 - level)} ${name}`;
+}
+
+/**
+ * Format table as markdown
+ * @param {string[]} headers - Column headers
+ * @param {string[][]} rows - Table rows
+ * @returns {string}
+ */
+export function tableToMarkdown(headers, rows) {
+  const headerRow = `| ${headers.join(" | ")} |`;
+  const separator = `| ${headers.map(() => "---").join(" | ")} |`;
+  const dataRows = rows.map((row) => `| ${row.join(" | ")} |`);
+  return [headerRow, separator, ...dataRows].join("\n");
+}
+
+/**
+ * Format a key-value object as markdown list
+ * @param {Object<string, string>} obj - Key-value pairs
+ * @param {number} indent - Indent level
+ * @returns {string}
+ */
+export function objectToMarkdownList(obj, indent = 0) {
+  const prefix = "  ".repeat(indent);
+  return Object.entries(obj)
+    .map(([key, value]) => `${prefix}- **${key}**: ${value}`)
+    .join("\n");
+}
+
+/**
+ * Format percentage for display
+ * @param {number} value - Decimal value (0-1)
+ * @returns {string}
+ */
+export function formatPercent(value) {
+  return `${Math.round(value * 100)}%`;
+}
+
+/**
+ * Capitalize first letter of each word
+ * @param {string} str
+ * @returns {string}
+ */
+export function capitalize(str) {
+  if (!str) return "";
+  return str.replace(/_/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+}
+
+/**
+ * Truncate text to max length (reserves space for ellipsis)
+ * @param {string} text
+ * @param {number} maxLength - Total length including ellipsis
+ * @returns {string}
+ */
+export function truncate(text, maxLength = 100) {
+  if (!text || text.length <= maxLength) return text || "";
+  return text.slice(0, maxLength - 3) + "...";
+}

package/app/formatters/skill/dom.js

@@ -0,0 +1,168 @@
+/**
+ * Skill formatting for DOM output
+ */
+
+import {
+  div,
+  heading1,
+  heading2,
+  p,
+  span,
+  a,
+  table,
+  tbody,
+  thead,
+  tr,
+  th,
+  td,
+} from "../../lib/render.js";
+import { createBackLink } from "../../components/nav.js";
+import { createLevelCell } from "../../components/detail.js";
+import { SKILL_LEVEL_ORDER } from "../../model/levels.js";
+import { prepareSkillDetail, formatCapability } from "./shared.js";
+
+/**
+ * Format skill detail as DOM elements
+ * @param {Object} skill - Raw skill entity
+ * @param {Object} context - Additional context and options
+ * @param {Array} context.disciplines - All disciplines
+ * @param {Array} context.tracks - All tracks
+ * @param {Array} context.drivers - All drivers
+ * @param {Array} context.capabilities - Capability entities
+ * @param {boolean} [context.showBackLink=true] - Whether to show back navigation link
+ * @returns {HTMLElement}
+ */
+export function skillToDOM(
+  skill,
+  { disciplines, tracks, drivers, capabilities, showBackLink = true } = {},
+) {
+  const view = prepareSkillDetail(skill, {
+    disciplines,
+    tracks,
+    drivers,
+    capabilities,
+  });
+  return div(
+    { className: "detail-page skill-detail" },
+    // Header
+    div(
+      { className: "page-header" },
+      showBackLink ? createBackLink("/skill", "← Back to Skills") : null,
+      heading1(
+        { className: "page-title" },
+        view.capabilityEmoji,
+        " ",
+        view.name,
+      ),
+      div(
+        { className: "page-meta" },
+        span(
+          { className: "badge badge-default" },
+          formatCapability(view.capability),
+        ),
+        view.isHumanOnly
+          ? span(
+              {
+                className: "badge badge-human-only",
+                title: "Requires interpersonal skills; excluded from agents",
+              },
+              "🤲 Human-Only",
+            )
+          : null,
+      ),
+      p({ className: "page-description" }, view.description),
+    ),
+
+    // Level descriptions
+    div(
+      { className: "detail-section" },
+      heading2({ className: "section-title" }, "Level Descriptions"),
+      table(
+        { className: "level-table" },
+        thead({}, tr({}, th({}, "Level"), th({}, "Description"))),
+        tbody(
+          {},
+          ...SKILL_LEVEL_ORDER.map((level, index) => {
+            const description = view.levelDescriptions[level] || "—";
+            return tr(
+              {},
+              createLevelCell(index + 1, SKILL_LEVEL_ORDER.length, level),
+              td({}, description),
+            );
+          }),
+        ),
+      ),
+    ),
+
+    // Used in Disciplines and Linked to Drivers in two columns
+    view.relatedDisciplines.length > 0 || view.relatedDrivers.length > 0
+      ? div(
+          { className: "detail-section" },
+          div(
+            { className: "content-columns" },
+            // Used in Disciplines column
+            view.relatedDisciplines.length > 0
+              ? div(
+                  { className: "column" },
+                  heading2(
+                    { className: "section-title" },
+                    "Used in Disciplines",
+                  ),
+                  ...view.relatedDisciplines.map((d) =>
+                    div(
+                      { className: "list-item" },
+                      showBackLink
+                        ? a({ href: `#/discipline/${d.id}` }, d.name)
+                        : span({}, d.name),
+                      " ",
+                      span(
+                        { className: `badge badge-${d.skillType}` },
+                        d.skillType,
+                      ),
+                    ),
+                  ),
+                )
+              : null,
+            // Linked to Drivers column
+            view.relatedDrivers.length > 0
+              ? div(
+                  { className: "column" },
+                  heading2({ className: "section-title" }, "Linked to Drivers"),
+                  ...view.relatedDrivers.map((d) =>
+                    div(
+                      { className: "list-item" },
+                      showBackLink
+                        ? a({ href: `#/driver/${d.id}` }, d.name)
+                        : span({}, d.name),
+                    ),
+                  ),
+                )
+              : null,
+          ),
+        )
+      : null,
+
+    // Related tracks
+    view.relatedTracks.length > 0
+      ? div(
+          { className: "detail-section" },
+          heading2({ className: "section-title" }, "Modified by Tracks"),
+          ...view.relatedTracks.map((t) =>
+            div(
+              { className: "list-item" },
+              showBackLink
+                ? a({ href: `#/track/${t.id}` }, t.name)
+                : span({}, t.name),
+              " ",
+              span(
+                {
+                  className: `modifier ${t.modifier > 0 ? "modifier-positive" : t.modifier < 0 ? "modifier-negative" : "modifier-neutral"}`,
+                },
+                t.modifier > 0 ? `+${t.modifier}` : String(t.modifier),
+              ),
+            ),
+          ),
+        )
+      : null,
+  );
+}

package/app/formatters/skill/markdown.js

@@ -0,0 +1,109 @@
+/**
+ * Skill formatting for markdown/CLI output
+ */
+
+import { tableToMarkdown, capitalize } from "../shared.js";
+import { prepareSkillsList, prepareSkillDetail } from "./shared.js";
+import { getConceptEmoji } from "../../model/levels.js";
+
+/**
+ * Format skill list as markdown
+ * @param {Array} skills - Raw skill entities
+ * @param {Array} capabilities - Capability entities
+ * @param {Object} [framework] - Framework config for emojis
+ * @returns {string}
+ */
+export function skillListToMarkdown(skills, capabilities, framework) {
+  const { groups, groupOrder } = prepareSkillsList(skills, capabilities);
+  const emoji = framework ? getConceptEmoji(framework, "skill") : "📚";
+  const lines = [`# ${emoji} Skills`, ""];
+
+  for (const capability of groupOrder) {
+    const capabilitySkills = groups[capability];
+    lines.push(`## ${capitalize(capability)}`, "");
+
+    for (const skill of capabilitySkills) {
+      lines.push(`- **${skill.name}**: ${skill.truncatedDescription}`);
+    }
+    lines.push("");
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Format skill detail as markdown
+ * @param {Object} skill - Raw skill entity
+ * @param {Object} context - Additional context
+ * @param {Array} context.disciplines - All disciplines
+ * @param {Array} context.tracks - All tracks
+ * @param {Array} context.drivers - All drivers
+ * @param {Array} context.capabilities - Capability entities
+ * @param {Object} [context.framework] - Framework config for emojis
+ * @returns {string}
+ */
+export function skillToMarkdown(
+  skill,
+  { disciplines, tracks, drivers, capabilities, framework },
+) {
+  const view = prepareSkillDetail(skill, {
+    disciplines,
+    tracks,
+    drivers,
+    capabilities,
+  });
+  const emoji = framework ? getConceptEmoji(framework, "skill") : "🎯";
+  const lines = [
+    `# ${emoji} ${view.name}`,
+    "",
+    `${view.capabilityEmoji} ${capitalize(view.capability)}`,
+  ];
+
+  // Add human-only badge if applicable
+  if (view.isHumanOnly) {
+    lines.push(
+      "",
+      "🤲 **Human-Only** — Requires interpersonal skills; excluded from agents",
+    );
+  }
+
+  lines.push("", view.description, "");
+
+  // Level descriptions table
+  lines.push("## Level Descriptions", "");
+  const levelRows = Object.entries(view.levelDescriptions).map(
+    ([level, desc]) => [capitalize(level), desc],
+  );
+  lines.push(tableToMarkdown(["Level", "Description"], levelRows));
+  lines.push("");
+
+  // Related disciplines
+  if (view.relatedDisciplines.length > 0) {
+    lines.push("## Used in Disciplines", "");
+    for (const d of view.relatedDisciplines) {
+      lines.push(`- **${d.name}**: as ${d.skillType}`);
+    }
+    lines.push("");
+  }
+
+  // Related tracks with modifiers
+  if (view.relatedTracks.length > 0) {
+    lines.push("## Modified by Tracks", "");
+    for (const t of view.relatedTracks) {
+      const modifierStr = t.modifier > 0 ? `+${t.modifier}` : `${t.modifier}`;
+      lines.push(`- **${t.name}**: ${modifierStr}`);
+    }
+    lines.push("");
+  }
+
+  // Related drivers
+  if (view.relatedDrivers.length > 0) {
+    lines.push("## Linked to Drivers", "");
+    for (const d of view.relatedDrivers) {
+      lines.push(`- ${d.name}`);
+    }
+    lines.push("");
+  }
+
+  return lines.join("\n");
+}

package/app/formatters/skill/shared.js

@@ -0,0 +1,125 @@
+/**
+ * Skill presentation helpers
+ *
+ * Shared utilities for formatting skill data across DOM and markdown outputs.
+ */
+
+import {
+  groupSkillsByCapability,
+  getCapabilityEmoji,
+} from "../../model/levels.js";
+import { getSkillTypeForDiscipline } from "../../model/derivation.js";
+import { truncate } from "../shared.js";
+
+/**
+ * Format capability name for display
+ * @param {string} capability
+ * @returns {string}
+ */
+export function formatCapability(capability) {
+  if (!capability) return "";
+  return capability.charAt(0).toUpperCase() + capability.slice(1);
+}
+
+/**
+ * @typedef {Object} SkillListItem
+ * @property {string} id
+ * @property {string} name
+ * @property {string} description
+ * @property {string} capability
+ * @property {string} capabilityEmoji
+ * @property {string} truncatedDescription
+ */
+
+/**
+ * Transform skills for list view (grouped by capability)
+ * @param {Array} skills - Raw skill entities
+ * @param {Array} capabilities - Capability entities
+ * @param {number} [descriptionLimit=120] - Maximum description length
+ * @returns {{ groups: Object<string, SkillListItem[]>, groupOrder: string[] }}
+ */
+export function prepareSkillsList(
+  skills,
+  capabilities,
+  descriptionLimit = 120,
+) {
+  const grouped = groupSkillsByCapability(skills);
+
+  const groups = {};
+  for (const [capability, capabilitySkills] of Object.entries(grouped)) {
+    groups[capability] = capabilitySkills.map((skill) => ({
+      id: skill.id,
+      name: skill.name,
+      description: skill.description,
+      capability: skill.capability,
+      capabilityEmoji: getCapabilityEmoji(capabilities, skill.capability),
+      truncatedDescription: truncate(skill.description, descriptionLimit),
+    }));
+  }
+
+  return { groups, groupOrder: Object.keys(groups) };
+}
+
+/**
+ * @typedef {Object} SkillDetailView
+ * @property {string} id
+ * @property {string} name
+ * @property {string} description
+ * @property {string} capability
+ * @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
+ */
+
+/**
+ * Transform skill for detail view
+ * @param {Object} skill - Raw skill entity
+ * @param {Object} context - Additional context
+ * @param {Array} context.disciplines - All disciplines
+ * @param {Array} context.tracks - All tracks
+ * @param {Array} context.drivers - All drivers
+ * @param {Array} context.capabilities - Capability entities
+ * @returns {SkillDetailView|null}
+ */
+export function prepareSkillDetail(
+  skill,
+  { disciplines, tracks, drivers, capabilities },
+) {
+  if (!skill) return null;
+
+  const relatedDisciplines = disciplines
+    .filter((d) => getSkillTypeForDiscipline(d, skill.id) !== null)
+    .map((d) => ({
+      id: d.id,
+      name: d.specialization || d.name,
+      skillType: getSkillTypeForDiscipline(d, skill.id),
+    }));
+
+  const relatedTracks = tracks
+    .filter((t) => t.skillModifiers?.[skill.id])
+    .map((t) => ({
+      id: t.id,
+      name: t.name,
+      modifier: t.skillModifiers[skill.id],
+    }));
+
+  const relatedDrivers = drivers
+    .filter((d) => d.contributingSkills?.includes(skill.id))
+    .map((d) => ({ id: d.id, name: d.name }));
+
+  return {
+    id: skill.id,
+    name: skill.name,
+    description: skill.description,
+    capability: skill.capability,
+    isHumanOnly: skill.isHumanOnly || false,
+    capabilityEmoji: getCapabilityEmoji(capabilities, skill.capability),
+    levelDescriptions: skill.levelDescriptions,
+    relatedDisciplines,
+    relatedTracks,
+    relatedDrivers,
+  };
+}

package/app/formatters/stage/dom.js

@@ -0,0 +1,135 @@
+/**
+ * Stage formatting for DOM output
+ */
+
+import { div, h2, p, a, span, ul, li } from "../../lib/render.js";
+import { createBackLink } from "../../components/nav.js";
+import { prepareStageDetail, getStageEmoji } from "./shared.js";
+
+/**
+ * Format stage detail as DOM elements
+ * @param {Object} stage - Raw stage entity
+ * @param {Object} context - Additional context
+ * @param {Array} [context.stages] - All stages (for handoff links)
+ * @param {boolean} [context.showBackLink=true] - Whether to show back navigation link
+ * @returns {HTMLElement}
+ */
+export function stageToDOM(stage, { stages = [], showBackLink = true } = {}) {
+  const view = prepareStageDetail(stage);
+  const emoji = getStageEmoji(stages, stage.id);
+
+  return div(
+    { className: "detail-page stage-detail" },
+    // Header
+    div(
+      { className: "page-header" },
+      showBackLink ? createBackLink("/stage", "← Back to Stages") : null,
+      div(
+        { className: "page-title-row" },
+        span({ className: "page-title" }, `${emoji} ${view.name}`),
+        span({ className: `badge ${view.modeClassName}` }, view.modeBadge),
+      ),
+      p({ className: "page-description" }, view.description),
+    ),
+
+    // Tools section
+    view.tools.length > 0
+      ? div(
+          { className: "section section-detail" },
+          h2({ className: "section-title" }, "Available Tools"),
+          div(
+            { className: "tool-badges" },
+            ...view.tools.map((tool) =>
+              span(
+                { className: "badge badge-tool", title: tool.label },
+                `${tool.icon} ${tool.label}`,
+              ),
+            ),
+          ),
+        )
+      : null,
+
+    // Entry/Exit Criteria
+    view.entryCriteria.length > 0 || view.exitCriteria.length > 0
+      ? div(
+          { className: "section section-detail" },
+          div(
+            { className: "content-columns" },
+            // Entry criteria column
+            view.entryCriteria.length > 0
+              ? div(
+                  { className: "column" },
+                  h2({ className: "section-title" }, "Entry Criteria"),
+                  ul(
+                    { className: "criteria-list" },
+                    ...view.entryCriteria.map((item) =>
+                      li({ className: "criteria-item" }, item),
+                    ),
+                  ),
+                )
+              : null,
+            // Exit criteria column
+            view.exitCriteria.length > 0
+              ? div(
+                  { className: "column" },
+                  h2({ className: "section-title" }, "Exit Criteria"),
+                  ul(
+                    { className: "criteria-list" },
+                    ...view.exitCriteria.map((item) =>
+                      li({ className: "criteria-item" }, item),
+                    ),
+                  ),
+                )
+              : null,
+          ),
+        )
+      : null,
+
+    // Constraints
+    view.constraints.length > 0
+      ? div(
+          { className: "section section-detail" },
+          h2({ className: "section-title" }, "Constraints"),
+          ul(
+            { className: "constraint-list" },
+            ...view.constraints.map((item) =>
+              li({ className: "constraint-item" }, `⚠️ ${item}`),
+            ),
+          ),
+        )
+      : null,
+
+    // Handoffs
+    view.handoffs.length > 0
+      ? div(
+          { className: "section section-detail" },
+          h2({ className: "section-title" }, "Handoffs"),
+          div(
+            { className: "handoff-list" },
+            ...view.handoffs.map((handoff) => {
+              const targetStage = stages.find((s) => s.id === handoff.target);
+              const targetEmoji = getStageEmoji(stages, handoff.target);
+              return div(
+                { className: "handoff-card" },
+                div(
+                  { className: "handoff-header" },
+                  showBackLink && targetStage
+                    ? a(
+                        { href: `#/stage/${handoff.target}` },
+                        `${targetEmoji} ${handoff.label}`,
+                      )
+                    : span({}, `${targetEmoji} ${handoff.label}`),
+                ),
+                handoff.prompt
+                  ? p(
+                      { className: "handoff-prompt text-muted" },
+                      handoff.prompt,
+                    )
+                  : null,
+              );
+            }),
+          ),
+        )
+      : null,
+  );
+}

package/app/formatters/stage/index.js

@@ -0,0 +1,12 @@
+/**
+ * Stage formatters index
+ *
+ * Re-exports all stage formatting functions.
+ */
+
+export {
+  prepareStagesList,
+  prepareStageDetail,
+  getStageEmoji,
+} from "./shared.js";
+export { stageToDOM } from "./dom.js";