@forwardimpact/pathway 0.1.0

package/app/commands/questions.js

@@ -0,0 +1,179 @@
+/**
+ * Questions CLI Command
+ *
+ * Browse and compare interview questions across skills and behaviours.
+ *
+ * Usage:
+ *   npx pathway questions                    # Summary with stats
+ *   npx pathway questions --list             # Question IDs (for piping)
+ *   npx pathway questions --level=practitioner  # Filter by level
+ *   npx pathway questions --stats            # Detailed statistics
+ */
+
+import {
+  parseFilters,
+  prepareQuestionsView,
+} from "../formatters/questions/shared.js";
+import { questionsToMarkdown } from "../formatters/questions/markdown.js";
+import { questionsToYaml } from "../formatters/questions/yaml.js";
+import { questionsToJson } from "../formatters/questions/json.js";
+import { formatTable } from "../lib/cli-output.js";
+
+/**
+ * Parse questions command options
+ * @param {Object} rawOptions - Raw CLI options
+ * @returns {Object} Parsed options
+ */
+function parseOptions(rawOptions) {
+  return {
+    level: rawOptions.level || null,
+    maturity: rawOptions.maturity || null,
+    skill: rawOptions.skill || null,
+    behaviour: rawOptions.behaviour || null,
+    capability: rawOptions.capability || null,
+    format: rawOptions.format || "table",
+    stats: rawOptions.stats || false,
+    json: rawOptions.json || false,
+    list: rawOptions.list || false,
+  };
+}
+
+/**
+ * Show questions summary
+ * @param {Object} data - Loaded data
+ */
+function showQuestionsSummary(data) {
+  const { skills, behaviours } = data;
+  const questions = data.questions;
+
+  console.log(`\n❓ Questions\n`);
+
+  // Skill questions by level
+  const skillLevels = [
+    "awareness",
+    "foundational",
+    "working",
+    "practitioner",
+    "expert",
+  ];
+  const skillRows = skillLevels.map((level) => {
+    let count = 0;
+    for (const skill of skills) {
+      const sq = questions.skills?.[skill.id];
+      if (sq?.[level]) {
+        count += sq[level].length;
+      }
+    }
+    return [level, count];
+  });
+
+  console.log("Skill Questions:");
+  console.log(formatTable(["Level", "Count"], skillRows));
+
+  // Behaviour questions by maturity
+  const maturities = [
+    "emerging",
+    "developing",
+    "practicing",
+    "role_modeling",
+    "exemplifying",
+  ];
+  const behaviourRows = maturities.map((maturity) => {
+    let count = 0;
+    for (const behaviour of behaviours) {
+      const bq = questions.behaviours?.[behaviour.id];
+      if (bq?.[maturity]) {
+        count += bq[maturity].length;
+      }
+    }
+    return [maturity.replace(/_/g, " "), count];
+  });
+
+  console.log("\nBehaviour Questions:");
+  console.log(formatTable(["Maturity", "Count"], behaviourRows));
+
+  console.log(`\nRun 'npx pathway questions --list' for question IDs`);
+  console.log(`Run 'npx pathway questions --stats' for detailed stats`);
+  console.log(`Run 'npx pathway questions --level=practitioner' to filter\n`);
+}
+
+/**
+ * Run the questions command
+ * @param {Object} params
+ * @param {Object} params.data - Loaded data
+ * @param {string[]} params.args - Command arguments
+ * @param {Object} params.options - Parsed options
+ */
+export async function runQuestionsCommand({
+  data,
+  args: _args,
+  options: rawOptions,
+}) {
+  const options = parseOptions(rawOptions);
+
+  // Handle --json as alias for --format=json
+  if (options.json) {
+    options.format = "json";
+  }
+
+  // No filters and no format: Show summary
+  const hasFilters =
+    options.level ||
+    options.maturity ||
+    options.skill ||
+    options.behaviour ||
+    options.capability;
+
+  if (!hasFilters && !options.stats && !options.list) {
+    showQuestionsSummary(data);
+    return;
+  }
+
+  // --list: Output question IDs for piping
+  if (options.list) {
+    const filter = parseFilters(options);
+    const view = prepareQuestionsView({
+      questionBank: data.questions,
+      skills: data.skills,
+      behaviours: data.behaviours,
+      filter,
+    });
+    for (const section of view.sections) {
+      for (const q of section.questions) {
+        console.log(q.id);
+      }
+    }
+    return;
+  }
+
+  // Parse filters
+  const filter = parseFilters(options);
+
+  // Prepare view
+  const view = prepareQuestionsView({
+    questionBank: data.questions,
+    skills: data.skills,
+    behaviours: data.behaviours,
+    filter,
+  });
+
+  // Format output
+  let output;
+  switch (options.format) {
+    case "yaml":
+      output = questionsToYaml(view, options);
+      break;
+    case "json":
+      output = questionsToJson(view, options);
+      break;
+    case "table":
+    default:
+      output = questionsToMarkdown(view, {
+        stats: options.stats,
+        skills: data.skills,
+      });
+      break;
+  }
+
+  console.log(output);
+}

