@kungfu-tech/buildchain 2.8.7-alpha.1 → 2.8.7

package/scripts/check-inventory.mjs

@@ -38,6 +38,7 @@ const requiredPaths = [
   "scripts/release-candidate-resolver.mjs",
   "scripts/buildchain-patrol.mjs",
   "scripts/workflow-friction-report.mjs",
+  "scripts/web-surface-production-release-pr.mjs",
   "docs/migration-inventory.md",
   "docs/lifecycle-protocol.md",
   "docs/ownership.md",
@@ -79,6 +80,22 @@ if (rootPackage.name !== "@kungfu-tech/buildchain") {
 if (rootPackage.private !== false) {
   throw new Error("root package must be publishable with private=false");
 }
+const packageDependencySections = ["dependencies", "optionalDependencies", "peerDependencies"];
+const exoticDependencyPattern =
+  /^(?:git(?:\+ssh|\+https|\+http|\+file)?:|github:|gitlab:|bitbucket:|https?:|file:|link:|workspace:)/i;
+for (const sectionName of packageDependencySections) {
+  const section = rootPackage[sectionName] || {};
+  for (const [dependencyName, specifier] of Object.entries(section)) {
+    if (typeof specifier !== "string") {
+      throw new Error(`package ${sectionName}.${dependencyName} must use a string version specifier`);
+    }
+    if (exoticDependencyPattern.test(specifier.trim())) {
+      throw new Error(
+        `package ${sectionName}.${dependencyName} must use an auditable npm registry version, not exotic specifier: ${specifier}`,
+      );
+    }
+  }
+}
 if (rootPackage.bin?.buildchain !== "./bin/buildchain.mjs") {
   throw new Error("root package must expose the buildchain CLI");
 }
@@ -109,6 +126,15 @@ if (rootPackage.exports?.["./release-propagation"] !== "./packages/core/release-
 if (rootPackage.exports?.["./buildchain-kfd-claims"] !== "./packages/core/buildchain-kfd-claims.js") {
   throw new Error("root package must export @kungfu-tech/buildchain/buildchain-kfd-claims");
 }
+if (rootPackage.exports?.["./site/buildchain-site.json"] !== "./dist/site/buildchain-site.json") {
+  throw new Error("root package must export @kungfu-tech/buildchain/site/buildchain-site.json");
+}
+if (rootPackage.exports?.["./site/site-manifest.json"] !== "./dist/site/site-manifest.json") {
+  throw new Error("root package must export @kungfu-tech/buildchain/site/site-manifest.json");
+}
+if (rootPackage.exports?.["./site/page-registry.json"] !== "./dist/site/page-registry.json") {
+  throw new Error("root package must export @kungfu-tech/buildchain/site/page-registry.json");
+}
 if (rootPackage.exports?.["./site/manual-registry.json"] !== "./dist/site/manual-registry.json") {
   throw new Error("root package must export @kungfu-tech/buildchain/site/manual-registry.json");
 }
@@ -124,25 +150,25 @@ if (rootPackage.publishConfig?.access !== "public") {
 if (rootPackage.publishConfig?.registry !== "https://registry.npmjs.org/") {
   throw new Error("root package publishConfig.registry must be npmjs");
 }
-for (const expectedFile of ["bin/", "scripts/*.mjs", "packages/core/", "docs/MAP.md", "docs/cli.md"]) {
+for (const expectedFile of ["bin/", "scripts/*.mjs", "packages/core/", "docs/*.md"]) {
   if (!rootPackage.files?.includes(expectedFile)) {
     throw new Error(`root package files must include ${expectedFile}`);
   }
 }
-for (const expectedFile of ["dist/site/", "docs/install.md", "docs/binary-distribution.md", "docs/site-bundle-contract.md"]) {
+for (const expectedFile of ["dist/site/", "actions/*/README.md", "fixtures/*/README.md"]) {
   if (!rootPackage.files?.includes(expectedFile)) {
     throw new Error(`root package files must include ${expectedFile}`);
   }
 }
-if (!rootPackage.files?.includes("docs/release-propagation.md")) {
-  throw new Error("root package files must include docs/release-propagation.md");
-}
 const cliSource = fs.readFileSync(path.join(root, "bin/buildchain.mjs"), "utf8");
 const coreIndexSource = fs.readFileSync(path.join(root, "packages/core/index.js"), "utf8");
 const versioningDoc = fs.readFileSync(path.join(root, "docs/versioning.md"), "utf8");
 const cliDoc = fs.readFileSync(path.join(root, "docs/cli.md"), "utf8");
 const docsMap = fs.readFileSync(path.join(root, "docs/MAP.md"), "utf8");
 const installDoc = fs.readFileSync(path.join(root, "docs/install.md"), "utf8");
+const siteBundle = JSON.parse(fs.readFileSync(path.join(root, "dist/site/buildchain-site.json"), "utf8"));
+const siteManifest = JSON.parse(fs.readFileSync(path.join(root, "dist/site/site-manifest.json"), "utf8"));
+const pageRegistry = JSON.parse(fs.readFileSync(path.join(root, "dist/site/page-registry.json"), "utf8"));
 if (!cliSource.startsWith("#!/usr/bin/env node")) {
   throw new Error("bin/buildchain.mjs must be executable with a node shebang");
 }
@@ -167,6 +193,89 @@ if (!coreIndexSource.includes("KFD2_RELEASE_TRUST_PASSPORT_CONTRACT")) {
 if (!coreIndexSource.includes("KFD2_TRUST_PROOF_CONTRACT")) {
   throw new Error("packages/core/index.js must export KFD-2 trust proof contract");
 }
+if (siteBundle.contract !== "kungfu-buildchain-site-bundle") {
+  throw new Error("buildchain-site.json must expose the Buildchain site bundle contract");
+}
+if (siteBundle.source?.homepageTextSource !== "README.md") {
+  throw new Error("buildchain-site.json source.homepageTextSource must be README.md");
+}
+if (siteManifest.source?.homepageTextSource !== "README.md") {
+  throw new Error("site-manifest.json source.homepageTextSource must be README.md");
+}
+if (siteBundle.homepage?.title !== "Buildchain") {
+  throw new Error("buildchain-site.json homepage.title must match README H1");
+}
+if (!Array.isArray(siteBundle.homepage?.sections) || siteBundle.homepage.sections.length < 5) {
+  throw new Error("buildchain-site.json homepage.sections must expose README-derived sections");
+}
+for (const requiredSection of ["install-and-verify", "use-buildchain", "release-model", "toolkit-observability", "site-fact-source"]) {
+  if (!siteBundle.homepage.sections.some((entry) => entry.id === requiredSection && entry.sourcePath === "README.md" && entry.markdown)) {
+    throw new Error(`buildchain-site.json homepage.sections must include README projection ${requiredSection}`);
+  }
+}
+if (siteBundle.homepage.sections.some((entry) => entry.id === "homepage-content-contract")) {
+  throw new Error("buildchain-site.json homepage.sections must not render the renderer contract as homepage content");
+}
+if (
+  siteBundle.homepage?.rendererContract?.id !== "homepage-content-contract" ||
+  siteBundle.homepage?.rendererContract?.renderAsHomepageContent !== false ||
+  !siteBundle.homepage?.rendererContract?.markdown
+) {
+  throw new Error("buildchain-site.json homepage.rendererContract must expose README renderer contract outside homepage.sections");
+}
+if (!siteBundle.homepage?.displayPlan?.firstScreen?.include?.includes("install-and-verify")) {
+  throw new Error("buildchain-site.json homepage.displayPlan firstScreen must include install-and-verify");
+}
+if (!Array.isArray(siteBundle.renderingBoundary?.ownedByBuildchain) || !siteBundle.renderingBoundary.ownedByBuildchain.includes("homepage section projection from README.md")) {
+  throw new Error("buildchain-site.json renderingBoundary.ownedByBuildchain must include README projection ownership");
+}
+if (!Array.isArray(siteBundle.renderingBoundary?.ownedBySite) || !siteBundle.renderingBoundary.ownedBySite.includes("markdown-to-HTML renderer")) {
+  throw new Error("buildchain-site.json renderingBoundary.ownedBySite must include markdown-to-HTML renderer");
+}
+if (pageRegistry.contract !== "kungfu-buildchain-site-page-registry") {
+  throw new Error("page-registry.json must expose the site page registry contract");
+}
+if (siteBundle.pageRegistry?.path !== "page-registry.json" || siteBundle.pageRegistry?.pageCount !== pageRegistry.pageCount) {
+  throw new Error("buildchain-site.json must link to page-registry.json with matching page count");
+}
+if (!siteManifest.facts?.includes("page-registry.json") || !siteBundle.entrypoints?.includes("page-registry.json")) {
+  throw new Error("site bundle entrypoints must include page-registry.json");
+}
+function immediateReadmes(dir) {
+  const absoluteDir = path.join(root, dir);
+  if (!fs.existsSync(absoluteDir)) return [];
+  return fs.readdirSync(absoluteDir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => `${dir}/${entry.name}/README.md`)
+    .filter((relPath) => fs.existsSync(path.join(root, relPath)))
+    .sort();
+}
+const expectedPageSources = [
+  "README.md",
+  ...fs.readdirSync(path.join(root, "docs")).filter((name) => name.endsWith(".md")).sort().map((name) => `docs/${name}`),
+  ...immediateReadmes("actions"),
+  "packages/core/README.md",
+  ...immediateReadmes("fixtures"),
+].sort();
+const registryPageSources = [...new Set((pageRegistry.pages || []).map((page) => page.sourcePath))].sort();
+const bundlePageSources = [...new Set((siteBundle.pages || []).map((page) => page.sourcePath))].sort();
+if (JSON.stringify(registryPageSources) !== JSON.stringify(expectedPageSources)) {
+  throw new Error(`page-registry.json must include every public markdown page: expected ${expectedPageSources.length}, got ${registryPageSources.length}`);
+}
+if (JSON.stringify(bundlePageSources) !== JSON.stringify(expectedPageSources)) {
+  throw new Error(`buildchain-site.json pages must include every public markdown page: expected ${expectedPageSources.length}, got ${bundlePageSources.length}`);
+}
+for (const page of pageRegistry.pages || []) {
+  if (!page.id || !page.route || !page.title || !page.category || !page.sourcePath || !page.digest || !page.markdown) {
+    throw new Error(`page-registry.json page is incomplete: ${page.sourcePath || page.id || "<unknown>"}`);
+  }
+}
+if (!pageRegistry.pages?.some((page) => page.sourcePath === "actions/promote-buildchain-ref/README.md")) {
+  throw new Error("page-registry.json must include action manuals");
+}
+if (!pageRegistry.pages?.some((page) => page.sourcePath === "packages/core/README.md" && page.category === "api")) {
+  throw new Error("page-registry.json must include Node API overview");
+}
 for (const requiredSnippet of [
   "createBuildchainKfdClaimRegistry",
   "createBuildchainKfd1Witness",

package/scripts/generate-site-bundle.mjs

@@ -10,11 +10,16 @@ import {
 } from "../packages/core/buildchain-kfd-claims.js";
 
 const SITE_BUNDLE_CONTRACT = "kungfu-buildchain-site-bundle";
+const README_PATH = "README.md";
 const root = path.resolve(import.meta.dirname, "..");
 const outputDir = path.join(root, "dist", "site");
 
+function readText(rel) {
+  return fs.readFileSync(path.join(root, rel), "utf8");
+}
+
 function readJson(rel) {
-  return JSON.parse(fs.readFileSync(path.join(root, rel), "utf8"));
+  return JSON.parse(readText(rel));
 }
 
 function writeJson(filePath, value) {
@@ -37,6 +42,72 @@ function existingJson(filePath) {
   return fs.existsSync(filePath) ? fs.readFileSync(filePath, "utf8") : "";
 }
 
+function normalizeMarkdown(value) {
+  return String(value || "").replace(/\r\n/g, "\n").trim();
+}
+
+function paragraphBlocks(markdown) {
+  return normalizeMarkdown(markdown)
+    .split(/\n{2,}/)
+    .map((block) => block.replace(/\n/g, " ").trim())
+    .filter(Boolean);
+}
+
+function parseReadme(markdown) {
+  const content = normalizeMarkdown(markdown);
+  const titleMatch = content.match(/^#\s+(.+)$/m);
+  if (!titleMatch) {
+    throw new Error(`${README_PATH} must start with an H1 title`);
+  }
+
+  const headingPattern = /^##\s+(.+)$/gm;
+  const headings = [];
+  let match;
+  while ((match = headingPattern.exec(content))) {
+    headings.push({
+      title: match[1].trim(),
+      index: match.index,
+      bodyStart: headingPattern.lastIndex,
+    });
+  }
+
+  const sections = {};
+  for (let index = 0; index < headings.length; index += 1) {
+    const current = headings[index];
+    const next = headings[index + 1];
+    sections[current.title] = content.slice(current.bodyStart, next ? next.index : content.length).trim();
+  }
+
+  const intro = content.slice(titleMatch[0].length, headings[0]?.index ?? content.length).trim();
+  return {
+    title: titleMatch[1].trim(),
+    intro,
+    sections,
+  };
+}
+
+function readmeSection(readme, heading) {
+  const body = readme.sections[heading];
+  if (!body) {
+    throw new Error(`${README_PATH} missing required section: ${heading}`);
+  }
+  return body;
+}
+
+function homepageSection({ readme, id, heading, title = heading, role, priority, presentation, firstScreen = false }) {
+  return {
+    id,
+    sourcePath: README_PATH,
+    sourceHeading: heading,
+    title,
+    renderRole: role,
+    homepagePriority: priority,
+    defaultPresentation: presentation,
+    includeInFirstScreen: firstScreen,
+    markdown: normalizeMarkdown(readmeSection(readme, heading)),
+  };
+}
+
 function docEntry(id, title, pathName, plane) {
   return {
     id,
@@ -48,10 +119,102 @@ function docEntry(id, title, pathName, plane) {
   };
 }
 
+function slugify(value) {
+  return String(value || "")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "") || "page";
+}
+
+function markdownTitle(markdown, fallback) {
+  const match = normalizeMarkdown(markdown).match(/^#\s+(.+)$/m);
+  return match ? match[1].trim() : fallback;
+}
+
+function markdownHeadings(markdown) {
+  const headings = [];
+  const pattern = /^(#{1,4})\s+(.+)$/gm;
+  let match;
+  while ((match = pattern.exec(normalizeMarkdown(markdown)))) {
+    headings.push({
+      level: match[1].length,
+      title: match[2].trim(),
+      anchor: slugify(match[2]),
+    });
+  }
+  return headings;
+}
+
+function listMarkdownFiles(dir) {
+  const absoluteDir = path.join(root, dir);
+  if (!fs.existsSync(absoluteDir)) return [];
+  return fs.readdirSync(absoluteDir)
+    .filter((name) => name.endsWith(".md"))
+    .sort()
+    .map((name) => `${dir}/${name}`);
+}
+
+function immediateReadmes(dir) {
+  const absoluteDir = path.join(root, dir);
+  if (!fs.existsSync(absoluteDir)) return [];
+  return fs.readdirSync(absoluteDir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => `${dir}/${entry.name}/README.md`)
+    .filter((relPath) => fs.existsSync(path.join(root, relPath)))
+    .sort();
+}
+
+function sitePage(relPath, category, routePrefix, extra = {}) {
+  const markdown = normalizeMarkdown(readText(relPath));
+  const baseName = path.basename(relPath, path.extname(relPath));
+  const parentName = path.basename(path.dirname(relPath));
+  const slug = extra.slug || (baseName.toLowerCase() === "readme" ? slugify(parentName) : slugify(baseName));
+  const route = extra.route || `${routePrefix}/${slug}`;
+  const title = markdownTitle(markdown, extra.title || slug);
+  return {
+    id: extra.id || `${category}:${slug}`,
+    title,
+    route,
+    category,
+    sourcePath: relPath,
+    digest: sha256File(relPath),
+    headings: markdownHeadings(markdown),
+    markdown,
+    ...extra,
+  };
+}
+
+function buildSitePages() {
+  const docsPages = listMarkdownFiles("docs").map((relPath) => sitePage(relPath, "manual", "/docs"));
+  const actionPages = immediateReadmes("actions").map((relPath) => sitePage(relPath, "action", "/actions"));
+  const fixturePages = immediateReadmes("fixtures").map((relPath) => sitePage(relPath, "fixture", "/fixtures"));
+  const apiPages = [
+    sitePage("packages/core/README.md", "api", "/api", {
+      id: "api:node-package",
+      slug: "node-package",
+      route: "/api/node-package",
+    }),
+  ];
+  return [
+    sitePage(README_PATH, "overview", "/", {
+      id: "overview:home",
+      slug: "home",
+      route: "/",
+      title: "Buildchain",
+    }),
+    ...docsPages,
+    ...actionPages,
+    ...apiPages,
+    ...fixturePages,
+  ].sort((a, b) => a.route.localeCompare(b.route));
+}
+
 function buildSiteBundle() {
   const packageJson = readJson("package.json");
   const inventory = readJson("tests/buildchain-inventory.json");
+  const readme = parseReadme(readText(README_PATH));
   const docs = BUILDCHAIN_AGENT_MANUALS.map((manual) => docEntry(manual.id, manual.title, manual.path, manual.plane));
+  const pages = buildSitePages();
 
   const cliRegistry = {
     schemaVersion: 1,
@@ -98,10 +261,29 @@ function buildSiteBundle() {
       "docs/release-passport.md",
       "docs/publish-transaction.md",
       "docs/site-bundle-contract.md",
+      "docs/runtime-train-validation.md",
+      "docs/consumer-issue-reporting.md",
+      "docs/ownership.md",
+      "docs/migration-inventory.md",
     ],
     guidance: "Agent consumers should use this registry to find packaged Buildchain manuals before inferring behavior from workflow snippets or release notes.",
   };
 
+  const pageRegistry = {
+    schemaVersion: 1,
+    contract: "kungfu-buildchain-site-page-registry",
+    package: packageJson.name,
+    sourceOfTruth: "npm package @kungfu-tech/buildchain/dist/site/page-registry.json",
+    rendererBoundary: {
+      contentOwner: "Buildchain",
+      rendererOwner: "site repository",
+      rule: "Site repositories render these markdown pages and metadata; they do not maintain separate Buildchain product copy.",
+    },
+    pageCount: pages.length,
+    categories: [...new Set(pages.map((page) => page.category))].sort(),
+    pages,
+  };
+
   const nodeApiRegistry = {
     schemaVersion: 1,
     contract: "kungfu-buildchain-node-api-registry",
@@ -137,6 +319,7 @@ function buildSiteBundle() {
       { id: "validate-config", path: "actions/validate-config", status: "active" },
       { id: "run-lifecycle", path: "actions/run-lifecycle", status: "active" },
       { id: "promote-buildchain-ref", path: "actions/promote-buildchain-ref", status: "active" },
+      { id: "report-buildchain-issue", path: "actions/report-buildchain-issue", status: "active" },
     ],
   };
 
@@ -196,6 +379,7 @@ function buildSiteBundle() {
     site: [
       "buildchain-site.json",
       "site-manifest.json",
+      "page-registry.json",
       "cli-registry.json",
       "manual-registry.json",
       "node-api-registry.json",
@@ -264,8 +448,14 @@ function buildSiteBundle() {
       versionSource: "package.json#version",
     },
     entrypoint: "buildchain-site.json",
+    source: {
+      homepageTextSource: README_PATH,
+      docsMap: "docs/MAP.md",
+      siteFactsDir: "dist/site",
+    },
     docs,
     facts: [
+      "page-registry.json",
       "cli-registry.json",
       "manual-registry.json",
       "node-api-registry.json",
@@ -284,6 +474,7 @@ function buildSiteBundle() {
     contract: "kungfu-buildchain-site-agent-index",
     readOrder: [
       "site-manifest.json",
+      "page-registry.json",
       "product-mechanism.json",
       "release-model.json",
       "cli-registry.json",
@@ -297,22 +488,141 @@ function buildSiteBundle() {
     instruction: "Use this bundle as the package-owned fact source for Buildchain pages. Do not infer current release mechanics from prose alone.",
   };
 
+  const homepageSections = [
+    homepageSection({
+      readme,
+      id: "install-and-verify",
+      heading: "Install and Verify",
+      role: "primary",
+      priority: 10,
+      presentation: "release-passport-install",
+      firstScreen: true,
+    }),
+    homepageSection({
+      readme,
+      id: "use-buildchain",
+      heading: "Use Buildchain",
+      role: "primary",
+      priority: 20,
+      presentation: "workflow-surface-list",
+      firstScreen: true,
+    }),
+    homepageSection({
+      readme,
+      id: "release-model",
+      heading: "Release Model",
+      role: "primary",
+      priority: 30,
+      presentation: "release-model-table",
+    }),
+    homepageSection({
+      readme,
+      id: "toolkit-observability",
+      heading: "Toolkit Observability",
+      role: "support",
+      priority: 40,
+      presentation: "toolkit-example",
+    }),
+    homepageSection({
+      readme,
+      id: "site-fact-source",
+      heading: "Site Fact Source",
+      role: "support",
+      priority: 50,
+      presentation: "site-fact-source",
+    }),
+  ];
+
+  const rendererContract = {
+    ...homepageSection({
+      readme,
+      id: "homepage-content-contract",
+      heading: "Homepage Content Contract",
+      role: "renderer-contract",
+      priority: 90,
+      presentation: "developer-note",
+    }),
+    renderAsHomepageContent: false,
+    note: "This is a machine/renderer contract for site implementers. It should not be rendered as ordinary homepage content.",
+  };
+
   const siteBundle = {
     schemaVersion: 1,
     contract: SITE_BUNDLE_CONTRACT,
     product: siteManifest.product,
     package: siteManifest.package,
+    source: {
+      package: packageJson.name,
+      homepageTextSource: README_PATH,
+      docsMap: "docs/MAP.md",
+      manualRegistry: "manual-registry.json",
+      siteFactsDir: "dist/site",
+    },
+    routes: {
+      home: "/",
+      docsPattern: "/docs/{id}",
+      llms: "/llms.txt",
+      manifest: "/manifest.json",
+    },
     sourceOfTruth: "npm package @kungfu-tech/buildchain/dist/site",
     humanFirst: true,
     agentFirst: true,
     entrypoints: siteManifest.facts.concat(["site-manifest.json"]),
+    pages,
+    pageRegistry: {
+      path: "page-registry.json",
+      contract: pageRegistry.contract,
+      pageCount: pageRegistry.pageCount,
+      categories: pageRegistry.categories,
+    },
+    homepage: {
+      title: readme.title,
+      lead: paragraphBlocks(readme.intro)[0] || "",
+      mechanismSummary: paragraphBlocks(readme.intro).slice(1),
+      sections: homepageSections,
+      displayPlan: {
+        firstScreen: {
+          include: ["title", "lead", "install-and-verify", "use-buildchain"],
+          maxPrimarySections: 2,
+          note: "The first viewport should establish Buildchain identity, release-passport trust, and the primary reusable workflow entrypoint without rendering implementation notes.",
+        },
+        primary: ["install-and-verify", "use-buildchain", "release-model"],
+        support: ["toolkit-observability", "site-fact-source"],
+        rendererContract: ["homepage-content-contract"],
+      },
+      rendererContract,
+    },
     docs,
     releaseModel,
+    renderingBoundary: {
+      ownedByBuildchain: [
+        "homepage title and text",
+        "homepage section projection from README.md",
+        "complete markdown page registry for Buildchain public docs, action manuals, Node API overview, and fixtures",
+        "release model facts",
+        "workflow and action registries",
+        "CLI command registry",
+        "manual and Node API registries",
+        "KFD claim registry",
+        "release-passport evidence vocabulary",
+      ],
+      ownedBySite: [
+        "HTML structure",
+        "CSS",
+        "responsive layout",
+        "navigation layout",
+        "visual assets",
+        "decorative images",
+        "markdown-to-HTML renderer",
+        "section presentation and progressive disclosure within Buildchain displayPlan constraints",
+      ],
+    },
   };
 
   return {
     "buildchain-site.json": siteBundle,
     "site-manifest.json": siteManifest,
+    "page-registry.json": pageRegistry,
     "cli-registry.json": cliRegistry,
     "manual-registry.json": manualRegistry,
     "node-api-registry.json": nodeApiRegistry,