@forwardimpact/pathway 0.1.0

package/app/commands/discipline.js

@@ -0,0 +1,58 @@
+/**
+ * Discipline CLI Command
+ *
+ * Handles discipline summary, listing, and detail display in the terminal.
+ *
+ * Usage:
+ *   npx pathway discipline              # Summary with stats
+ *   npx pathway discipline --list       # IDs only (for piping)
+ *   npx pathway discipline <id>         # Detail view
+ *   npx pathway discipline --validate   # Validation checks
+ */
+
+import { createEntityCommand } from "./command-factory.js";
+import { disciplineToMarkdown } from "../formatters/discipline/markdown.js";
+import { formatTable } from "../lib/cli-output.js";
+
+/**
+ * Format discipline summary output
+ * @param {Array} disciplines - Raw discipline entities
+ */
+function formatSummary(disciplines) {
+  console.log(`\n📋 Disciplines\n`);
+
+  const rows = disciplines.map((d) => [
+    d.id,
+    d.coreSkills?.length || 0,
+    d.supportingSkills?.length || 0,
+    d.broadSkills?.length || 0,
+  ]);
+
+  console.log(formatTable(["ID", "Core", "Supporting", "Broad"], rows));
+  console.log(`\nTotal: ${disciplines.length} disciplines`);
+  console.log(`\nRun 'npx pathway discipline --list' for IDs`);
+  console.log(`Run 'npx pathway discipline <id>' for details\n`);
+}
+
+/**
+ * Format discipline detail output
+ * @param {Object} viewAndContext - Contains discipline entity and context
+ */
+function formatDetail(viewAndContext) {
+  const { discipline, skills, behaviours } = viewAndContext;
+  console.log(disciplineToMarkdown(discipline, { skills, behaviours }));
+}
+
+export const runDisciplineCommand = createEntityCommand({
+  entityName: "discipline",
+  pluralName: "disciplines",
+  findEntity: (data, id) => data.disciplines.find((d) => d.id === id),
+  presentDetail: (entity, data) => ({
+    discipline: entity,
+    skills: data.skills,
+    behaviours: data.behaviours,
+  }),
+  formatSummary,
+  formatDetail,
+  emoji: "📋",
+});

package/app/commands/driver.js

@@ -0,0 +1,94 @@
+/**
+ * Driver CLI Command
+ *
+ * Handles driver summary, listing, and detail display in the terminal.
+ *
+ * Usage:
+ *   npx pathway driver              # Summary with stats
+ *   npx pathway driver --list       # IDs only (for piping)
+ *   npx pathway driver <id>         # Detail view
+ *   npx pathway driver --validate   # Validation checks
+ */
+
+import { createEntityCommand } from "./command-factory.js";
+import { prepareDriverDetail } from "../formatters/driver/shared.js";
+import { formatTable } from "../lib/cli-output.js";
+import {
+  formatHeader,
+  formatSubheader,
+  formatBullet,
+} from "../lib/cli-output.js";
+import { getConceptEmoji } from "../model/levels.js";
+
+/**
+ * Format driver summary output
+ * @param {Array} drivers - Raw driver entities
+ * @param {Object} data - Full data context
+ */
+function formatSummary(drivers, data) {
+  const { skills, behaviours, framework } = data;
+  const emoji = framework ? getConceptEmoji(framework, "driver") : "🎯";
+
+  console.log(`\n${emoji} Drivers\n`);
+
+  const rows = drivers.map((d) => {
+    const contributingSkills = skills.filter((s) =>
+      d.contributingSkills?.includes(s.id),
+    ).length;
+    const contributingBehaviours = behaviours.filter((b) =>
+      d.contributingBehaviours?.includes(b.id),
+    ).length;
+    return [d.id, d.name, contributingSkills, contributingBehaviours];
+  });
+
+  console.log(formatTable(["ID", "Name", "Skills", "Behaviours"], rows));
+  console.log(`\nTotal: ${drivers.length} drivers`);
+  console.log(`\nRun 'npx pathway driver --list' for IDs`);
+  console.log(`Run 'npx pathway driver <id>' for details\n`);
+}
+
+/**
+ * Format driver detail output
+ * @param {Object} viewAndContext - Contains driver entity and context
+ * @param {Object} framework - Framework config
+ */
+function formatDetail(viewAndContext, framework) {
+  const { driver, skills, behaviours } = viewAndContext;
+  const view = prepareDriverDetail(driver, { skills, behaviours });
+  const emoji = framework ? getConceptEmoji(framework, "driver") : "🎯";
+
+  console.log(formatHeader(`\n${emoji} ${view.name}\n`));
+  console.log(`${view.description}\n`);
+
+  // Contributing skills
+  if (view.contributingSkills.length > 0) {
+    console.log(formatSubheader("Contributing Skills\n"));
+    for (const s of view.contributingSkills) {
+      console.log(formatBullet(s.name, 1));
+    }
+    console.log();
+  }
+
+  // Contributing behaviours
+  if (view.contributingBehaviours.length > 0) {
+    console.log(formatSubheader("Contributing Behaviours\n"));
+    for (const b of view.contributingBehaviours) {
+      console.log(formatBullet(b.name, 1));
+    }
+    console.log();
+  }
+}
+
+export const runDriverCommand = createEntityCommand({
+  entityName: "driver",
+  pluralName: "drivers",
+  findEntity: (data, id) => data.drivers.find((d) => d.id === id),
+  presentDetail: (entity, data) => ({
+    driver: entity,
+    skills: data.skills,
+    behaviours: data.behaviours,
+  }),
+  formatSummary,
+  formatDetail,
+  emoji: "🎯",
+});