package/app/commands/serve.js

@@ -0,0 +1,143 @@
+/**
+ * Serve Command
+ *
+ * Serves the Engineering Pathway web application with local data.
+ * Uses Node.js built-in http module (no external dependencies).
+ */
+
+import { createServer } from "http";
+import { readFile, stat } from "fs/promises";
+import { join, extname, dirname } from "path";
+import { fileURLToPath } from "url";
+import { generateAllIndexes } from "../model/index-generator.js";
+import { loadFrameworkConfig } from "../model/loader.js";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const publicDir = join(__dirname, "..");
+
+const MIME_TYPES = {
+  ".html": "text/html; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".js": "application/javascript; charset=utf-8",
+  ".yaml": "text/yaml; charset=utf-8",
+  ".yml": "text/yaml; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".svg": "image/svg+xml",
+  ".png": "image/png",
+  ".ico": "image/x-icon",
+  ".woff": "font/woff",
+  ".woff2": "font/woff2",
+};
+
+/**
+ * Get MIME type for a file extension
+ * @param {string} ext - File extension including dot
+ * @returns {string} MIME type
+ */
+function getMimeType(ext) {
+  return MIME_TYPES[ext.toLowerCase()] || "application/octet-stream";
+}
+
+/**
+ * Serve a static file
+ * @param {import('http').ServerResponse} res - HTTP response
+ * @param {string} filePath - Path to file
+ */
+async function serveFile(res, filePath) {
+  try {
+    const content = await readFile(filePath);
+    const ext = extname(filePath);
+    res.setHeader("Content-Type", getMimeType(ext));
+    res.end(content);
+  } catch (err) {
+    if (err.code === "ENOENT") {
+      res.statusCode = 404;
+      res.setHeader("Content-Type", "text/plain");
+      res.end("Not Found");
+    } else {
+      res.statusCode = 500;
+      res.setHeader("Content-Type", "text/plain");
+      res.end("Internal Server Error");
+    }
+  }
+}
+
+/**
+ * Check if a path is a directory
+ * @param {string} path - Path to check
+ * @returns {Promise<boolean>}
+ */
+async function isDirectory(path) {
+  try {
+    const stats = await stat(path);
+    return stats.isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Run the serve command
+ * @param {Object} params - Command parameters
+ * @param {string} params.dataDir - Path to data directory
+ * @param {Object} params.options - Command options
+ */
+export async function runServeCommand({ dataDir, options }) {
+  const port = options.port || 3000;
+
+  // Load framework config for display
+  let framework;
+  try {
+    framework = await loadFrameworkConfig(dataDir);
+  } catch {
+    // Fallback if framework config fails
+    framework = { emoji: "🚀", title: "Engineering Pathway" };
+  }
+
+  // Generate _index.yaml files before serving
+  console.log("Generating index files...");
+  await generateAllIndexes(dataDir);
+
+  const server = createServer(async (req, res) => {
+    const url = new URL(req.url, `http://localhost:${port}`);
+    let pathname = url.pathname;
+
+    // Handle trailing slash for directories
+    if (pathname.endsWith("/") && pathname !== "/") {
+      pathname = pathname.slice(0, -1);
+    }
+
+    let filePath;
+
+    if (pathname.startsWith("/data/")) {
+      // Serve from user's data directory
+      filePath = join(dataDir, pathname.slice(6));
+    } else if (pathname === "/" || pathname === "") {
+      // Serve index.html for root
+      filePath = join(publicDir, "index.html");
+    } else {
+      // Serve from package's public directory
+      filePath = join(publicDir, pathname);
+    }
+
+    // Check if path is a directory, serve index.html if so
+    if (await isDirectory(filePath)) {
+      filePath = join(filePath, "index.html");
+    }
+
+    await serveFile(res, filePath);
+  });
+
+  server.listen(port, () => {
+    console.log(`
+${framework.emoji} ${framework.title} running at http://localhost:${port}
+📁 Data directory: ${dataDir}
+
+Press Ctrl+C to stop the server.
+`);
+  });
+
+  // Keep the process running
+  return new Promise(() => {});
+}

package/app/commands/site.js

@@ -0,0 +1,121 @@
+/**
+ * Site Command
+ *
+ * Generates a static site from the Engineering Pathway data.
+ * Copies all necessary files (HTML, JS, CSS) and data to an output directory.
+ */
+
+import { cp, mkdir, rm, access, realpath } from "fs/promises";
+import { join, dirname, relative, resolve } from "path";
+import { fileURLToPath } from "url";
+import { generateAllIndexes } from "../model/index-generator.js";
+import { loadFrameworkConfig } from "../model/loader.js";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const appDir = join(__dirname, "..");
+
+/**
+ * Files and directories to copy from app/
+ */
+const PUBLIC_ASSETS = [
+  // HTML entry points
+  "index.html",
+  "slides.html",
+  "handout.html",
+  // JavaScript entry points
+  "main.js",
+  "slide-main.js",
+  "handout-main.js",
+  "types.js",
+  // Directories
+  "css",
+  "lib",
+  "model",
+  "pages",
+  "slides",
+  "components",
+  "formatters",
+];
+
+/**
+ * Run the site command
+ * @param {Object} params - Command parameters
+ * @param {string} params.dataDir - Path to data directory
+ * @param {Object} params.options - Command options
+ */
+export async function runSiteCommand({ dataDir, options }) {
+  const outputDir = options.output || join(process.cwd(), "site");
+  const clean = options.clean !== false;
+
+  // Load framework config for display
+  let framework;
+  try {
+    framework = await loadFrameworkConfig(dataDir);
+  } catch {
+    framework = { emoji: "🚀", title: "Engineering Pathway" };
+  }
+
+  console.log(`
+${framework.emoji} Generating ${framework.title} static site...
+`);
+
+  // Clean output directory if requested
+  if (clean) {
+    try {
+      await access(outputDir);
+      console.log(`🗑️  Cleaning ${outputDir}...`);
+      await rm(outputDir, { recursive: true });
+    } catch {
+      // Directory doesn't exist, nothing to clean
+    }
+  }
+
+  // Create output directory
+  await mkdir(outputDir, { recursive: true });
+
+  // Generate index files in data directory
+  console.log("📇 Generating index files...");
+  await generateAllIndexes(dataDir);
+
+  // Copy app assets
+  console.log("📦 Copying application files...");
+  for (const asset of PUBLIC_ASSETS) {
+    const src = join(appDir, 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");
+
+  // Check if source and destination are the same (e.g., when --output=.)
+  const resolvedDataDir = await realpath(dataDir).catch(() => resolve(dataDir));
+  const resolvedDataOutputDir = resolve(dataOutputDir);
+
+  if (resolvedDataDir === resolvedDataOutputDir) {
+    console.log(`   ✓ data/ (already in place)`);
+  } else {
+    await cp(dataDir, dataOutputDir, { recursive: true, dereference: true });
+    console.log(`   ✓ data/ (from ${relative(process.cwd(), dataDir)})`);
+  }
+
+  // Show summary
+  console.log(`
+✅ Site generated successfully!
+
+Output: ${outputDir}
+
+To serve locally:
+  cd ${relative(process.cwd(), outputDir) || "."}
+  npx serve .
+`);
+}

package/app/commands/skill.js

@@ -0,0 +1,76 @@
+/**
+ * Skill CLI Command
+ *
+ * Handles skill summary, listing, and detail display in the terminal.
+ *
+ * Usage:
+ *   npx pathway skill              # Summary with stats
+ *   npx pathway skill --list       # IDs only (for piping)
+ *   npx pathway skill <id>         # Detail view
+ *   npx pathway skill --validate   # Validation checks
+ */
+
+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";
+
+/**
+ * Format skill summary output
+ * @param {Array} skills - Raw skill entities
+ * @param {Object} data - Full data context
+ */
+function formatSummary(skills, data) {
+  const { capabilities, framework } = data;
+  const { groups, groupOrder } = prepareSkillsList(skills, capabilities);
+  const emoji = framework ? getConceptEmoji(framework, "skill") : "📚";
+
+  console.log(`\n${emoji} Skills\n`);
+
+  // Summary table by capability
+  const rows = groupOrder.map((capability) => {
+    const count = groups[capability]?.length || 0;
+    const withAgent = groups[capability]?.filter((s) => s.agent).length || 0;
+    return [capability, count, withAgent];
+  });
+
+  console.log(formatTable(["Capability", "Count", "Agent"], rows));
+  console.log(`\nTotal: ${skills.length} skills`);
+  console.log(`\nRun 'npx pathway skill --list' for IDs`);
+  console.log(`Run 'npx pathway skill <id>' for details\n`);
+}
+
+/**
+ * Format skill detail output
+ * @param {Object} viewAndContext - Contains skill entity and context
+ * @param {Object} framework - Framework config
+ */
+function formatDetail(viewAndContext, framework) {
+  const { skill, disciplines, tracks, drivers, capabilities } = viewAndContext;
+  console.log(
+    skillToMarkdown(skill, {
+      disciplines,
+      tracks,
+      drivers,
+      capabilities,
+      framework,
+    }),
+  );
+}
+
+export const runSkillCommand = createEntityCommand({
+  entityName: "skill",
+  pluralName: "skills",
+  findEntity: (data, id) => data.skills.find((s) => s.id === id),
+  presentDetail: (entity, data) => ({
+    skill: entity,
+    disciplines: data.disciplines,
+    tracks: data.tracks,
+    drivers: data.drivers,
+    capabilities: data.capabilities,
+  }),
+  formatSummary,
+  formatDetail,
+  emoji: "📚",
+});

package/app/commands/stage.js

@@ -0,0 +1,129 @@
+/**
+ * Stage CLI Command
+ *
+ * Handles stage summary, listing, and detail display in the terminal.
+ *
+ * Usage:
+ *   npx pathway stage              # Summary with lifecycle flow
+ *   npx pathway stage --list       # IDs only (for piping)
+ *   npx pathway stage <id>         # Detail view
+ */
+
+import { createEntityCommand } from "./command-factory.js";
+import {
+  prepareStageDetail,
+  getStageEmoji,
+} from "../formatters/stage/shared.js";
+import { formatTable } from "../lib/cli-output.js";
+import {
+  formatHeader,
+  formatSubheader,
+  formatBullet,
+} from "../lib/cli-output.js";
+
+/**
+ * Format stage summary output
+ * @param {Array} stages - Raw stage entities
+ * @param {Object} _data - Full data context (unused)
+ */
+function formatSummary(stages, _data) {
+  console.log("\n🔄 Stages\n");
+
+  // Show lifecycle flow
+  const flow = stages
+    .map((s) => `${getStageEmoji(stages, s.id)} ${s.name}`)
+    .join(" → ");
+  console.log(`Lifecycle: ${flow}\n`);
+
+  const rows = stages.map((s) => {
+    const toolCount = s.tools?.length || 0;
+    const handoffCount = s.handoffs?.length || 0;
+    return [s.id, s.name, s.mode, toolCount, handoffCount];
+  });
+
+  console.log(formatTable(["ID", "Name", "Mode", "Tools", "Handoffs"], rows));
+  console.log(`\nTotal: ${stages.length} stages`);
+  console.log(`\nRun 'npx pathway stage --list' for IDs`);
+  console.log(`Run 'npx pathway stage <id>' for details\n`);
+}
+
+/**
+ * Format stage detail output
+ * @param {Object} viewAndContext - Contains stage entity and context
+ * @param {Object} _framework - Framework config (unused)
+ */
+function formatDetail(viewAndContext, _framework) {
+  const { stage, stages } = viewAndContext;
+  const view = prepareStageDetail(stage);
+  const emoji = getStageEmoji(stages, stage.id);
+
+  console.log(formatHeader(`\n${emoji} ${view.name}\n`));
+  console.log(`Mode: ${view.modeBadge}\n`);
+  console.log(`${view.description}\n`);
+
+  // Tools
+  if (view.tools.length > 0) {
+    console.log(formatSubheader("Tools\n"));
+    for (const tool of view.tools) {
+      console.log(formatBullet(`${tool.icon} ${tool.label}`, 1));
+    }
+    console.log();
+  }
+
+  // Entry criteria
+  if (view.entryCriteria.length > 0) {
+    console.log(formatSubheader("Entry Criteria\n"));
+    for (const item of view.entryCriteria) {
+      console.log(formatBullet(item, 1));
+    }
+    console.log();
+  }
+
+  // Exit criteria
+  if (view.exitCriteria.length > 0) {
+    console.log(formatSubheader("Exit Criteria\n"));
+    for (const item of view.exitCriteria) {
+      console.log(formatBullet(item, 1));
+    }
+    console.log();
+  }
+
+  // Constraints
+  if (view.constraints.length > 0) {
+    console.log(formatSubheader("Constraints\n"));
+    for (const item of view.constraints) {
+      console.log(formatBullet(`⚠️  ${item}`, 1));
+    }
+    console.log();
+  }
+
+  // Handoffs
+  if (view.handoffs.length > 0) {
+    console.log(formatSubheader("Handoffs\n"));
+    for (const handoff of view.handoffs) {
+      const targetStage = stages.find((s) => s.id === handoff.target);
+      const targetEmoji = getStageEmoji(stages, handoff.target);
+      const targetName = targetStage?.name || handoff.target;
+      console.log(
+        formatBullet(`${targetEmoji} ${handoff.label} → ${targetName}`, 1),
+      );
+      if (handoff.prompt) {
+        console.log(`      "${handoff.prompt}"`);
+      }
+    }
+    console.log();
+  }
+}
+
+export const runStageCommand = createEntityCommand({
+  entityName: "stage",
+  pluralName: "stages",
+  findEntity: (data, id) => data.stages?.find((s) => s.id === id),
+  presentDetail: (entity, data) => ({
+    stage: entity,
+    stages: data.stages || [],
+  }),
+  formatSummary,
+  formatDetail,
+  emoji: "🔄",
+});