@forwardimpact/pathway 0.12.0 → 0.14.0

package/bin/fit-pathway.js

@@ -18,7 +18,7 @@
  *   stage [<id>]                Show stages
  *   tool [<name>]               Show tools
  *   job [<discipline> <grade>] [--track=TRACK]  Generate job definition
- *   interview <discipline> <grade> [--track=TRACK] [--type=TYPE]  Generate interview
+ *   interview <discipline> <grade> [--track=TRACK] [--type=mission|decomposition|stakeholder]  Generate interview
  *   progress <discipline> <grade> [--track=TRACK] [--compare=GRADE]  Career progression
  *   questions [options]         Browse interview questions
  *   agent [<discipline> <track>] [--output=PATH]  Generate AI agent
@@ -31,6 +31,7 @@
 
 import { join, resolve } from "path";
 import { existsSync } from "fs";
+import { homedir } from "os";
 import { loadAllData } from "@forwardimpact/schema/loader";
 import { formatError } from "../src/lib/cli-output.js";
 
@@ -51,6 +52,7 @@ import { runAgentCommand } from "../src/commands/agent.js";
 import { runDevCommand } from "../src/commands/dev.js";
 import { runInitCommand } from "../src/commands/init.js";
 import { runBuildCommand } from "../src/commands/build.js";
