@forwardimpact/pathway 0.25.20 → 0.25.22

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forwardimpact/pathway",
-  "version": "0.25.20",
+  "version": "0.25.22",
   "description": "Career progression web app and CLI for exploring roles and generating agent teams",
   "license": "Apache-2.0",
   "repository": {

package/src/commands/agent.js

@@ -32,11 +32,11 @@ import {
   deriveReferenceLevel,
   deriveAgentSkills,
   generateSkillMarkdown,
-  deriveToolkit,
   getDisciplineAbbreviation,
   toKebabCase,
   interpolateTeamInstructions,
-} from "@forwardimpact/libskill";
+} from "@forwardimpact/libskill/agent";
+import { deriveToolkit } from "@forwardimpact/libskill/toolkit";
 import { formatAgentProfile } from "../formatters/agent/profile.js";
 import { formatError, formatSuccess } from "../lib/cli-output.js";
 import { toolkitToPlainList } from "../formatters/toolkit/markdown.js";
@@ -94,7 +94,7 @@ function showAgentSummary(data, agentData, skillsWithAgent) {
  * @param {Object} agentData - Agent-specific data
  * @returns {Array<{discipline: Object, track: Object, humanDiscipline: Object, humanTrack: Object}>}
  */
-function findValidCombinations(data, agentData) {
+export function findValidCombinations(data, agentData) {
   const pairs = [];
   for (const discipline of agentData.disciplines) {
     for (const track of agentData.tracks) {
@@ -237,10 +237,10 @@ function resolveAgentEntities(data, agentData, disciplineId, trackId) {
  * @param {Object} humanDiscipline
  */
 function printTeamInstructions(agentTrack, humanDiscipline) {
-  const teamInstructions = interpolateTeamInstructions(
+  const teamInstructions = interpolateTeamInstructions({
     agentTrack,
     humanDiscipline,
-  );
+  });
   if (teamInstructions) {
     console.log("# Team Instructions (CLAUDE.md)\n");
     console.log(teamInstructions.trim());
@@ -287,10 +287,10 @@ async function handleSingleStage({
     return;
   }
 
-  const teamInstructions = interpolateTeamInstructions(
+  const teamInstructions = interpolateTeamInstructions({
     agentTrack,
     humanDiscipline,
-  );
+  });
   await writeTeamInstructions(teamInstructions, baseDir);
   await writeProfile(profile, baseDir, agentTemplate);
   await generateClaudeCodeSettings(baseDir, agentData.claudeCodeSettings);
@@ -331,7 +331,9 @@ async function handleAllStages({
   const skillFiles = derivedSkills
     .map((derived) => skillsWithAgent.find((s) => s.id === derived.skillId))
     .filter((skill) => skill?.agent)
-    .map((skill) => generateSkillMarkdown(skill, data.stages));
+    .map((skill) =>
+      generateSkillMarkdown({ skillData: skill, stages: data.stages }),
+    );
 
   for (const profile of profiles) {
     const errors = validateAgentProfile(profile);
@@ -373,10 +375,10 @@ async function handleAllStages({
     return;
   }
 
-  const teamInstructions = interpolateTeamInstructions(
+  const teamInstructions = interpolateTeamInstructions({
     agentTrack,
     humanDiscipline,
-  );
+  });
   await writeTeamInstructions(teamInstructions, baseDir);
   for (const profile of profiles) {
     await writeProfile(profile, baseDir, agentTemplate);

package/src/commands/build-bundle.js

@@ -0,0 +1,88 @@
+/**
+ * Bundle generation for Pathway distribution.
+ *
+ * Emits `bundle.tar.gz` and `install.sh` alongside the static site so
+ * engineers can install `@forwardimpact/pathway` globally via
+ * `curl -fsSL <site>/install.sh | bash`. Invoked from build.js when
+ * `framework.distribution.siteUrl` is configured.
+ */
+
+import { cp, mkdir, rm, readFile, writeFile } from "fs/promises";
+import { join } from "path";
+import { execFileSync } from "child_process";
+import Mustache from "mustache";
+
+/**
+ * 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
+ * @param {string} params.version - Pathway package version
+ * @param {string} params.templatesDir - Absolute path to pathway/templates
+ */
+export async function generateBundle({
+  outputDir,
+  dataDir,
+  siteUrl,
+  framework,
+  version,
+  templatesDir,
+}) {
+  console.log("📦 Generating distribution bundle...");
+
+  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(templatesDir, "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/build-packs.js

@@ -0,0 +1,392 @@
+/**
+ * Pack generation for Pathway distribution.
+ *
+ * Emits one pre-built agent/skill pack per valid discipline/track combination
+ * and two discovery manifests (`.well-known/agent-skills/index.json` for
+ * `npx skills` and `apm.yml` for Microsoft APM). See
+ * specs/320-pathway-ecosystem-distribution for context.
+ *
+ * Invoked from build.js after the distribution bundle has been generated.
+ */
+
+import { mkdir, rm, readFile, writeFile } from "fs/promises";
+import { join } from "path";
+import { execFileSync } from "child_process";
+import { createHash } from "crypto";
+
+import { createDataLoader } from "@forwardimpact/map/loader";
+import { createTemplateLoader } from "@forwardimpact/libtemplate";
+import {
+  generateStageAgentProfile,
+  deriveReferenceLevel,
+  deriveAgentSkills,
+  generateSkillMarkdown,
+  interpolateTeamInstructions,
+  getDisciplineAbbreviation,
+  toKebabCase,
+} from "@forwardimpact/libskill/agent";
+
+import { formatAgentProfile } from "../formatters/agent/profile.js";
+import {
+  formatAgentSkill,
+  formatInstallScript,
+  formatReference,
+} from "../formatters/agent/skill.js";
+import { findValidCombinations } from "./agent.js";
+
+/**
+ * Slugify a string for use as a package name.
+ * @param {string} text
+ * @returns {string}
+ */
+function slugify(text) {
+  return text
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+/**
+ * Stringify a JSON value with object keys sorted recursively.
+ * Produces deterministic output for digest stability.
+ * @param {unknown} value
+ * @returns {string}
+ */
+function stringifySorted(value) {
+  const seen = new WeakSet();
+  const sort = (v) => {
+    if (v === null || typeof v !== "object") return v;
+    if (seen.has(v)) throw new Error("Cannot stringify circular structure");
+    seen.add(v);
+    if (Array.isArray(v)) return v.map(sort);
+    const out = {};
+    for (const key of Object.keys(v).sort()) out[key] = sort(v[key]);
+    return out;
+  };
+  return JSON.stringify(sort(value), null, 2) + "\n";
+}
+
+/**
+ * Escape a YAML scalar double-quoted value.
+ * @param {string} text
+ * @returns {string}
+ */
+function yamlQuote(text) {
+  return `"${String(text).replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+
+/**
+ * Write a single pack's files to disk under the staging directory.
+ * Calls the formatters directly (silent, no console output).
+ * @param {Object} params
+ * @returns {Promise<void>}
+ */
+async function writePackFiles({
+  packDir,
+  profiles,
+  skillFiles,
+  teamInstructions,
+  agentTemplate,
+  skillTemplates,
+  claudeCodeSettings,
+}) {
+  const claudeDir = join(packDir, ".claude");
+  const agentsDir = join(claudeDir, "agents");
+  const skillsDir = join(claudeDir, "skills");
+
+  await mkdir(agentsDir, { recursive: true });
+  await mkdir(skillsDir, { recursive: true });
+
+  for (const profile of profiles) {
+    const profilePath = join(agentsDir, profile.filename);
+    await writeFile(
+      profilePath,
+      formatAgentProfile(profile, agentTemplate),
+      "utf-8",
+    );
+  }
+
+  for (const skill of skillFiles) {
+    const skillDir = join(skillsDir, skill.dirname);
+    await mkdir(skillDir, { recursive: true });
+
+    await writeFile(
+      join(skillDir, "SKILL.md"),
+      formatAgentSkill(skill, skillTemplates.skill),
+      "utf-8",
+    );
+
+    if (skill.installScript) {
+      const scriptsDir = join(skillDir, "scripts");
+      await mkdir(scriptsDir, { recursive: true });
+      await writeFile(
+        join(scriptsDir, "install.sh"),
+        formatInstallScript(skill, skillTemplates.install),
+        { mode: 0o755 },
+      );
+    }
+
+    if (skill.implementationReference) {
+      const refsDir = join(skillDir, "references");
+      await mkdir(refsDir, { recursive: true });
+      await writeFile(
+        join(refsDir, "REFERENCE.md"),
+        formatReference(skill, skillTemplates.reference),
+        "utf-8",
+      );
+    }
+  }
+
+  if (teamInstructions) {
+    await writeFile(
+      join(claudeDir, "CLAUDE.md"),
+      teamInstructions.trim() + "\n",
+      "utf-8",
+    );
+  }
+
+  // Claude Code settings — matches the CLI path's generateClaudeCodeSettings
+  // output format (no merge with existing files since the staging dir starts
+  // empty).
+  const settings = { ...(claudeCodeSettings || {}) };
+  await writeFile(
+    join(claudeDir, "settings.json"),
+    JSON.stringify(settings, null, 2) + "\n",
+    "utf-8",
+  );
+}
+
+/**
+ * Derive profiles, skills, and team instructions for a single combination.
+ * @param {Object} params
+ * @returns {{profiles: Array, skillFiles: Array, teamInstructions: string|null}}
+ */
+function derivePackContent({
+  discipline,
+  track,
+  humanDiscipline,
+  humanTrack,
+  data,
+  agentData,
+  skillsWithAgent,
+  level,
+}) {
+  const stageParams = {
+    discipline: humanDiscipline,
+    track: humanTrack,
+    level,
+    skills: skillsWithAgent,
+    behaviours: data.behaviours,
+    agentBehaviours: agentData.behaviours,
+    agentDiscipline: discipline,
+    agentTrack: track,
+    stages: data.stages,
+  };
+
+  const profiles = data.stages.map((stage) =>
+    generateStageAgentProfile({ ...stageParams, stage }),
+  );
+
+  const derivedSkills = deriveAgentSkills({
+    discipline: humanDiscipline,
+    track: humanTrack,
+    level,
+    skills: skillsWithAgent,
+  });
+
+  const skillFiles = derivedSkills
+    .map((derived) => skillsWithAgent.find((s) => s.id === derived.skillId))
+    .filter((skill) => skill?.agent)
+    .map((skill) =>
+      generateSkillMarkdown({ skillData: skill, stages: data.stages }),
+    );
+
+  const teamInstructions = interpolateTeamInstructions({
+    agentTrack: track,
+    humanDiscipline,
+  });
+
+  return { profiles, skillFiles, teamInstructions };
+}
+
+/**
+ * Archive a staged pack directory as a deterministic tar.gz and return its
+ * sha256 digest.
+ * @param {string} packDir - Staging directory containing the pack files
+ * @param {string} archivePath - Destination path for the tar.gz
+ * @returns {Promise<string>} sha256 digest string (e.g. "sha256:abc...")
+ */
+async function archivePack(packDir, archivePath) {
+  execFileSync("tar", [
+    "-czf",
+    archivePath,
+    "--sort=name",
+    "--mtime=1970-01-01",
+    "--owner=0",
+    "--group=0",
+    "--numeric-owner",
+    "-C",
+    packDir,
+    ".",
+  ]);
+
+  const bytes = await readFile(archivePath);
+  return "sha256:" + createHash("sha256").update(bytes).digest("hex");
+}
+
+/**
+ * Write the `npx skills` discovery manifest.
+ * @param {string} outputDir
+ * @param {Array<{name: string, description: string, url: string, digest: string}>} packs
+ * @param {string} version
+ */
+async function writeSkillsManifest(outputDir, packs, version) {
+  const wellKnownDir = join(outputDir, ".well-known", "agent-skills");
+  await mkdir(wellKnownDir, { recursive: true });
+  const manifest = {
+    $schema: "https://schemas.agentskills.io/discovery/0.2.0/schema.json",
+    skills: packs.map((pack) => ({
+      description: pack.description,
+      digest: pack.digest,
+      name: pack.name,
+      type: "archive",
+      url: pack.url,
+      version,
+    })),
+  };
+  await writeFile(
+    join(wellKnownDir, "index.json"),
+    stringifySorted(manifest),
+    "utf-8",
+  );
+}
+
+/**
+ * Write the Microsoft APM manifest at the site root.
+ * @param {string} outputDir
+ * @param {Array<{name: string, description: string, url: string, digest: string}>} packs
+ * @param {string} version
+ * @param {string} frameworkTitle
+ */
+async function writeApmManifest(outputDir, packs, version, frameworkTitle) {
+  const lines = [
+    `name: ${slugify(frameworkTitle)}`,
+    `version: ${version}`,
+    `description: ${yamlQuote(`${frameworkTitle} agent teams for Claude Code`)}`,
+    "",
+    "skills:",
+  ];
+  for (const pack of packs) {
+    lines.push(`  - name: ${pack.name}`);
+    lines.push(`    description: ${yamlQuote(pack.description)}`);
+    lines.push(`    version: ${version}`);
+    lines.push(`    url: ${yamlQuote(pack.url)}`);
+    lines.push(`    digest: ${yamlQuote(pack.digest)}`);
+  }
+  lines.push("");
+  await writeFile(join(outputDir, "apm.yml"), lines.join("\n"), "utf-8");
+}
+
+/**
+ * Generate pre-built agent/skill packs for installation through ecosystem
+ * tools like `npx skills` and Microsoft APM. One pack per valid
+ * discipline/track combination.
+ *
+ * @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
+ * @param {string} params.version - Pathway package version
+ * @param {string} params.templatesDir - Absolute path to pathway/templates
+ */
+export async function generatePacks({
+  outputDir,
+  dataDir,
+  siteUrl,
+  framework,
+  version,
+  templatesDir,
+}) {
+  console.log("📦 Generating agent/skill packs...");
+
+  const normalizedSiteUrl = siteUrl.replace(/\/$/, "");
+  const frameworkTitle = framework.title || "Engineering Pathway";
+
+  const loader = createDataLoader();
+  const templateLoader = createTemplateLoader(templatesDir);
+
+  const data = await loader.loadAllData(dataDir);
+  const agentData = await loader.loadAgentData(dataDir);
+  const skillsWithAgent = await loader.loadSkillsWithAgentData(dataDir);
+
+  const level = deriveReferenceLevel(data.levels);
+
+  const agentTemplate = templateLoader.load("agent.template.md", dataDir);
+  const skillTemplates = {
+    skill: templateLoader.load("skill.template.md", dataDir),
+    install: templateLoader.load("skill-install.template.sh", dataDir),
+    reference: templateLoader.load("skill-reference.template.md", dataDir),
+  };
+
+  const stagingDir = join(outputDir, "_packs");
+  const packsDir = join(outputDir, "packs");
+  await mkdir(stagingDir, { recursive: true });
+  await mkdir(packsDir, { recursive: true });
+
+  const combinations = findValidCombinations(data, agentData);
+  if (combinations.length === 0) {
+    console.log("   (no valid discipline/track combinations — skipping)");
+    await rm(stagingDir, { recursive: true, force: true });
+    return;
+  }
+
+  const packs = [];
+
+  for (const combination of combinations) {
+    const { discipline, track, humanDiscipline, humanTrack } = combination;
+    const abbrev = getDisciplineAbbreviation(discipline.id);
+    const agentName = `${abbrev}-${toKebabCase(track.id)}`;
+    const specName = humanDiscipline.specialization || humanDiscipline.name;
+    const description = `${specName} (${humanTrack.name}) — agent team`;
+
+    const { profiles, skillFiles, teamInstructions } = derivePackContent({
+      ...combination,
+      data,
+      agentData,
+      skillsWithAgent,
+      level,
+    });
+
+    const packDir = join(stagingDir, agentName);
+    await writePackFiles({
+      packDir,
+      profiles,
+      skillFiles,
+      teamInstructions,
+      agentTemplate,
+      skillTemplates,
+      claudeCodeSettings: agentData.claudeCodeSettings,
+    });
+
+    const archivePath = join(packsDir, `${agentName}.tar.gz`);
+    const digest = await archivePack(packDir, archivePath);
+
+    packs.push({
+      name: agentName,
+      description,
+      url: `${normalizedSiteUrl}/packs/${agentName}.tar.gz`,
+      digest,
+    });
+
+    console.log(`   ✓ packs/${agentName}.tar.gz`);
+  }
+
+  await rm(stagingDir, { recursive: true, force: true });
+
+  await writeSkillsManifest(outputDir, packs, version);
+  console.log("   ✓ .well-known/agent-skills/index.json");
+
+  await writeApmManifest(outputDir, packs, version, frameworkTitle);
+  console.log("   ✓ apm.yml");
+}

package/src/commands/build.js

@@ -3,26 +3,20 @@
  *
  * 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.
+ * Optionally delegates to build-bundle and build-packs to produce the
+ * distribution surfaces (bundle.tar.gz + install.sh for the curl|bash flow,
+ * and agent/skill packs for ecosystem tools like `npx skills` and APM) when
+ * `framework.distribution.siteUrl` is configured.
  */
 
-import {
-  cp,
-  mkdir,
-  rm,
-  access,
-  realpath,
-  readFile,
-  writeFile,
-} from "fs/promises";
+import { cp, mkdir, rm, access, realpath, 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 { createIndexGenerator } from "@forwardimpact/map/index-generator";
 import { createDataLoader } from "@forwardimpact/map/loader";
+import { generateBundle } from "./build-bundle.js";
+import { generatePacks } from "./build-packs.js";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -201,10 +195,26 @@ ${framework.emojiIcon} Generating ${framework.title} static site...
   );
   console.log(`   ✓ version.json (${version})`);
 
-  // Generate distribution bundle if siteUrl is configured
+  // Generate distribution surfaces if siteUrl is configured
   const siteUrl = options.url || framework.distribution?.siteUrl;
   if (siteUrl) {
-    await generateBundle({ outputDir, dataDir, siteUrl, framework });
+    const templatesDir = join(appDir, "..", "templates");
+    await generateBundle({
+      outputDir,
+      dataDir,
+      siteUrl,
+      framework,
+      version,
+      templatesDir,
+    });
+    await generatePacks({
+      outputDir,
+      dataDir,
+      siteUrl,
+      framework,
+      version,
+      templatesDir,
+    });
   }
 
   // Show summary
@@ -212,7 +222,7 @@ ${framework.emojiIcon} Generating ${framework.title} static site...
 ✅ Site generated successfully!
 
 Output: ${outputDir}
-${siteUrl ? `\nDistribution:\n  ${outputDir}/bundle.tar.gz\n  ${outputDir}/install.sh\n` : ""}
+${siteUrl ? `\nDistribution:\n  ${outputDir}/bundle.tar.gz\n  ${outputDir}/install.sh\n  ${outputDir}/packs/ (agent/skill packs)\n  ${outputDir}/.well-known/agent-skills/index.json\n  ${outputDir}/apm.yml\n` : ""}
 To serve locally:
   cd ${relative(process.cwd(), outputDir) || "."}
   bunx serve .
@@ -228,70 +238,3 @@ function getPathwayVersion() {
   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");
-}