package/app/commands/grade.js

@@ -0,0 +1,60 @@
+/**
+ * Grade CLI Command
+ *
+ * Handles grade summary, listing, and detail display in the terminal.
+ *
+ * Usage:
+ *   npx pathway grade              # Summary with stats
+ *   npx pathway grade --list       # IDs only (for piping)
+ *   npx pathway grade <id>         # Detail view
+ *   npx pathway grade --validate   # Validation checks
+ */
+
+import { createEntityCommand } from "./command-factory.js";
+import { gradeToMarkdown } from "../formatters/grade/markdown.js";
+import { formatTable } from "../lib/cli-output.js";
+import { getConceptEmoji } from "../model/levels.js";
+import { capitalize } from "../formatters/shared.js";
+
+/**
+ * Format grade summary output
+ * @param {Array} grades - Raw grade entities
+ * @param {Object} data - Full data context
+ */
+function formatSummary(grades, data) {
+  const { framework } = data;
+  const emoji = framework ? getConceptEmoji(framework, "grade") : "📊";
+
+  console.log(`\n${emoji} Grades\n`);
+
+  const rows = grades.map((g) => [
+    g.id,
+    g.displayName || g.id,
+    g.typicalExperienceRange || "-",
+    capitalize(g.baseSkillLevels?.primary || "-"),
+  ]);
+
+  console.log(formatTable(["ID", "Name", "Experience", "Primary Level"], rows));
+  console.log(`\nTotal: ${grades.length} grades`);
+  console.log(`\nRun 'npx pathway grade --list' for IDs`);
+  console.log(`Run 'npx pathway grade <id>' for details\n`);
+}
+
+/**
+ * Format grade detail output
+ * @param {Object} grade - Raw grade entity
+ * @param {Object} framework - Framework config
+ */
+function formatDetail(grade, framework) {
+  console.log(gradeToMarkdown(grade, framework));
+}
+
+export const runGradeCommand = createEntityCommand({
+  entityName: "grade",
+  pluralName: "grades",
+  findEntity: (data, id) => data.grades.find((g) => g.id === id),
+  presentDetail: (entity) => entity,
+  formatSummary,
+  formatDetail,
+  emoji: "📊",
+});

package/app/commands/index.js