+import { runUpdateCommand } from "../src/commands/update.js";
 
 const COMMANDS = {
   discipline: runDisciplineCommand,
@@ -86,7 +88,8 @@ GETTING STARTED
 
   init                                Create ./data/ with example data
   dev [--port=PORT]                   Run live development server
-  build [--output=PATH]               Generate static site to ./public/
+  build [--output=PATH] [--url=URL]   Generate static site + distribution bundle
+  update [--url=URL]                  Update local ~/.fit/pathway/ installation
 
 ────────────────────────────────────────────────────────────────────────────────
 ENTITY COMMANDS
@@ -167,13 +170,14 @@ INTERVIEW COMMAND
 Generate interview question sets based on job requirements.
 
 Usage:
-  npx fit-pathway interview <discipline> <grade>
-  npx fit-pathway interview <d> <g> --track=<track>
-  npx fit-pathway interview <d> <g> --type=<type>
+  npx fit-pathway interview <discipline> <grade>                     All types
+  npx fit-pathway interview <d> <g> --track=<track>                  With track
+  npx fit-pathway interview <d> <g> --track=<t> --type=<type>        Single type
 
 Options:
   --track=TRACK       Track specialization
-  --type=TYPE         Interview type: full (default), short
+  --type=TYPE         Interview type: mission, decomposition, stakeholder
+                      (omit for all types)
 
 ────────────────────────────────────────────────────────────────────────────────
 PROGRESS COMMAND
@@ -252,6 +256,7 @@ function parseArgs(args) {
     path: null,
     // Site command options
     clean: true,
+    url: null,
   };
 
   for (const arg of args) {
@@ -307,6 +312,8 @@ function parseArgs(args) {
       result.path = arg.slice(7);
     } else if (arg === "--no-clean") {
       result.clean = false;
+    } else if (arg.startsWith("--url=")) {
+      result.url = arg.slice(6);
     } else if (!arg.startsWith("-")) {
       if (!result.command) {
         result.command = arg;
@@ -331,9 +338,10 @@ function printHelp() {
  * Resolution order:
  * 1. --data=<path> flag (explicit override)
  * 2. PATHWAY_DATA environment variable
- * 3. ./data/ relative to current working directory
- * 4. ./examples/ relative to current working directory
- * 5. apps/schema/examples/ for monorepo development
+ * 3. ~/.fit/pathway/data/ (home directory install)
+ * 4. ./data/ relative to current working directory
+ * 5. ./examples/ relative to current working directory
+ * 6. apps/schema/examples/ for monorepo development
  *
  * @param {Object} options - Parsed command options
  * @returns {string} Resolved absolute path to data directory
@@ -349,19 +357,25 @@ function resolveDataPath(options) {
     return resolve(process.env.PATHWAY_DATA);
   }
 
-  // 3. Current working directory ./data/
+  // 3. Home directory install (~/.fit/pathway/data/)
+  const homeData = join(homedir(), ".fit", "pathway", "data");
+  if (existsSync(homeData)) {
+    return homeData;
+  }
+
+  // 4. Current working directory ./data/
   const cwdData = join(process.cwd(), "data");
   if (existsSync(cwdData)) {
     return cwdData;
   }
 
-  // 4. Current working directory ./examples/
+  // 5. Current working directory ./examples/
   const cwdExamples = join(process.cwd(), "examples");
   if (existsSync(cwdExamples)) {
     return cwdExamples;
   }
 
-  // 5. Monorepo: apps/schema/examples/
+  // 6. Monorepo: apps/schema/examples/
   const schemaExamples = join(process.cwd(), "apps/schema/examples");
   if (existsSync(schemaExamples)) {
     return schemaExamples;
@@ -413,6 +427,12 @@ async function main() {
     process.exit(0);
   }
 
+  // Handle update command (re-downloads bundle for local install)
+  if (command === "update") {
+    await runUpdateCommand({ dataDir, options });
+    process.exit(0);
+  }
+
   const handler = COMMANDS[command];
 
   if (!handler) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forwardimpact/pathway",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "description": "Career progression web app and CLI for exploring roles and generating agents",
   "license": "Apache-2.0",
   "repository": {
@@ -40,8 +40,8 @@
     "./commands": "./src/commands/index.js"
   },
   "dependencies": {
-    "@forwardimpact/schema": "^0.5.0",
-    "@forwardimpact/model": "^0.6.0",
+    "@forwardimpact/schema": "^0.6.0",
+    "@forwardimpact/model": "^0.8.0",
     "mustache": "^4.2.0",
     "simple-icons": "^16.7.0",
     "yaml": "^2.3.4"

package/src/commands/build.js

@@ -3,11 +3,24 @@
  *
  * Generates a static site from the Engineering Pathway data.
  * Copies all necessary files (HTML, JS, CSS) and data to an output directory.
+ * Optionally generates a distribution bundle (bundle.tar.gz + install.sh)
+ * for local installs by individual engineers.
  */
 
-import { cp, mkdir, rm, access, realpath } from "fs/promises";
+import {
+  cp,
+  mkdir,
+  rm,
+  access,
+  realpath,
+  readFile,
+  writeFile,
+} from "fs/promises";
+import { readFileSync } from "fs";
 import { join, dirname, relative, resolve } from "path";
 import { fileURLToPath } from "url";
+import { execFileSync } from "child_process";
+import Mustache from "mustache";
 import { generateAllIndexes } from "@forwardimpact/schema/index-generator";
 import { loadFrameworkConfig } from "@forwardimpact/schema/loader";
 
@@ -151,14 +164,97 @@ ${framework.emojiIcon} Generating ${framework.title} static site...
     console.log(`   ✓ data/ (from ${relative(process.cwd(), dataDir)})`);
   }
 
+  // Generate distribution bundle if siteUrl is configured
+  const siteUrl = options.url || framework.distribution?.siteUrl;
+  if (siteUrl) {
+    await generateBundle({ outputDir, dataDir, siteUrl, framework });
+  }
+
   // Show summary
   console.log(`
 ✅ Site generated successfully!
 
 Output: ${outputDir}
-
+${siteUrl ? `\nDistribution:\n  ${outputDir}/bundle.tar.gz\n  ${outputDir}/install.sh\n` : ""}
 To serve locally:
   cd ${relative(process.cwd(), outputDir) || "."}
   npx serve .
 `);
 }
+
+/**
+ * Read the pathway package version from package.json
+ * @returns {string} Package version
+ */
+function getPathwayVersion() {
+  const pkgPath = join(appDir, "..", "package.json");
+  const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+  return pkg.version;
+}
+
+/**
+ * Generate distribution bundle (bundle.tar.gz + install.sh)
+ * @param {Object} params
+ * @param {string} params.outputDir - Build output directory
+ * @param {string} params.dataDir - Source data directory
+ * @param {string} params.siteUrl - Base URL for the published site
+ * @param {Object} params.framework - Framework configuration
+ */
+async function generateBundle({ outputDir, dataDir, siteUrl, framework }) {
+  console.log("📦 Generating distribution bundle...");
+
+  const version = getPathwayVersion();
+  const frameworkTitle = framework.title || "Engineering Pathway";
+
+  // 1. Create temporary bundle directory
+  const bundleDir = join(outputDir, "_bundle");
+  await mkdir(bundleDir, { recursive: true });
+
+  // 2. Generate minimal package.json for the bundle
+  const bundlePkg = {
+    name: "fit-pathway-local",
+    version: version,
+    private: true,
+    dependencies: {
+      "@forwardimpact/pathway": `^${version}`,
+    },
+  };
+  await writeFile(
+    join(bundleDir, "package.json"),
+    JSON.stringify(bundlePkg, null, 2) + "\n",
+  );
+  console.log(`   ✓ package.json (pathway ^${version})`);
+
+  // 3. Copy data files into bundle
+  await cp(dataDir, join(bundleDir, "data"), {
+    recursive: true,
+    dereference: true,
+  });
+  console.log("   ✓ data/");
+
+  // 4. Create tar.gz from the bundle directory
+  execFileSync("tar", [
+    "-czf",
+    join(outputDir, "bundle.tar.gz"),
+    "-C",
+    outputDir,
+    "_bundle",
+  ]);
+  console.log("   ✓ bundle.tar.gz");
+
+  // 5. Clean up temporary bundle directory
+  await rm(bundleDir, { recursive: true });
+
+  // 6. Render install.sh from template
+  const templatePath = join(appDir, "..", "templates", "install.template.sh");
+  const template = await readFile(templatePath, "utf8");
+  const installScript = Mustache.render(template, {
+    siteUrl: siteUrl.replace(/\/$/, ""),
+    version,
+    frameworkTitle,
+  });
+  await writeFile(join(outputDir, "install.sh"), installScript, {
+    mode: 0o755,
+  });
+  console.log("   ✓ install.sh");
+}

package/src/commands/index.js

@@ -19,3 +19,4 @@ export { runQuestionsCommand } from "./questions.js";
 export { runServeCommand } from "./serve.js";
 export { runInitCommand } from "./init.js";
 export { runSiteCommand } from "./site.js";
+export { runUpdateCommand } from "./update.js";

package/src/commands/interview.js

@@ -4,9 +4,9 @@
  * Generates and displays interview questions in the terminal.
  *
  * Usage:
- *   npx pathway interview <discipline> <grade>                    # Interview for trackless job
- *   npx pathway interview <discipline> <grade> --track=<track>    # Interview with track
- *   npx pathway interview <discipline> <grade> --track=<track> --type=short
+ *   npx fit-pathway interview <discipline> <grade>                                  # All interview types
+ *   npx fit-pathway interview <discipline> <grade> --track=<track>                  # With track
+ *   npx fit-pathway interview <discipline> <grade> --track=<track> --type=mission   # Single type
  */
 
 import { createCompositeCommand } from "./command-factory.js";
@@ -16,8 +16,10 @@ import {
 } from "../formatters/interview/shared.js";
 import { interviewToMarkdown } from "../formatters/interview/markdown.js";
 
+const VALID_TYPES = Object.keys(INTERVIEW_TYPES);
+
 /**
- * Format interview output
+ * Format a single interview type as markdown
  * @param {Object} view - Presenter view
  * @param {Object} options - Options including framework
  */
@@ -25,15 +27,31 @@ function formatInterview(view, options) {
   console.log(interviewToMarkdown(view, { framework: options.framework }));
 }
 
+/**
+ * Format all interview types as markdown with separators
+ * @param {Array<Object>} views - Array of presenter views
+ * @param {Object} options - Options including framework
+ */
+function formatAllInterviews(views, options) {
+  for (let i = 0; i < views.length; i++) {
+    if (i > 0) {
+      console.log("\n" + "─".repeat(80) + "\n");
+    }
+    console.log(
+      interviewToMarkdown(views[i], { framework: options.framework }),
+    );
+  }
+}
+
 export const runInterviewCommand = createCompositeCommand({
   commandName: "interview",
   requiredArgs: ["discipline_id", "grade_id"],
   findEntities: (data, args, options) => {
-    const interviewType = options.type || "full";
+    const interviewType = options.type === "full" ? null : options.type;
 
-    if (!INTERVIEW_TYPES[interviewType]) {
+    if (interviewType && !INTERVIEW_TYPES[interviewType]) {
       console.error(`Unknown interview type: ${interviewType}`);
-      console.error("Available types: full, short, behaviour");
+      console.error(`Available types: ${VALID_TYPES.join(", ")}`);
       process.exit(1);
     }
 
@@ -58,18 +76,38 @@ export const runInterviewCommand = createCompositeCommand({
     }
     return null;
   },
-  presenter: (entities, data, _options) =>
-    prepareInterviewDetail({
+  presenter: (entities, data, _options) => {
+    const params = {
       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 }),
+    };
+
+    // Single type: return one view
+    if (entities.interviewType) {
+      return prepareInterviewDetail({
+        ...params,
+        interviewType: entities.interviewType,
+      });
+    }
+
+    // All types: return array of views
+    return VALID_TYPES.map((type) =>
+      prepareInterviewDetail({ ...params, interviewType: type }),
+    ).filter(Boolean);
+  },
+  formatter: (view, options, data) => {
+    const opts = { ...options, framework: data.framework };
+
+    if (Array.isArray(view)) {
+      formatAllInterviews(view, opts);
+    } else {
+      formatInterview(view, opts);
+    }
+  },
   usageExample:
-    "npx pathway interview software_engineering L4 --track=platform --type=short",
+    "npx fit-pathway interview software_engineering J090 --track=platform --type=mission",
 });

package/src/commands/job.js

@@ -132,6 +132,7 @@ export async function runJobCommand({ data, args, options, dataDir }) {
     behaviours: data.behaviours,
     drivers: data.drivers,
     capabilities: data.capabilities,
+    stages: data.stages,
   });
 
   if (!view) {

package/src/commands/questions.js

@@ -56,12 +56,15 @@ function showQuestionsSummary(data) {
     "practitioner",
     "expert",
   ];
+  const roleTypes = ["professionalQuestions", "managementQuestions"];
   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;
+      const sq = questions.skillLevels?.[skill.id];
+      if (sq) {
+        for (const roleType of roleTypes) {
+          count += (sq[roleType]?.[level] || []).length;
+        }
       }
     }
     return [level, count];
@@ -81,9 +84,11 @@ function showQuestionsSummary(data) {
   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;
+      const bq = questions.behaviourMaturities?.[behaviour.id];
+      if (bq) {
+        for (const roleType of roleTypes) {
+          count += (bq[roleType]?.[maturity] || []).length;
+        }
       }
     }
     return [maturity.replace(/_/g, " "), count];
@@ -138,10 +143,8 @@ export async function runQuestionsCommand({
       behaviours: data.behaviours,
       filter,
     });
-    for (const section of view.sections) {
-      for (const q of section.questions) {
-        console.log(q.id);
-      }
+    for (const q of view.questions) {
+      console.log(q.id);
     }
     return;
   }

package/src/commands/stage.js

@@ -60,19 +60,19 @@ function formatDetail(viewAndContext, _framework) {
   console.log(formatHeader(`\n${emoji} ${view.name}\n`));
   console.log(`${view.description}\n`);
 
-  // Entry criteria
-  if (view.entryCriteria.length > 0) {
-    console.log(formatSubheader("Entry Criteria\n"));
-    for (const item of view.entryCriteria) {
+  // Read checklist
+  if (view.readChecklist.length > 0) {
+    console.log(formatSubheader("Read-Then-Do Checklist\n"));
+    for (const item of view.readChecklist) {
       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) {
+  // Confirm checklist
+  if (view.confirmChecklist.length > 0) {
+    console.log(formatSubheader("Do-Then-Confirm Checklist\n"));
+    for (const item of view.confirmChecklist) {
       console.log(formatBullet(item, 1));
     }
     console.log();

package/src/commands/update.js

@@ -0,0 +1,133 @@
+/**
+ * Update Command
+ *
+ * Re-downloads the distribution bundle from the published site URL
+ * and updates the local ~/.fit/pathway/ installation.
+ */
+
+import { cp, mkdir, rm, readFile, writeFile, access } from "fs/promises";
+import { join } from "path";
+import { homedir } from "os";
+import { execFileSync, execSync } from "child_process";
+import { loadFrameworkConfig } from "@forwardimpact/schema/loader";
+
+const INSTALL_DIR = join(homedir(), ".fit", "pathway");
+
+/**
+ * Run the update command.
+ * Reads siteUrl from the installed framework.yaml, re-downloads the bundle,
+ * extracts data, and runs npm install to update dependencies.
+ *
+ * @param {Object} params - Command parameters
+ * @param {string} params.dataDir - Path to data directory (may be the installed one)
+ * @param {Object} params.options - Command options
+ */
+export async function runUpdateCommand({ dataDir: _dataDir, options }) {
+  const installDataDir = join(INSTALL_DIR, "data");
+
+  // Verify we have a home-directory installation
+  try {
+    await access(installDataDir);
+  } catch {
+    console.error("Error: No local installation found at ~/.fit/pathway/");
+    console.error(
+      "Install first using the install.sh script from your organization's pathway site.",
+    );
+    process.exit(1);
+  }
+
+  // Load framework config to get siteUrl
+  const framework = await loadFrameworkConfig(installDataDir);
+  const siteUrl = options.url || framework.distribution?.siteUrl;
+
+  if (!siteUrl) {
+    console.error(
+      "Error: No siteUrl found in ~/.fit/pathway/data/framework.yaml (distribution.siteUrl)",
+    );
+    console.error("Provide one with --url=<URL> or add it to framework.yaml.");
+    process.exit(1);
+  }
+
+  const baseUrl = siteUrl.replace(/\/$/, "");
+  const bundleName = "bundle.tar.gz";
+
+  console.log(`\n🔄 Updating from ${baseUrl}...\n`);
+
+  // 1. Download bundle to temp location
+  const tmpDir = join(INSTALL_DIR, "_update_tmp");
+  await mkdir(tmpDir, { recursive: true });
+
+  const tmpBundle = join(tmpDir, bundleName);
+
+  try {
+    console.log("   Downloading bundle...");
+    execFileSync("curl", [
+      "-fsSL",
+      `${baseUrl}/${bundleName}`,
+      "-o",
+      tmpBundle,
+    ]);
+    console.log("   ✓ Downloaded");
+
+    // 2. Extract bundle
+    console.log("   Extracting...");
+    const extractDir = join(tmpDir, "extracted");
+    await mkdir(extractDir, { recursive: true });
+    execFileSync("tar", [
+      "-xzf",
+      tmpBundle,
+      "-C",
+      extractDir,
+      "--strip-components=1",
+    ]);
+    console.log("   ✓ Extracted");
+
+    // 3. Compare versions
+    const newPkgPath = join(extractDir, "package.json");
+    const oldPkgPath = join(INSTALL_DIR, "package.json");
+    const newPkg = JSON.parse(await readFile(newPkgPath, "utf8"));
+    let oldPkg;
+    try {
+      oldPkg = JSON.parse(await readFile(oldPkgPath, "utf8"));
+    } catch {
+      oldPkg = { version: "unknown", dependencies: {} };
+    }
+
+    const oldVersion =
+      oldPkg.dependencies?.["@forwardimpact/pathway"] || "unknown";
+    const newVersion =
+      newPkg.dependencies?.["@forwardimpact/pathway"] || "unknown";
+
+    // 4. Replace data
+    console.log("   Updating data files...");
+    await rm(installDataDir, { recursive: true });
+    await cp(join(extractDir, "data"), installDataDir, { recursive: true });
+    console.log("   ✓ Data updated");
+
+    // 5. Update package.json if version changed
+    if (oldVersion !== newVersion) {
+      console.log(`   Updating pathway ${oldVersion} → ${newVersion}...`);
+      await writeFile(oldPkgPath, JSON.stringify(newPkg, null, 2) + "\n");
+      console.log("   ✓ package.json updated");
+    }
+
+    // 6. Run npm install
+    console.log("   Installing dependencies...");
+    execSync("npm install --production --ignore-scripts --no-audit --no-fund", {
+      cwd: INSTALL_DIR,
+      stdio: "ignore",
+    });
+    console.log("   ✓ Dependencies installed");
+
+    // 7. Report
+    console.log(`
+✅ Update complete!
+
+  Pathway: ${oldVersion === newVersion ? newVersion + " (unchanged)" : oldVersion + " → " + newVersion}
+  Data:    updated from ${baseUrl}
+`);
+  } finally {
+    // Clean up temp directory
+    await rm(tmpDir, { recursive: true, force: true });
+  }
+}

package/src/components/command-prompt.js

@@ -0,0 +1,85 @@
+/**
+ * Command Prompt Component
+ *
+ * Reusable terminal-style command display with copy button.
+ * Shows a `$` prompt, monospace command text, and a copy-to-clipboard button.
+ */
+
+import { div, span, button } from "../lib/render.js";
+
+const SVG_NS = "http://www.w3.org/2000/svg";
+
+/**
+ * Create the copy icon SVG (two overlapping rectangles)
+ * @returns {SVGSVGElement}
+ */
+function createCopyIcon() {
+  const svg = document.createElementNS(SVG_NS, "svg");
+  svg.setAttribute("viewBox", "0 0 24 24");
+
+  const rect = document.createElementNS(SVG_NS, "rect");
+  rect.setAttribute("x", "9");
+  rect.setAttribute("y", "9");
+  rect.setAttribute("width", "13");
+  rect.setAttribute("height", "13");
+  rect.setAttribute("rx", "2");
+
+  const path = document.createElementNS(SVG_NS, "path");
+  path.setAttribute(
+    "d",
+    "M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1",
+  );
+
+  svg.appendChild(rect);
+  svg.appendChild(path);
+  return svg;
+}
+
+/**
+ * Copy text to clipboard with fallback for older browsers
+ * @param {string} text
+ * @param {HTMLButtonElement} btn
+ */
+async function copyToClipboard(text, btn) {
+  try {
+    await navigator.clipboard.writeText(text);
+  } catch {
+    const textarea = document.createElement("textarea");
+    textarea.value = text;
+    textarea.style.position = "fixed";
+    textarea.style.opacity = "0";
+    document.body.appendChild(textarea);
+    textarea.select();
+    document.execCommand("copy");
+    document.body.removeChild(textarea);
+  }
+
+  btn.classList.add("copied");
+  btn.setAttribute("aria-label", "Copied!");
+  setTimeout(() => {
+    btn.classList.remove("copied");
+    btn.setAttribute("aria-label", "Copy command");
+  }, 2000);
+}
+
+/**
+ * Create a command prompt element with copy button
+ * @param {string} command - The command text to display
+ * @returns {HTMLElement}
+ */
+export function createCommandPrompt(command) {
+  const copyBtn = button({
+    className: "command-prompt__copy",
+    "aria-label": "Copy command",
+    type: "button",
+  });
+  copyBtn.appendChild(createCopyIcon());
+  copyBtn.addEventListener("click", () => copyToClipboard(command, copyBtn));
+
+  return div(
+    { className: "command-prompt" },
+    span({ className: "command-prompt__prompt" }, "$"),
+    span({ className: "command-prompt__text" }, command),
+    copyBtn,
+  );
+}