@forwardimpact/pathway 0.13.0 → 0.14.0

package/bin/fit-pathway.js

@@ -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
@@ -253,6 +256,7 @@ function parseArgs(args) {
     path: null,
     // Site command options
     clean: true,
+    url: null,
   };
 
   for (const arg of args) {
@@ -308,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;
@@ -332,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
@@ -350,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;
@@ -414,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.13.0",
+  "version": "0.14.0",
   "description": "Career progression web app and CLI for exploring roles and generating agents",
   "license": "Apache-2.0",
   "repository": {
@@ -41,7 +41,7 @@
   },
   "dependencies": {
     "@forwardimpact/schema": "^0.6.0",
-    "@forwardimpact/model": "^0.7.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/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/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,
+  );
+}

package/src/components/nav.js

@@ -5,11 +5,11 @@
 import { div, a } from "../lib/render.js";
 
 /**
- * Update the active navigation link
+ * Update the active navigation link in the drawer
  * @param {string} path - Current path
  */
 export function updateActiveNav(path) {
-  const links = document.querySelectorAll("#nav-links a");
+  const links = document.querySelectorAll("#drawer-nav a");
   links.forEach((link) => {
     const href = link.getAttribute("href").slice(1); // Remove #
     const isActive = path === href || (href !== "/" && path.startsWith(href));

package/src/components/top-bar.js

@@ -0,0 +1,97 @@
+/**
+ * Top Bar Component
+ *
+ * Fixed bar across the top of the app with:
+ * - Sidebar toggle button (left)
+ * - CLI command display with copy button (center)
+ *
+ * Similar to Safari's URL bar with sidebar toggle.
+ */
+
+import { getCliCommand } from "../lib/cli-command.js";
+
+/** @type {HTMLElement|null} */
+let commandDisplay = null;
+
+/** @type {HTMLButtonElement|null} */
+let copyButton = null;
+
+/**
+ * Set up the top bar: wire toggle and initial command display.
+ * Call after DOM is ready.
+ */
+export function setupTopBar() {
+  const app = document.getElementById("app");
+  const toggle = document.getElementById("sidebar-toggle");
+  const commandEl = document.getElementById("cli-command");
+  const copyBtn = document.getElementById("cli-copy");
+
+  commandDisplay = commandEl;
+  copyButton = copyBtn;
+
+  if (toggle) {
+    toggle.addEventListener("click", () => {
+      app.classList.toggle("drawer-open");
+    });
+  }
+
+  if (copyBtn) {
+    copyBtn.addEventListener("click", handleCopy);
+  }
+
+  // Intercept history.replaceState so CLI command updates when pages
+  // change the hash without triggering hashchange (e.g. agent builder)
+  const originalReplaceState = history.replaceState.bind(history);
+  history.replaceState = (...args) => {
+    originalReplaceState(...args);
+    updateCommand();
+  };
+
+  // Set initial command
+  updateCommand();
+}
+
+/**
+ * Update the CLI command display for the current route.
+ * Call on every route change.
+ */
+export function updateCommand() {
+  if (!commandDisplay) return;
+  const path = window.location.hash.slice(1) || "/";
+  commandDisplay.textContent = getCliCommand(path);
+  // Reset copy button state
+  if (copyButton) {
+    copyButton.setAttribute("aria-label", "Copy command");
+    copyButton.classList.remove("copied");
+  }
+}
+
+/**
+ * Copy the current CLI command to clipboard
+ */
+async function handleCopy() {
+  if (!commandDisplay || !copyButton) return;
+  const text = commandDisplay.textContent;
+
+  try {
+    await navigator.clipboard.writeText(text);
+    copyButton.classList.add("copied");
+    copyButton.setAttribute("aria-label", "Copied!");
+    setTimeout(() => {
+      copyButton.classList.remove("copied");
+      copyButton.setAttribute("aria-label", "Copy command");
+    }, 2000);
+  } catch {
+    // Fallback for older browsers
+    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);
+    copyButton.classList.add("copied");
+    setTimeout(() => copyButton.classList.remove("copied"), 2000);
+  }
+}

package/src/css/bundles/app.css

@@ -24,6 +24,8 @@
 @import "../components/progress.css" layer(components);
 @import "../components/states.css" layer(components);
 @import "../components/nav.css" layer(components);
+@import "../components/top-bar.css" layer(components);
+@import "../components/command-prompt.css" layer(components);
 
 /* Utilities */
 @import "../components/utilities.css" layer(utilities);