@@ -0,0 +1,20 @@
+/**
+ * CLI Commands Index
+ *
+ * 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 { runStageCommand } from "./stage.js";
+export { runJobCommand } from "./job.js";
+export { runInterviewCommand } from "./interview.js";
+export { runProgressCommand } from "./progress.js";
+export { runQuestionsCommand } from "./questions.js";
+export { runServeCommand } from "./serve.js";
+export { runInitCommand } from "./init.js";
+export { runSiteCommand } from "./site.js";

package/app/commands/init.js

@@ -0,0 +1,67 @@
+/**
+ * Init Command
+ *
+ * Initializes a new Engineering Pathway project by copying example data.
+ */
+
+import { cp, access } from "fs/promises";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const examplesDir = join(__dirname, "..", "..", "examples");
+
+/**
+ * Run the init command
+ * @param {Object} params - Command parameters
+ * @param {Object} params.options - Command options
+ */
+export async function runInitCommand({ options }) {
+  const targetPath = options.path || process.cwd();
+  const dataDir = join(targetPath, "data");
+
+  // Check if data/ already exists
+  try {
+    await access(dataDir);
+    console.error("Error: ./data/ already exists.");
+    console.error("Remove it first or use a different directory.");
+    process.exit(1);
+  } catch {
+    // Directory doesn't exist, proceed
+  }
+
+  // Check if examples directory exists
+  try {
+    await access(examplesDir);
+  } catch {
+    console.error("Error: Examples directory not found in package.");
+    console.error("This may indicate a corrupted package installation.");
+    process.exit(1);
+  }
+
+  // Copy example data
+  console.log("Creating ./data/ with example data...\n");
+  await cp(examplesDir, dataDir, { recursive: true });
+
+  console.log(`✅ Created ./data/ with example data.
+
+Next steps:
+  1. Edit data files to match your organization
+  2. npx pathway --validate
+  3. npx pathway serve
+
+Data structure:
+  data/
+  ├── framework.yaml      # Framework metadata
+  ├── grades.yaml         # Career levels
+  ├── stages.yaml         # Lifecycle stages
+  ├── drivers.yaml        # Business drivers
+  ├── capabilities.yaml   # Capability areas
+  ├── disciplines/        # Engineering disciplines
+  ├── tracks/             # Role tracks
+  ├── skills/             # Technical skills
+  ├── behaviours/         # Behavioural expectations
+  └── questions/          # Interview questions
+`);
+}

package/app/commands/interview.js

@@ -0,0 +1,68 @@
+/**
+ * Interview CLI Command
+ *
+ * Generates and displays interview questions in the terminal.
+ */
+
+import { createCompositeCommand } from "./command-factory.js";
+import {
+  prepareInterviewDetail,
+  INTERVIEW_TYPES,
+} from "../formatters/interview/shared.js";
+import { interviewToMarkdown } from "../formatters/interview/markdown.js";
+
+/**
+ * Format interview output
+ * @param {Object} view - Presenter view
+ * @param {Object} options - Options including framework
+ */
+function formatInterview(view, options) {
+  console.log(interviewToMarkdown(view, { framework: options.framework }));
+}
+
+export const runInterviewCommand = createCompositeCommand({
+  commandName: "interview",
+  requiredArgs: ["discipline_id", "track_id", "grade_id"],
+  findEntities: (data, args, options) => {
+    const interviewType = options.type || "full";
+
+    if (!INTERVIEW_TYPES[interviewType]) {
+      console.error(`Unknown interview type: ${interviewType}`);
+      console.error("Available types: full, short, behaviour");
+      process.exit(1);
+    }
+
+    return {
+      discipline: data.disciplines.find((d) => d.id === args[0]),
+      track: data.tracks.find((t) => t.id === args[1]),
+      grade: data.grades.find((g) => g.id === args[2]),
+      interviewType,
+    };
+  },
+  validateEntities: (entities, _data) => {
+    if (!entities.discipline) {
+      return `Discipline not found: ${entities.discipline}`;
+    }
+    if (!entities.grade) {
+      return `Grade not found: ${entities.grade}`;
+    }
+    if (!entities.track) {
+      return `Track not found: ${entities.track}`;
+    }
+    return null;
+  },
+  presenter: (entities, data, _options) =>
+    prepareInterviewDetail({
+      discipline: entities.discipline,
+      grade: entities.grade,
+      track: entities.track,
+      skills: data.skills,
+      behaviours: data.behaviours,
+      questions: data.questions,
+      interviewType: entities.interviewType,
+    }),
+  formatter: (view, options, data) =>
+    formatInterview(view, { ...options, framework: data.framework }),
+  usageExample:
+    "npx pathway interview software_engineering platform L4 --type=short",
+});

