@forwardimpact/pathway 0.1.0

package/app/lib/cli-output.js

@@ -0,0 +1,270 @@
+/**
+ * CLI Output Formatting Utilities
+ *
+ * Provides consistent formatting for terminal output including colors,
+ * tables, headers, and level formatting.
+ */
+
+// ANSI color codes
+export const colors = {
+  reset: "\x1b[0m",
+  bold: "\x1b[1m",
+  dim: "\x1b[2m",
+  italic: "\x1b[3m",
+  underline: "\x1b[4m",
+  red: "\x1b[31m",
+  green: "\x1b[32m",
+  yellow: "\x1b[33m",
+  blue: "\x1b[34m",
+  magenta: "\x1b[35m",
+  cyan: "\x1b[36m",
+  white: "\x1b[37m",
+  gray: "\x1b[90m",
+};
+
+/**
+ * Check if stdout supports colors
+ * @returns {boolean}
+ */
+export function supportsColor() {
+  if (process.env.NO_COLOR) return false;
+  if (process.env.FORCE_COLOR) return true;
+  return process.stdout.isTTY;
+}
+
+/**
+ * Wrap text with color if supported
+ * @param {string} text
+ * @param {string} color
+ * @returns {string}
+ */
+function colorize(text, color) {
+  if (!supportsColor()) return text;
+  return `${color}${text}${colors.reset}`;
+}
+
+/**
+ * Format a header
+ * @param {string} text
+ * @returns {string}
+ */
+export function formatHeader(text) {
+  return colorize(text, colors.bold + colors.cyan);
+}
+
+/**
+ * Format a subheader
+ * @param {string} text
+ * @returns {string}
+ */
+export function formatSubheader(text) {
+  return colorize(text, colors.bold);
+}
+
+/**
+ * Format a list item
+ * @param {string} label
+ * @param {string} value
+ * @param {number} [indent=0]
+ * @returns {string}
+ */
+export function formatListItem(label, value, indent = 0) {
+  const padding = "  ".repeat(indent);
+  const bullet = colorize("•", colors.dim);
+  return `${padding}${bullet} ${label}: ${value}`;
+}
+
+/**
+ * Format a bullet item (no label)
+ * @param {string} text
+ * @param {number} [indent=0]
+ * @returns {string}
+ */
+export function formatBullet(text, indent = 0) {
+  const padding = "  ".repeat(indent);
+  const bullet = colorize("•", colors.dim);
+  return `${padding}${bullet} ${text}`;
+}
+
+/**
+ * Format a table
+ * @param {string[]} headers
+ * @param {Array<Array<string|number>>} rows
+ * @param {Object} [options]
+ * @param {boolean} [options.compact=false]
+ * @returns {string}
+ */
+export function formatTable(headers, rows, options = {}) {
+  const { compact = false } = options;
+
+  // Calculate column widths
+  const widths = headers.map((h, i) =>
+    Math.max(String(h).length, ...rows.map((r) => String(r[i] || "").length)),
+  );
+
+  const lines = [];
+
+  // Header
+  const headerLine = headers
+    .map((h, i) => String(h).padEnd(widths[i]))
+    .join("  ");
+  lines.push(colorize(headerLine, colors.bold));
+
+  // Separator
+  if (!compact) {
+    lines.push(widths.map((w) => "─".repeat(w)).join("──"));
+  }
+
+  // Rows
+  for (const row of rows) {
+    lines.push(
+      row.map((cell, i) => String(cell || "").padEnd(widths[i])).join("  "),
+    );
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Format skill level with color
+ * @param {string} level
+ * @returns {string}
+ */
+export function formatSkillLevel(level) {
+  const levelColors = {
+    awareness: colors.gray,
+    foundational: colors.blue,
+    working: colors.green,
+    practitioner: colors.yellow,
+    expert: colors.magenta,
+  };
+  const color = levelColors[level] || colors.reset;
+  return colorize(level, color);
+}
+
+/**
+ * Format behaviour maturity with color
+ * @param {string} maturity
+ * @returns {string}
+ */
+export function formatBehaviourMaturity(maturity) {
+  const maturityColors = {
+    emerging: colors.gray,
+    developing: colors.blue,
+    practicing: colors.green,
+    role_modeling: colors.yellow,
+    exemplifying: colors.magenta,
+  };
+  const color = maturityColors[maturity] || colors.reset;
+  const displayName = maturity.replace(/_/g, " ");
+  return colorize(displayName, color);
+}
+
+/**
+ * Format a modifier value (+1, 0, -1)
+ * @param {number} modifier
+ * @returns {string}
+ */
+export function formatModifier(modifier) {
+  if (modifier > 0) {
+    return colorize(`+${modifier}`, colors.green);
+  } else if (modifier < 0) {
+    return colorize(String(modifier), colors.red);
+  }
+  return colorize("0", colors.dim);
+}
+
+/**
+ * Format a percentage
+ * @param {number} value - Value between 0 and 1
+ * @returns {string}
+ */
+export function formatPercent(value) {
+  const percent = Math.round(value * 100);
+  let color;
+  if (percent >= 80) {
+    color = colors.green;
+  } else if (percent >= 50) {
+    color = colors.yellow;
+  } else {
+    color = colors.red;
+  }
+  return colorize(`${percent}%`, color);
+}
+
+/**
+ * Format a change indicator (↑, ↓, →)
+ * @param {number} change
+ * @returns {string}
+ */
+export function formatChange(change) {
+  if (change > 0) {
+    return colorize(`↑${change}`, colors.green);
+  } else if (change < 0) {
+    return colorize(`↓${Math.abs(change)}`, colors.red);
+  }
+  return colorize("→", colors.dim);
+}
+
+/**
+ * Format an error message
+ * @param {string} message
+ * @returns {string}
+ */
+export function formatError(message) {
+  return colorize(`Error: ${message}`, colors.red);
+}
+
+/**
+ * Format a success message
+ * @param {string} message
+ * @returns {string}
+ */
+export function formatSuccess(message) {
+  return colorize(message, colors.green);
+}
+
+/**
+ * Format a warning message
+ * @param {string} message
+/**
+ * Format a warning message
+ * @param {string} message
+ * @returns {string}
+ */
+export function formatWarning(message) {
+  return colorize(`Warning: ${message}`, colors.yellow);
+}
+
+/**
+ * Create a horizontal rule
+ * @param {number} [width=60]
+ * @returns {string}
+ */
+export function horizontalRule(width = 60) {
+  return colorize("─".repeat(width), colors.dim);
+}
+
+/**
+ * Format a section with title and content
+ * @param {string} title
+ * @param {string} content
+ * @returns {string}
+ */
+export function formatSection(title, content) {
+  return `${formatHeader(title)}\n\n${content}`;
+}
+
+/**
+ * Indent all lines of text
+ * @param {string} text
+ * @param {number} [spaces=2]
+ * @returns {string}
+ */
+export function indent(text, spaces = 2) {
+  const padding = " ".repeat(spaces);
+  return text
+    .split("\n")
+    .map((line) => padding + line)
+    .join("\n");
+}

package/app/lib/error-boundary.js

@@ -0,0 +1,70 @@
+/**
+ * Error boundary wrapper for page rendering
+ */
+
+import { renderNotFound, renderError } from "../components/error-page.js";
+import { NotFoundError, InvalidCombinationError } from "./errors.js";
+
+/**
+ * @typedef {Object} ErrorBoundaryOptions
+ * @property {(error: Error) => void} [onError] - Error callback for logging
+ * @property {string} [backPath] - Default back path
+ * @property {string} [backText] - Default back text
+ * @property {(title: string, message: string) => void} [renderErrorFn] - Custom error renderer
+ */
+
+/**
+ * Wrap a render function with error handling
+ * @param {Function} renderFn - Page render function
+ * @param {ErrorBoundaryOptions} [options]
+ * @returns {Function}
+ */
+export function withErrorBoundary(renderFn, options = {}) {
+  const errorRenderer =
+    options.renderErrorFn ||
+    ((title, message) => {
+      renderError({
+        title,
+        message,
+        backPath: options.backPath || "/",
+        backText: options.backText || "← Back to Home",
+      });
+    });
+
+  return (...args) => {
+    try {
+      return renderFn(...args);
+    } catch (error) {
+      console.error("Page render error:", error);
+
+      options.onError?.(error);
+
+      if (error instanceof NotFoundError) {
+        if (options.renderErrorFn) {
+          errorRenderer(
+            `${error.entityType} Not Found`,
+            `No ${error.entityType.toLowerCase()} found with ID: ${error.entityId}`,
+          );
+        } else {
+          renderNotFound({
+            entityType: error.entityType,
+            entityId: error.entityId,
+            backPath: error.backPath,
+            backText: `← Back to ${error.entityType}s`,
+          });
+        }
+        return;
+      }
+
+      if (error instanceof InvalidCombinationError) {
+        errorRenderer("Invalid Combination", error.message);
+        return;
+      }
+
+      errorRenderer(
+        "Something Went Wrong",
+        error.message || "An unexpected error occurred.",
+      );
+    }
+  };
+}

package/app/lib/errors.js

@@ -0,0 +1,49 @@
+/**
+ * Custom error types for the application
+ */
+
+/**
+ * Entity not found error
+ */
+export class NotFoundError extends Error {
+  /**
+   * @param {string} entityType - Type of entity (e.g., 'Skill', 'Behaviour')
+   * @param {string} entityId - ID that was not found
+   * @param {string} backPath - Path to navigate back to
+   */
+  constructor(entityType, entityId, backPath) {
+    super(`${entityType} not found: ${entityId}`);
+    this.name = "NotFoundError";
+    this.entityType = entityType;
+    this.entityId = entityId;
+    this.backPath = backPath;
+  }
+}
+
+/**
+ * Invalid combination error (e.g., invalid job configuration)
+ */
+export class InvalidCombinationError extends Error {
+  /**
+   * @param {string} message - Error message
+   * @param {string} backPath - Path to navigate back to
+   */
+  constructor(message, backPath) {
+    super(message);
+    this.name = "InvalidCombinationError";
+    this.backPath = backPath;
+  }
+}
+
+/**
+ * Data loading error
+ */
+export class DataLoadError extends Error {
+  /**
+   * @param {string} message - Error message
+   */
+  constructor(message) {
+    super(message);
+    this.name = "DataLoadError";
+  }
+}

package/app/lib/form-controls.js

@@ -0,0 +1,47 @@
+/**
+ * Reusable form control components
+ */
+
+import { select, option } from "./render.js";
+
+/**
+ * Create a select element with initial value and change handler
+ * @param {Object} options - Configuration options
+ * @param {string} options.id - Element ID
+ * @param {Array} options.items - Array of items to display
+ * @param {string} options.initialValue - Initial selected value
+ * @param {string} options.placeholder - Placeholder text for empty option
+ * @param {Function} options.onChange - Callback when selection changes
+ * @param {Function} [options.getDisplayName] - Optional function to get display name from item
+ * @returns {HTMLElement}
+ */
+export function createSelectWithValue({
+  id,
+  items,
+  initialValue,
+  placeholder,
+  onChange,
+  getDisplayName,
+}) {
+  const displayFn = getDisplayName || ((item) => item.name);
+  const selectEl = select(
+    {
+      className: "form-select",
+      id,
+    },
+    option({ value: "" }, placeholder),
+    ...items.map((item) => {
+      const opt = option({ value: item.id }, displayFn(item));
+      if (item.id === initialValue) {
+        opt.selected = true;
+      }
+      return opt;
+    }),
+  );
+
+  selectEl.addEventListener("change", (e) => {
+    onChange(e.target.value);
+  });
+
+  return selectEl;
+}

package/app/lib/job-cache.js

@@ -0,0 +1,86 @@
+/**
+ * Job Cache
+ *
+ * Centralized caching for generated job definitions.
+ * Provides consistent key generation and get-or-create pattern.
+ */
+
+import { deriveJob } from "../model/derivation.js";
+
+/** @type {Map<string, Object>} */
+const cache = new Map();
+
+/**
+ * Create a consistent cache key from job parameters
+ * @param {string} disciplineId
+ * @param {string} trackId
+ * @param {string} gradeId
+ * @returns {string}
+ */
+export function makeJobKey(disciplineId, trackId, gradeId) {
+  return `${disciplineId}_${trackId}_${gradeId}`;
+}
+
+/**
+ * Get or create a cached job definition
+ * @param {Object} params
+ * @param {Object} params.discipline
+ * @param {Object} params.grade
+ * @param {Object} params.track
+ * @param {Array} params.skills
+ * @param {Array} params.behaviours
+ * @param {Array} [params.capabilities]
+ * @returns {Object|null}
+ */
+export function getOrCreateJob({
+  discipline,
+  grade,
+  track,
+  skills,
+  behaviours,
+  capabilities,
+}) {
+  const key = makeJobKey(discipline.id, track.id, grade.id);
+
+  if (!cache.has(key)) {
+    const job = deriveJob({
+      discipline,
+      grade,
+      track,
+      skills,
+      behaviours,
+      capabilities,
+    });
+    if (job) {
+      cache.set(key, job);
+    }
+    return job;
+  }
+
+  return cache.get(key);
+}
+
+/**
+ * Clear all cached jobs
+ */
+export function clearJobCache() {
+  cache.clear();
+}
+
+/**
+ * Invalidate a specific job from the cache
+ * @param {string} disciplineId
+ * @param {string} trackId
+ * @param {string} gradeId
+ */
+export function invalidateJob(disciplineId, trackId, gradeId) {
+  cache.delete(makeJobKey(disciplineId, trackId, gradeId));
+}
+
+/**
+ * Get the number of cached jobs (for testing/debugging)
+ * @returns {number}
+ */
+export function getCacheSize() {
+  return cache.size;
+}

package/app/lib/markdown.js

@@ -0,0 +1,114 @@
+/**
+ * Simple Markdown to HTML converter
+ *
+ * Converts common markdown syntax to HTML. Designed for job descriptions
+ * with headings, lists, bold text, and paragraphs.
+ */
+
+/**
+ * Convert markdown text to HTML
+ * @param {string} markdown - The markdown text to convert
+ * @returns {string} HTML string
+ */
+export function markdownToHtml(markdown) {
+  const lines = markdown.split("\n");
+  const htmlLines = [];
+  let inList = false;
+
+  for (let i = 0; i < lines.length; i++) {
+    let line = lines[i];
+
+    // Skip empty lines but close list if open
+    if (line.trim() === "") {
+      if (inList) {
+        htmlLines.push("</ul>");
+        inList = false;
+      }
+      continue;
+    }
+
+    // H1 heading
+    if (line.startsWith("# ")) {
+      if (inList) {
+        htmlLines.push("</ul>");
+        inList = false;
+      }
+      htmlLines.push(`<h1>${escapeHtml(line.slice(2))}</h1>`);
+      continue;
+    }
+
+    // H2 heading
+    if (line.startsWith("## ")) {
+      if (inList) {
+        htmlLines.push("</ul>");
+        inList = false;
+      }
+      htmlLines.push(`<h2>${escapeHtml(line.slice(3))}</h2>`);
+      continue;
+    }
+
+    // H3 heading
+    if (line.startsWith("### ")) {
+      if (inList) {
+        htmlLines.push("</ul>");
+        inList = false;
+      }
+      htmlLines.push(`<h3>${escapeHtml(line.slice(4))}</h3>`);
+      continue;
+    }
+
+    // List item
+    if (line.startsWith("- ")) {
+      if (!inList) {
+        htmlLines.push("<ul>");
+        inList = true;
+      }
+      const content = formatInlineMarkdown(line.slice(2));
+      htmlLines.push(`<li>${content}</li>`);
+      continue;
+    }
+
+    // Regular paragraph
+    if (inList) {
+      htmlLines.push("</ul>");
+      inList = false;
+    }
+    htmlLines.push(`<p>${formatInlineMarkdown(line)}</p>`);
+  }
+
+  // Close any open list
+  if (inList) {
+    htmlLines.push("</ul>");
+  }
+
+  return htmlLines.join("\n");
+}
+
+/**
+ * Escape HTML special characters
+ * @param {string} text - Text to escape
+ * @returns {string} Escaped text
+ */
+function escapeHtml(text) {
+  return text
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#039;");
+}
+
+/**
+ * Format inline markdown (bold text)
+ * @param {string} text - Text to format
+ * @returns {string} HTML formatted text
+ */
+function formatInlineMarkdown(text) {
+  // First escape HTML
+  let result = escapeHtml(text);
+
+  // Convert **bold** to <strong>bold</strong>
+  result = result.replace(/\*\*([^*]+)\*\*/g, "<strong>$1</strong>");
+
+  return result;
+}