@forwardimpact/pathway 0.3.0 → 0.5.0

package/app/commands/agent.js

@@ -454,7 +454,7 @@ export async function runAgentCommand({ data, args, options, dataDir }) {
   const skillFiles = derivedSkills
     .map((derived) => skillsWithAgent.find((s) => s.id === derived.skillId))
     .filter((skill) => skill?.agent)
-    .map((skill) => generateSkillMd(skill));
+    .map((skill) => generateSkillMd(skill, data.stages));
 
   // Validate all profiles
   for (const profile of profiles) {

package/app/commands/behaviour.js

@@ -57,5 +57,5 @@ export const runBehaviourCommand = createEntityCommand({
   }),
   formatSummary,
   formatDetail,
-  emoji: "🧠",
+  emojiIcon: "🧠",
 });

package/app/commands/command-factory.js

@@ -24,7 +24,7 @@ import { capitalize } from "../formatters/shared.js";
  * @param {Function} config.formatDetail - Function to format detail output: (view, framework) => void
  * @param {Function} [config.sortItems] - Optional function to sort items: (items) => sortedItems
  * @param {Function} [config.validate] - Optional validation function: (data) => {errors: [], warnings: []}
- * @param {string} [config.emoji] - Optional emoji for the entity
+ * @param {string} [config.emojiIcon] - Optional emoji for the entity
  * @returns {Function} Command handler
  */
 export function createEntityCommand({
@@ -36,7 +36,7 @@ export function createEntityCommand({
   formatDetail,
   sortItems,
   validate,
-  _emoji = "",
+  _emojiIcon = "",
 }) {
   return async function runCommand({ data, args, options }) {
     const [id] = args;

package/app/commands/discipline.js

@@ -54,5 +54,5 @@ export const runDisciplineCommand = createEntityCommand({
   }),
   formatSummary,
   formatDetail,
-  emoji: "📋",
+  emojiIcon: "📋",
 });

package/app/commands/driver.js

@@ -90,5 +90,5 @@ export const runDriverCommand = createEntityCommand({
   }),
   formatSummary,
   formatDetail,
-  emoji: "🎯",
+  emojiIcon: "🎯",
 });

package/app/commands/grade.js

@@ -56,5 +56,5 @@ export const runGradeCommand = createEntityCommand({
   presentDetail: (entity) => entity,
   formatSummary,
   formatDetail,
-  emoji: "📊",
+  emojiIcon: "📊",
 });

package/app/commands/index.js

@@ -4,13 +4,14 @@
  * Re-exports all command handlers for convenient importing.
  */
 
-export { runSkillCommand } from "./skill.js";
-export { runBehaviourCommand } from "./behaviour.js";
-export { runDriverCommand } from "./driver.js";
 export { runDisciplineCommand } from "./discipline.js";
 export { runGradeCommand } from "./grade.js";
 export { runTrackCommand } from "./track.js";
+export { runBehaviourCommand } from "./behaviour.js";
+export { runSkillCommand } from "./skill.js";
+export { runDriverCommand } from "./driver.js";
 export { runStageCommand } from "./stage.js";
+export { runToolCommand } from "./tool.js";
 export { runJobCommand } from "./job.js";
 export { runInterviewCommand } from "./interview.js";
 export { runProgressCommand } from "./progress.js";

package/app/commands/serve.js

@@ -94,7 +94,7 @@ export async function runServeCommand({ dataDir, options }) {
     framework = await loadFrameworkConfig(dataDir);
   } catch {
     // Fallback if framework config fails
-    framework = { emoji: "🚀", title: "Engineering Pathway" };
+    framework = { emojiIcon: "🚀", title: "Engineering Pathway" };
   }
 
   // Generate _index.yaml files before serving