package/app/commands/job.js

@@ -0,0 +1,157 @@
+/**
+ * Job CLI Command
+ *
+ * Generates and displays job definitions in the terminal.
+ *
+ * Usage:
+ *   npx pathway job                              # Summary with stats
+ *   npx pathway job --list                       # All valid combinations (for piping)
+ *   npx pathway job <discipline> <track> <grade> # Detail view
+ *   npx pathway job se platform L3 --checklist=code_to_review # Show checklist for handoff
+ *   npx pathway job --validate                   # Validation checks
+ */
+
+import { prepareJobDetail } from "../model/job.js";
+import { jobToMarkdown } from "../formatters/job/markdown.js";
+import { generateAllJobs } from "../model/derivation.js";
+import { formatTable } from "../lib/cli-output.js";
+import {
+  deriveChecklist,
+  formatChecklistMarkdown,
+} from "../model/checklist.js";
+
+/**
+ * Format job output
+ * @param {Object} view - Presenter view
+ * @param {Object} _options - Command options
+ * @param {Object} entities - Original entities
+ */
+function formatJob(view, _options, entities) {
+  console.log(jobToMarkdown(view, entities));
+}
+
+/**
+ * Run job command
+ * @param {Object} params
+ * @param {Object} params.data - All loaded data
+ * @param {string[]} params.args - Command arguments
+ * @param {Object} params.options - Command options
+ */
+export async function runJobCommand({ data, args, options }) {
+  const jobs = generateAllJobs({
+    disciplines: data.disciplines,
+    grades: data.grades,
+    tracks: data.tracks,
+    skills: data.skills,
+    behaviours: data.behaviours,
+    validationRules: data.framework.validationRules,
+  });
+
+  // --list: Output clean lines for piping
+  if (options.list) {
+    for (const job of jobs) {
+      console.log(`${job.discipline.id} ${job.track.id} ${job.grade.id}`);
+    }
+    return;
+  }
+
+  // No args: Show summary
+  if (args.length === 0) {
+    console.log(`\n💼 Jobs\n`);
+
+    // Count by discipline
+    const byDiscipline = {};
+    for (const job of jobs) {
+      byDiscipline[job.discipline.id] =
+        (byDiscipline[job.discipline.id] || 0) + 1;
+    }
+
+    const rows = Object.entries(byDiscipline).map(([id, count]) => [id, count]);
+    console.log(formatTable(["Discipline", "Combinations"], rows));
+    console.log(`\nTotal: ${jobs.length} valid job combinations`);
+    console.log(`\nRun 'npx pathway job --list' for all combinations`);
+    console.log(
+      `Run 'npx pathway job <discipline> <track> <grade>' for details\n`,
+    );
+    return;
+  }
+
+  // Handle job detail view
+  if (args.length < 3) {
+    console.error("Usage: npx pathway job <discipline> <track> <grade>");
+    console.error("       npx pathway job --list");
+    console.error("Example: npx pathway job software_engineering platform L4");
+    process.exit(1);
+  }
+
+  const discipline = data.disciplines.find((d) => d.id === args[0]);
+  const track = data.tracks.find((t) => t.id === args[1]);
+  const grade = data.grades.find((g) => g.id === args[2]);
+
+  if (!discipline) {
+    console.error(`Discipline not found: ${args[0]}`);
+    console.error(`Available: ${data.disciplines.map((d) => d.id).join(", ")}`);
+    process.exit(1);
+  }
+
+  if (!track) {
+    console.error(`Track not found: ${args[1]}`);
+    console.error(`Available: ${data.tracks.map((t) => t.id).join(", ")}`);
+    process.exit(1);
+  }
+
+  if (!grade) {
+    console.error(`Grade not found: ${args[2]}`);
+    console.error(`Available: ${data.grades.map((g) => g.id).join(", ")}`);
+    process.exit(1);
+  }
+
+  const view = prepareJobDetail({
+    discipline,
+    grade,
+    track,
+    skills: data.skills,
+    behaviours: data.behaviours,
+    drivers: data.drivers,
+    capabilities: data.capabilities,
+  });
+
+  if (!view) {
+    console.error("Failed to generate job output.");
+    process.exit(1);
+  }
+
+  if (options.json) {
+    console.log(JSON.stringify(view, null, 2));
+    return;
+  }
+
+  // --checklist: Show checklist for a specific handoff
+  if (options.checklist) {
+    const validHandoffs = ["plan_to_code", "code_to_review"];
+    if (!validHandoffs.includes(options.checklist)) {
+      console.error(`Invalid handoff: ${options.checklist}`);
+      console.error(`Available: ${validHandoffs.join(", ")}`);
+      process.exit(1);
+    }
+
+    const checklist = deriveChecklist({
+      handoff: options.checklist,
+      skillMatrix: view.skillMatrix,
+      capabilities: data.capabilities,
+    });
+
+    if (checklist.length === 0) {
+      console.log(`\nNo checklist items for ${options.checklist}\n`);
+      return;
+    }
+
+    const handoffLabel = options.checklist.replace(/_/g, " → ");
+    console.log(`\n# ${view.title} — ${handoffLabel}\n`);
+    console.log(formatChecklistMarkdown(checklist));
+    console.log("");
+    return;
+  }
+
+  formatJob(view, options, { discipline, grade, track });
+}

