@forwardimpact/pathway 0.1.0

package/app/formatters/agent/dom.js

@@ -0,0 +1,540 @@
+/**
+ * Agent DOM Formatter
+ *
+ * Formats agent deployment data into DOM elements for browser display.
+ * Includes copy and download functionality.
+ */
+
+import {
+  div,
+  h2,
+  h3,
+  p,
+  span,
+  button,
+  section,
+  details,
+  summary,
+} from "../../lib/render.js";
+import { formatAgentProfile } from "./profile.js";
+import { formatAgentSkill } from "./skill.js";
+import { getStageEmoji } from "../stage/shared.js";
+
+/**
+ * Convert agent deployment to DOM elements
+ * @param {Object} deployment - Generated deployment
+ * @param {Object} deployment.profile - Agent profile
+ * @param {Array} deployment.skills - Agent skills
+ * @param {Array} [deployment.roleAgents] - Role variant agents (plan, review)
+ * @param {Object} [deployment.vscodeSettings] - VS Code settings to include in download
+ * @returns {HTMLElement}
+ */
+export function agentDeploymentToDOM({
+  profile,
+  skills,
+  roleAgents = [],
+  vscodeSettings = {},
+}) {
+  const profileContent = formatAgentProfile(profile);
+  const agentName = profile.frontmatter.name;
+
+  return div(
+    { className: "agent-deployment" },
+
+    // Download all button
+    createDownloadButton(
+      profile,
+      skills,
+      roleAgents,
+      vscodeSettings,
+      agentName,
+    ),
+
+    // Profile section
+    section(
+      { className: "agent-section" },
+      div(
+        { className: "section-header" },
+        h2({}, "Agent Profile"),
+        createCopyButton(profileContent),
+      ),
+      p({ className: "filename" }, profile.filename),
+      createCodeBlock(profileContent),
+    ),
+
+    // Role Agents section
+    roleAgents.length > 0
+      ? section(
+          { className: "agent-section" },
+          h2({}, `Role Variants (${roleAgents.length})`),
+          p(
+            { className: "text-muted" },
+            "Specialized agents for specific workflow phases. These can be used as subagents or standalone.",
+          ),
+          div(
+            { className: "role-agents-list" },
+            ...roleAgents.map((agent) => createRoleAgentCard(agent)),
+          ),
+        )
+      : null,
+
+    // Skills section
+    section(
+      { className: "agent-section" },
+      h2({}, `Skills (${skills.length})`),
+      skills.length > 0
+        ? div(
+            { className: "skills-list" },
+            ...skills.map((skill) => createSkillCard(skill)),
+          )
+        : p(
+            { className: "text-muted" },
+            "No skills with agent sections found for this discipline.",
+          ),
+    ),
+
+    // CLI hint section
+    section(
+      { className: "agent-section cli-hint" },
+      h2({}, "CLI Alternative"),
+      p({}, "Generate this agent from the command line:"),
+      createCliCommand(agentName),
+    ),
+  );
+}
+
+/**
+ * Create download all button
+ * @param {Object} profile - Agent profile
+ * @param {Array} skills - Agent skills
+ * @param {Array} roleAgents - Role variant agents
+ * @param {Object} vscodeSettings - VS Code settings to include
+ * @param {string} agentName - Agent name for zip filename
+ * @returns {HTMLElement}
+ */
+function createDownloadButton(
+  profile,
+  skills,
+  roleAgents,
+  vscodeSettings,
+  agentName,
+) {
+  const btn = button(
+    { className: "btn btn-primary download-all-btn" },
+    "📦 Download All (.zip)",
+  );
+
+  btn.addEventListener("click", async () => {
+    btn.disabled = true;
+    btn.textContent = "Generating...";
+
+    try {
+      await downloadAllAsZip(
+        profile,
+        skills,
+        roleAgents,
+        vscodeSettings,
+        agentName,
+      );
+    } finally {
+      btn.disabled = false;
+      btn.textContent = "📦 Download All (.zip)";
+    }
+  });
+
+  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
+ * @returns {HTMLElement}
+ */
+function createSkillCard(skill) {
+  const content = formatAgentSkill(skill);
+  const filename = `${skill.dirname}/SKILL.md`;
+
+  return div(
+    { className: "skill-card" },
+    div(
+      { className: "skill-header" },
+      span({ className: "skill-filename" }, filename),
+      createCopyButton(content),
+    ),
+    createCodeBlock(content),
+  );
+}
+
+/**
+ * Create a role agent card with collapsible content
+ * @param {Object} agent - Role agent with frontmatter, body, filename
+ * @returns {HTMLElement}
+ */
+function createRoleAgentCard(agent) {
+  const content = formatAgentProfile(agent);
+  const roleName = agent.frontmatter.name.split("-").pop(); // Extract role suffix (plan, review)
+
+  return details(
+    { className: "role-agent-card" },
+    summary(
+      {},
+      div(
+        { className: "role-agent-header" },
+        span(
+          { className: "role-name" },
+          `${roleName.charAt(0).toUpperCase() + roleName.slice(1)} Agent`,
+        ),
+        span({ className: "role-filename" }, agent.filename),
+      ),
+    ),
+    div(
+      { className: "role-agent-content" },
+      p(
+        { className: "text-muted role-description" },
+        agent.frontmatter.description,
+      ),
+      div({ className: "role-agent-actions" }, createCopyButton(content)),
+      createCodeBlock(content),
+    ),
+  );
+}
+
+/**
+ * Create CLI command display
+ * @param {string} agentName - Agent name (kebab-case)
+ * @returns {HTMLElement}
+ */
+function createCliCommand(agentName) {
+  // Convert kebab-case name to discipline and track
+  const parts = agentName.split("-");
+  const track = parts.pop();
+  const discipline = parts.join("_");
+
+  const command = `npx pathway agent ${discipline} ${track} --output=.github --all-roles`;
+
+  const container = div(
+    { className: "cli-command" },
+    createCodeBlock(command),
+    createCopyButton(command),
+  );
+
+  return container;
+}
+
+/**
+ * Download all agent files as a ZIP
+ * @param {Object} profile - Agent profile
+ * @param {Array} skills - Agent skills
+ * @param {Array} roleAgents - Role variant agents
+ * @param {Object} vscodeSettings - VS Code settings to include
+ * @param {string} agentName - Agent name for zip filename
+ */
+async function downloadAllAsZip(
+  profile,
+  skills,
+  roleAgents,
+  vscodeSettings,
+  agentName,
+) {
+  // Dynamically import JSZip
+  const JSZip = await importJSZip();
+  const zip = new JSZip();
+
+  // Add main profile to .github/agents/ folder
+  const profileContent = formatAgentProfile(profile);
+  zip.file(`.github/agents/${profile.filename}`, profileContent);
+
+  // Add role agent profiles to .github/agents/ folder
+  for (const roleAgent of roleAgents) {
+    const roleContent = formatAgentProfile(roleAgent);
+    zip.file(`.github/agents/${roleAgent.filename}`, roleContent);
+  }
+
+  // Add skills to .claude/skills/ folder
+  for (const skill of skills) {
+    const skillContent = formatAgentSkill(skill);
+    zip.file(`.claude/skills/${skill.dirname}/SKILL.md`, skillContent);
+  }
+
+  // Add VS Code settings for multi-agent features
+  if (Object.keys(vscodeSettings).length > 0) {
+    zip.file(
+      ".vscode/settings.json",
+      JSON.stringify(vscodeSettings, null, 2) + "\n",
+    );
+  }
+
+  // Generate and download
+  const blob = await zip.generateAsync({ type: "blob" });
+  const url = URL.createObjectURL(blob);
+
+  const link = document.createElement("a");
+  link.href = url;
+  link.download = `${agentName}-agent.zip`;
+  document.body.appendChild(link);
+  link.click();
+  document.body.removeChild(link);
+
+  URL.revokeObjectURL(url);
+}
+
+/**
+ * Dynamically import JSZip from CDN
+ * @returns {Promise<typeof JSZip>}
+ */
+async function importJSZip() {
+  // Use dynamic import from CDN
+  const module = await import("https://cdn.jsdelivr.net/npm/jszip@3.10.1/+esm");
+  return module.default;
+}
+
+/**
+ * Format a stage-specific agent preview
+ * @param {Object} stageAgent - Derived stage agent data
+ * @param {Object} profile - Generated profile with frontmatter and body
+ * @param {Object} options - Options
+ * @param {Array} [options.stages] - All stages for emoji lookup
+ * @param {Object} [options.vscodeSettings] - VS Code settings for download
+ * @returns {HTMLElement}
+ */
+export function stageAgentToDOM(stageAgent, profile, options = {}) {
+  const { vscodeSettings = {}, stages = [] } = options;
+  const { stage, tools, handoffs, constraints, checklist, derivedSkills } =
+    stageAgent;
+  const stageEmoji = getStageEmoji(stages, stage.id);
+  const profileContent = formatAgentProfile(profile);
+
+  return div(
+    { className: "agent-deployment stage-agent-preview" },
+
+    // Stage info header
+    section(
+      { className: "agent-section stage-info" },
+      div(
+        { className: "stage-header" },
+        span({ className: "stage-emoji" }, stageEmoji),
+        h2({}, `${stage.name} Agent`),
+      ),
+      p({ className: "text-muted" }, stage.description),
+    ),
+
+    // Tools section
+    tools.length > 0
+      ? section(
+          { className: "agent-section" },
+          h3({}, "Tools"),
+          div(
+            { className: "tool-badges" },
+            ...tools.map((tool) =>
+              span({ className: "badge badge-tool" }, tool),
+            ),
+          ),
+        )
+      : null,
+
+    // Constraints section
+    constraints.length > 0
+      ? section(
+          { className: "agent-section" },
+          h3({}, "Constraints"),
+          div(
+            { className: "constraint-list" },
+            ...constraints.map((c) =>
+              div({ className: "constraint-item" }, `⚠️ ${c}`),
+            ),
+          ),
+        )
+      : null,
+
+    // Handoffs section
+    handoffs.length > 0
+      ? section(
+          { className: "agent-section" },
+          h3({}, "Handoffs"),
+          div(
+            { className: "handoff-buttons" },
+            ...handoffs.map((h) => {
+              const targetEmoji = getStageEmoji(stages, h.target);
+              return div(
+                { className: "handoff-button-preview" },
+                span({ className: "handoff-icon" }, targetEmoji),
+                span({ className: "handoff-label" }, h.label),
+              );
+            }),
+          ),
+        )
+      : null,
+
+    // Checklist section
+    checklist.length > 0
+      ? section(
+          { className: "agent-section" },
+          h3({}, "Handoff Checklist"),
+          p(
+            { className: "text-muted" },
+            "Items to verify before transitioning to the next stage.",
+          ),
+          createChecklistPreview(checklist),
+        )
+      : null,
+
+    // Skills summary
+    derivedSkills.length > 0
+      ? section(
+          { className: "agent-section" },
+          h3({}, `Derived Skills (${derivedSkills.length})`),
+          div(
+            { className: "skill-badges" },
+            ...derivedSkills
+              .slice(0, 8)
+              .map((skill) =>
+                span({ className: "badge badge-default" }, skill.name),
+              ),
+            derivedSkills.length > 8
+              ? span(
+                  { className: "text-muted" },
+                  ` +${derivedSkills.length - 8} more`,
+                )
+              : null,
+          ),
+        )
+      : null,
+
+    // Profile section
+    section(
+      { className: "agent-section" },
+      div(
+        { className: "section-header" },
+        h3({}, "Agent Profile"),
+        createCopyButton(profileContent),
+      ),
+      p({ className: "filename" }, profile.filename),
+      createCodeBlock(profileContent),
+    ),
+
+    // Download button
+    createStageAgentDownloadButton(profile, vscodeSettings),
+  );
+}
+
+/**
+ * Create checklist preview grouped by capability
+ * @param {Array} checklist - Checklist items with capability and items
+ * @returns {HTMLElement}
+ */
+function createChecklistPreview(checklist) {
+  return div(
+    { className: "checklist-preview" },
+    ...checklist.map((group) =>
+      div(
+        { className: "checklist-group" },
+        div({ className: "checklist-capability" }, group.capability),
+        div(
+          { className: "checklist-items" },
+          ...group.items.map((item) =>
+            div(
+              { className: "checklist-item" },
+              span({ className: "checklist-checkbox" }, "☐"),
+              span({}, item),
+            ),
+          ),
+        ),
+      ),
+    ),
+  );
+}
+
+/**
+ * Create download button for stage agent
+ * @param {Object} profile - Agent profile
+ * @param {Object} vscodeSettings - VS Code settings
+ * @returns {HTMLElement}
+ */
+function createStageAgentDownloadButton(profile, vscodeSettings) {
+  const btn = button(
+    { className: "btn btn-primary download-all-btn" },
+    "📥 Download Agent Profile",
+  );
+
+  btn.addEventListener("click", async () => {
+    btn.disabled = true;
+    btn.textContent = "Generating...";
+
+    try {
+      const JSZip = await importJSZip();
+      const zip = new JSZip();
+
+      // Add profile
+      const profileContent = formatAgentProfile(profile);
+      zip.file(`.github/agents/${profile.filename}`, profileContent);
+
+      // Add VS Code settings
+      if (Object.keys(vscodeSettings).length > 0) {
+        zip.file(
+          ".vscode/settings.json",
+          JSON.stringify(vscodeSettings, null, 2) + "\n",
+        );
+      }
+
+      // Generate and download
+      const blob = await zip.generateAsync({ type: "blob" });
+      const url = URL.createObjectURL(blob);
+
+      const link = document.createElement("a");
+      link.href = url;
+      link.download = `${profile.frontmatter.name}-agent.zip`;
+      document.body.appendChild(link);
+      link.click();
+      document.body.removeChild(link);
+
+      URL.revokeObjectURL(url);
+    } finally {
+      btn.disabled = false;
+      btn.textContent = "📥 Download Agent Profile";
+    }
+  });
+
+  return btn;
+}

package/app/formatters/agent/profile.js

@@ -0,0 +1,133 @@
+/**
+ * Agent Profile Formatter
+ *
+ * Formats agent profile data into .agent.md file content
+ * following the GitHub Copilot Custom Agents specification.
+ */
+
+/**
+ * Format YAML frontmatter value
+ * @param {any} value - Value to format
+ * @returns {string} Formatted value
+ */
+function formatYamlValue(value) {
+  if (Array.isArray(value)) {
+    return JSON.stringify(value);
+  }
+  if (typeof value === "boolean") {
+    return String(value);
+  }
+  if (typeof value === "string") {
+    // Quote strings that contain special characters or newlines
+    if (value.includes("\n") || value.includes(":") || value.includes("#")) {
+      return `"${value.replace(/"/g, '\\"')}"`;
+    }
+    return value;
+  }
+  return String(value);
+}
+
+/**
+ * Format handoffs array as YAML
+ * @param {Array} handoffs - Array of handoff objects
+ * @returns {string[]} YAML lines for handoffs
+ */
+function formatHandoffs(handoffs) {
+  const lines = ["handoffs:"];
+  for (const handoff of handoffs) {
+    lines.push(`  - label: ${formatYamlValue(handoff.label)}`);
+    if (handoff.agent) {
+      lines.push(`    agent: ${formatYamlValue(handoff.agent)}`);
+    }
+
+    // Format prompt as single-line string, replacing newlines with spaces
+    const singleLinePrompt = handoff.prompt
+      .replace(/\n\n+/g, " ")
+      .replace(/\n/g, " ")
+      .replace(/\s+/g, " ")
+      .trim();
+    lines.push(`    prompt: ${formatYamlValue(singleLinePrompt)}`);
+
+    if (handoff.send !== undefined) {
+      lines.push(`    send: ${formatYamlValue(handoff.send)}`);
+    }
+  }
+  return lines;
+}
+
+/**
+ * Format agent profile as .agent.md file content
+ * @param {Object} profile - Profile with frontmatter and body
+ * @param {Object} profile.frontmatter - YAML frontmatter data
+ * @param {string} profile.frontmatter.name - Agent name
+ * @param {string} profile.frontmatter.description - Agent description
+ * @param {string[]} profile.frontmatter.tools - Available tools
+ * @param {boolean} profile.frontmatter.infer - Whether to auto-select
+ * @param {Array} [profile.frontmatter.handoffs] - Handoff definitions
+ * @param {string} profile.body - Markdown body content
+ * @returns {string} Complete .agent.md file content
+ */
+export function formatAgentProfile({ frontmatter, body }) {
+  const lines = ["---"];
+
+  // Name (optional but recommended)
+  if (frontmatter.name) {
+    lines.push(`name: ${formatYamlValue(frontmatter.name)}`);
+  }
+
+  // Description (required)
+  lines.push(`description: ${formatYamlValue(frontmatter.description)}`);
+
+  // Tools (optional, defaults to all)
+  if (frontmatter.tools && frontmatter.tools.length > 0) {
+    lines.push(`tools: ${formatYamlValue(frontmatter.tools)}`);
+  }
+
+  // Infer (optional)
+  if (frontmatter.infer !== undefined) {
+    lines.push(`infer: ${formatYamlValue(frontmatter.infer)}`);
+  }
+
+  // Handoffs (optional)
+  if (frontmatter.handoffs && frontmatter.handoffs.length > 0) {
+    lines.push(...formatHandoffs(frontmatter.handoffs));
+  }
+
+  lines.push("---");
+  lines.push("");
+  lines.push(body);
+
+  return lines.join("\n");
+}
+
+/**
+ * Format agent profile for CLI output (markdown)
+ * @param {Object} profile - Profile with frontmatter and body
+ * @returns {string} Markdown formatted for CLI display
+ */
+export function formatAgentProfileForCli({ frontmatter, body }) {
+  const lines = [];
+
+  lines.push(`# Agent Profile: ${frontmatter.name}`);
+  lines.push("");
+  lines.push(`**Description:** ${frontmatter.description}`);
+  lines.push("");
+  lines.push(`**Tools:** ${frontmatter.tools.join(", ")}`);
+  lines.push(`**Infer:** ${frontmatter.infer}`);
+
+  if (frontmatter.handoffs && frontmatter.handoffs.length > 0) {
+    lines.push("");
+    lines.push("**Handoffs:**");
+    for (const handoff of frontmatter.handoffs) {
+      const target = handoff.agent ? ` → ${handoff.agent}` : " (self)";
+      lines.push(`  - ${handoff.label}${target}`);
+    }
+  }
+
+  lines.push("");
+  lines.push("---");
+  lines.push("");
+  lines.push(body);
+
+  return lines.join("\n");
+}