@@ -136,7 +136,7 @@ export async function runServeCommand({ dataDir, options }) {
 
   server.listen(port, () => {
     console.log(`
-${framework.emoji} ${framework.title} running at http://localhost:${port}
+${framework.emojiIcon} ${framework.title} running at http://localhost:${port}
 📁 Data directory: ${dataDir}
 
 Press Ctrl+C to stop the server.

package/app/commands/site.js

@@ -38,6 +38,11 @@ const PUBLIC_ASSETS = [
   "formatters",
 ];
 
+/**
+ * Files and directories to copy from project root
+ */
+const ROOT_ASSETS = ["templates"];
+
 /**
  * Run the site command
  * @param {Object} params - Command parameters
@@ -53,11 +58,11 @@ export async function runSiteCommand({ dataDir, options }) {
   try {
     framework = await loadFrameworkConfig(dataDir);
   } catch {
-    framework = { emoji: "🚀", title: "Engineering Pathway" };
+    framework = { emojiIcon: "🚀", title: "Engineering Pathway" };
   }
 
   console.log(`
-${framework.emoji} Generating ${framework.title} static site...
+${framework.emojiIcon} Generating ${framework.title} static site...
 `);
 
   // Clean output directory if requested
@@ -93,6 +98,21 @@ ${framework.emoji} Generating ${framework.title} static site...
     }
   }
 
+  // Copy root assets (templates, etc.)
+  const rootDir = join(appDir, "..");
+  for (const asset of ROOT_ASSETS) {
+    const src = join(rootDir, asset);
+    const dest = join(outputDir, asset);
+
+    try {
+      await access(src);
+      await cp(src, dest, { recursive: true });
+      console.log(`   ✓ ${asset}`);
+    } catch (err) {
+      console.log(`   ⚠️  Skipped ${asset}: ${err.message}`);
+    }
+  }
+
   // Copy data directory (dereference symlinks to copy actual content)
   console.log("📁 Copying data files...");
   const dataOutputDir = join(outputDir, "data");

package/app/commands/skill.js

@@ -7,6 +7,7 @@
  *   npx pathway skill              # Summary with stats
  *   npx pathway skill --list       # IDs only (for piping)
  *   npx pathway skill <id>         # Detail view
+ *   npx pathway skill <id> --agent # Agent SKILL.md output
  *   npx pathway skill --validate   # Validation checks
  */
 
@@ -14,7 +15,10 @@ import { createEntityCommand } from "./command-factory.js";
 import { skillToMarkdown } from "../formatters/skill/markdown.js";
 import { prepareSkillsList } from "../formatters/skill/shared.js";
 import { getConceptEmoji } from "../model/levels.js";
-import { formatTable } from "../lib/cli-output.js";
+import { formatTable, formatError } from "../lib/cli-output.js";
+import { generateSkillMd } from "../model/agent.js";
+import { formatAgentSkill } from "../formatters/agent/skill.js";
+import { loadSkillTemplate } from "../lib/template-loader.js";
 
 /**
  * Format skill summary output
@@ -59,7 +63,29 @@ function formatDetail(viewAndContext, framework) {
   );
 }
 
-export const runSkillCommand = createEntityCommand({
+/**
+ * Format skill as agent SKILL.md output
+ * @param {Object} skill - Skill entity with agent section
+ * @param {Array} stages - All stage entities
+ * @param {string} dataDir - Path to data directory for template loading
+ */
+async function formatAgentDetail(skill, stages, dataDir) {
+  if (!skill.agent) {
+    console.error(formatError(`Skill '${skill.id}' has no agent section`));
+    console.error(`\nSkills with agent support:`);
+    console.error(
+      `  npx pathway skill --list | xargs -I{} sh -c 'npx pathway skill {} --json | jq -e .skill.agent > /dev/null && echo {}'`,
+    );
+    process.exit(1);
+  }
+
+  const template = await loadSkillTemplate(dataDir);
+  const skillMd = generateSkillMd(skill, stages);
+  const output = formatAgentSkill(skillMd, template);
+  console.log(output);
+}
+
+const baseSkillCommand = createEntityCommand({
   entityName: "skill",
   pluralName: "skills",
   findEntity: (data, id) => data.skills.find((s) => s.id === id),
@@ -72,5 +98,33 @@ export const runSkillCommand = createEntityCommand({
   }),
   formatSummary,
   formatDetail,
-  emoji: "📚",
+  emojiIcon: "📚",
 });
+
+/**
+ * Run skill command with --agent support
+ * @param {Object} params - Command parameters
+ * @param {Object} params.data - Loaded pathway data
+ * @param {string[]} params.args - Command arguments
+ * @param {Object} params.options - Command options
+ * @param {string} params.dataDir - Path to data directory
+ */
+export async function runSkillCommand({ data, args, options, dataDir }) {
+  // Handle --agent flag for detail view
+  if (options.agent && args.length > 0) {
+    const [id] = args;
+    const skill = data.skills.find((s) => s.id === id);
+
+    if (!skill) {
+      console.error(formatError(`Skill not found: ${id}`));
+      console.error(`Available: ${data.skills.map((s) => s.id).join(", ")}`);
+      process.exit(1);
+    }
+
+    await formatAgentDetail(skill, data.stages, dataDir);
+    return;
+  }
+
+  // Delegate to base command for all other cases
+  return baseSkillCommand({ data, args, options, dataDir });
+}

package/app/commands/stage.js

@@ -115,5 +115,5 @@ export const runStageCommand = createEntityCommand({
   }),
   formatSummary,
   formatDetail,
-  emoji: "🔄",
+  emojiIcon: "🔄",
 });

package/app/commands/tool.js

@@ -0,0 +1,112 @@
+/**
+ * Tool CLI Command
+ *
+ * Handles tool summary, listing, and detail display in the terminal.
+ *
+ * Usage:
+ *   npx pathway tool              # Summary with stats
+ *   npx pathway tool --list       # Tool names only (for piping)
+ *   npx pathway tool <name>       # Detail view for specific tool
+ */
+
+import { prepareToolsList } from "../formatters/tool/shared.js";
+import {
+  formatTable,
+  formatHeader,
+  formatSubheader,
+} from "../lib/cli-output.js";
+
+/**
+ * Run tool command
+ * @param {Object} params - Command parameters
+ * @param {Object} params.data - Loaded pathway data
+ * @param {string[]} params.args - Command arguments
+ * @param {Object} params.options - Command options
+ */
+export async function runToolCommand({ data, args, options }) {
+  const [name] = args;
+  const { tools, totalCount } = prepareToolsList(data.skills);
+
+  // --list: Output clean newline-separated tool names for piping
+  if (options.list) {
+    for (const tool of tools) {
+      console.log(tool.name);
+    }
+    return;
+  }
+
+  // No args: Show summary
+  if (!name) {
+    if (options.json) {
+      console.log(JSON.stringify(tools, null, 2));
+      return;
+    }
+    formatSummary(tools, totalCount);
+    return;
+  }
+
+  // With name: Show detail
+  const tool = tools.find((t) => t.name.toLowerCase() === name.toLowerCase());
+
+  if (!tool) {
+    console.error(`Tool not found: ${name}`);
+    console.error(`Available: ${tools.map((t) => t.name).join(", ")}`);
+    process.exit(1);
+  }
+
+  if (options.json) {
+    console.log(JSON.stringify(tool, null, 2));
+    return;
+  }
+
+  formatDetail(tool);
+}
+
+/**
+ * Format tool summary output
+ * @param {Array} tools - Aggregated tools
+ * @param {number} totalCount - Total tool count
+ */
+function formatSummary(tools, totalCount) {
+  console.log(`\n🔧 Tools\n`);
+
+  // Show tools sorted by usage count
+  const sorted = [...tools].sort((a, b) => b.usages.length - a.usages.length);
+  const rows = sorted
+    .slice(0, 15)
+    .map((t) => [
+      t.name,
+      t.usages.length,
+      t.description.length > 50
+        ? t.description.slice(0, 47) + "..."
+        : t.description,
+    ]);
+
+  console.log(formatTable(["Tool", "Skills", "Description"], rows));
+  console.log(`\nTotal: ${totalCount} tools`);
+  if (sorted.length > 15) {
+    console.log(`(showing top 15 by usage)`);
+  }
+  console.log(`\nRun 'npx pathway tool --list' for all tool names`);
+  console.log(`Run 'npx pathway tool <name>' for details\n`);
+}
+
+/**
+ * Format tool detail output
+ * @param {Object} tool - Aggregated tool with usages
+ */
+function formatDetail(tool) {
+  console.log(formatHeader(`\n🔧 ${tool.name}\n`));
+  console.log(`${tool.description}\n`);
+
+  if (tool.url) {
+    console.log(`Documentation: ${tool.url}\n`);
+  }
+
+  if (tool.usages.length > 0) {
+    console.log(formatSubheader("Used in Skills\n"));
+    const rows = tool.usages.map((u) => [u.skillName, u.useWhen]);
+    console.log(formatTable(["Skill", "Use When"], rows));
+    console.log();
+  }
+}

package/app/commands/track.js

@@ -63,5 +63,5 @@ export const runTrackCommand = createEntityCommand({
   sortItems: sortTracksByName,
   formatSummary,
   formatDetail,
-  emoji: "🛤️",
+  emojiIcon: "🛤️",
 });

package/app/components/card.js

@@ -13,6 +13,7 @@ import { div, h3, p, span } from "../lib/render.js";
  * @param {HTMLElement[]} [options.badges] - Badges to display
  * @param {HTMLElement[]} [options.meta] - Meta information
  * @param {HTMLElement} [options.content] - Additional content
+ * @param {HTMLElement} [options.icon] - Icon element to display
  * @param {string} [options.className] - Additional CSS class
  * @returns {HTMLElement}
  */
@@ -23,13 +24,22 @@ export function createCard({
   badges = [],
   meta = [],
   content,
+  icon,
   className = "",
 }) {
   const isClickable = !!href;
 
+  const titleContent = icon
+    ? div(
+        { className: "card-title-with-icon" },
+        icon,
+        h3({ className: "card-title" }, title),
+      )
+    : h3({ className: "card-title" }, title);
+
   const cardHeader = div(
     { className: "card-header" },
-    h3({ className: "card-title" }, title),
+    titleContent,
     badges.length > 0 ? div({ className: "card-badges" }, ...badges) : null,
   );
 

package/app/components/checklist.js

@@ -43,7 +43,7 @@ export function createChecklist(checklist, options = {}) {
 function createChecklistGroup(group, options) {
   const { interactive, capabilities } = options;
   const emoji = getCapabilityEmoji(capabilities, group.capability);
-  const capabilityName = formatCapabilityName(group.capability);
+  const capabilityName = formatCapabilityName(group.capability, capabilities);
 
   return div(
     { className: "checklist-group" },
@@ -90,11 +90,13 @@ function createInteractiveCheckbox() {
 
 /**
  * Format capability name for display
- * @param {string} capability - Capability ID
+ * @param {string} capabilityId - Capability ID
+ * @param {Array} capabilities - Capabilities array
  * @returns {string}
  */
-function formatCapabilityName(capability) {
-  return capability.replace(/_/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+function formatCapabilityName(capabilityId, capabilities) {
+  const capability = capabilities.find((c) => c.id === capabilityId);
+  return capability?.name || capabilityId;
 }
 
 /**

package/app/components/code-display.js

@@ -0,0 +1,153 @@
+/**
+ * Code Display Component
+ *
+ * Reusable read-only code block with copy buttons and syntax highlighting.
+ * Used for markdown content, agent profiles, skills, and code snippets.
+ */
+
+/* global Prism */
+import { div, p, span, button } from "../lib/render.js";
+
+const COPY_LABEL = "📋 Copy";
+const COPY_HTML_LABEL = "Copy as HTML";
+
+/**
+ * Create a copy button that copies content to clipboard
+ * @param {string} content - The text content to copy
+ * @returns {HTMLElement}
+ */
+export function createCopyButton(content) {
+  const btn = button(
+    {
+      className: "btn btn-sm copy-btn",
+      onClick: async () => {
+        try {
+          await navigator.clipboard.writeText(content);
+          btn.textContent = "✓ Copied!";
+          btn.classList.add("copied");
+          setTimeout(() => {
+            btn.textContent = COPY_LABEL;
+            btn.classList.remove("copied");
+          }, 2000);
+        } catch (err) {
+          console.error("Failed to copy:", err);
+          btn.textContent = "Copy failed";
+          setTimeout(() => {
+            btn.textContent = COPY_LABEL;
+          }, 2000);
+        }
+      },
+    },
+    COPY_LABEL,
+  );
+  return btn;
+}
+
+/**
+ * Create a copy button that copies HTML to clipboard (for rich text pasting)
+ * @param {string} html - The HTML content to copy
+ * @returns {HTMLElement}
+ */
+function createCopyHtmlButton(html) {
+  const btn = button(
+    {
+      className: "btn btn-sm btn-secondary copy-btn",
+      onClick: async () => {
+        try {
+          const blob = new Blob([html], { type: "text/html" });
+          const clipboardItem = new ClipboardItem({ "text/html": blob });
+          await navigator.clipboard.write([clipboardItem]);
+          btn.textContent = "✓ Copied!";
+          btn.classList.add("copied");
+          setTimeout(() => {
+            btn.textContent = COPY_HTML_LABEL;
+            btn.classList.remove("copied");
+          }, 2000);
+        } catch (err) {
+          console.error("Failed to copy:", err);
+          btn.textContent = "Copy failed";
+          setTimeout(() => {
+            btn.textContent = COPY_HTML_LABEL;
+          }, 2000);
+        }
+      },
+    },
+    COPY_HTML_LABEL,
+  );
+  return btn;
+}
+
+/**
+ * Create a code display component with syntax highlighting and copy button
+ * @param {Object} options
+ * @param {string} options.content - The code content to display
+ * @param {string} [options.language="markdown"] - Language for syntax highlighting
+ * @param {string} [options.filename] - Optional filename to display in header
+ * @param {string} [options.description] - Optional description text
+ * @param {Function} [options.toHtml] - Function to convert content to HTML (enables "Copy as HTML" button)
+ * @param {number} [options.minHeight] - Optional minimum height in pixels
+ * @param {number} [options.maxHeight] - Optional maximum height in pixels
+ * @returns {HTMLElement}
+ */
+export function createCodeDisplay({
+  content,
+  language = "markdown",
+  filename,
+  description,
+  toHtml,
+  minHeight,
+  maxHeight,
+}) {
+  // Create highlighted code block
+  const pre = document.createElement("pre");
+  pre.className = "code-display";
+  if (minHeight) pre.style.minHeight = `${minHeight}px`;
+  if (maxHeight) {
+    pre.style.maxHeight = `${maxHeight}px`;
+    pre.style.overflowY = "auto";
+  }
+
+  const code = document.createElement("code");
+  if (language) {
+    code.className = `language-${language}`;
+  }
+  code.textContent = content;
+  pre.appendChild(code);
+
+  // Apply Prism highlighting if available and language specified
+  if (language && typeof Prism !== "undefined") {
+    Prism.highlightElement(code);
+  }
+
+  // Build header content
+  const headerLeft = [];
+  if (filename) {
+    headerLeft.push(span({ className: "code-display-filename" }, filename));
+  }
+  if (description) {
+    headerLeft.push(p({ className: "text-muted" }, description));
+  }
+
+  // Build buttons
+  const buttons = [createCopyButton(content)];
+  if (toHtml) {
+    buttons.push(createCopyHtmlButton(toHtml(content)));
+  }
+
+  // Only show header if there's content for it
+  const hasHeader = headerLeft.length > 0 || buttons.length > 0;
+
+  return div(
+    { className: "code-display-container" },
+    hasHeader
+      ? div(
+          { className: "code-display-header" },
+          headerLeft.length > 0
+            ? div({ className: "code-display-info" }, ...headerLeft)
+            : null,
+          div({ className: "button-group" }, ...buttons),
+        )
+      : null,
+    pre,
+  );
+}