package/app/commands/progress.js

@@ -0,0 +1,77 @@
+/**
+ * Progress CLI Command
+ *
+ * Shows career progression analysis in the terminal.
+ */
+
+import { createCompositeCommand } from "./command-factory.js";
+import {
+  prepareProgressDetail,
+  getDefaultTargetGrade,
+} from "../formatters/progress/shared.js";
+import { progressToMarkdown } from "../formatters/progress/markdown.js";
+
+/**
+ * Format progress output
+ * @param {Object} view - Presenter view
+ */
+function formatProgress(view) {
+  console.log(progressToMarkdown(view));
+}
+
+export const runProgressCommand = createCompositeCommand({
+  commandName: "progress",
+  requiredArgs: ["discipline_id", "track_id", "grade_id"],
+  findEntities: (data, args, options) => {
+    const discipline = data.disciplines.find((d) => d.id === args[0]);
+    const track = data.tracks.find((t) => t.id === args[1]);
+    const grade = data.grades.find((g) => g.id === args[2]);
+
+    let targetGrade;
+    if (options.compare) {
+      targetGrade = data.grades.find((g) => g.id === options.compare);
+      if (!targetGrade) {
+        console.error(`Target grade not found: ${options.compare}`);
+        process.exit(1);
+      }
+    } else {
+      targetGrade = getDefaultTargetGrade(grade, data.grades);
+      if (!targetGrade) {
+        console.error("No next grade available for progression.");
+        process.exit(1);
+      }
+    }
+
+    return { discipline, grade, track, targetGrade };
+  },
+  validateEntities: (entities, _data) => {
+    if (!entities.discipline) {
+      return `Discipline not found`;
+    }
+    if (!entities.grade) {
+      return `Grade not found`;
+    }
+    if (!entities.track) {
+      return `Track not found`;
+    }
+    if (!entities.targetGrade) {
+      return `Target grade not found`;
+    }
+    return null;
+  },
+  presenter: (entities, data) =>
+    prepareProgressDetail({
+      fromDiscipline: entities.discipline,
+      fromGrade: entities.grade,
+      fromTrack: entities.track,
+      toDiscipline: entities.discipline,
+      toGrade: entities.targetGrade,
+      toTrack: entities.track,
+      skills: data.skills,
+      behaviours: data.behaviours,
+      capabilities: data.capabilities,
+    }),
+  formatter: formatProgress,
+  usageExample:
+    "npx pathway progress software_engineering platform L3 --compare=L4",
+});