@kungfu-tech/kfd 1.0.0-alpha.14 → 1.0.0-alpha.15

package/scripts/npm-publish-transaction.mjs

@@ -0,0 +1,220 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+const EXACT_TAG_PATTERN = /^v\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
+
+function readArg(argv, name, fallback = "") {
+  const index = argv.indexOf(`--${name}`);
+  return index === -1 ? fallback : argv[index + 1] || "";
+}
+
+function hasFlag(argv, name) {
+  return argv.includes(`--${name}`);
+}
+
+function readEnv(name, fallback = "") {
+  return process.env[name] || fallback;
+}
+
+function runNpm({ cwd, args, allowFailure = false }) {
+  const result = spawnSync("npm", args, { cwd, env: process.env, encoding: "utf8" });
+  if (result.error) throw result.error;
+  if (!allowFailure && result.status !== 0) {
+    throw new Error(`npm ${args.join(" ")} failed\n${result.stdout || ""}${result.stderr || ""}`.trim());
+  }
+  return result;
+}
+
+function readPackageJson(cwd) {
+  const filePath = path.join(cwd, "package.json");
+  if (!fs.existsSync(filePath)) throw new Error(`package.json not found: ${filePath}`);
+  return JSON.parse(fs.readFileSync(filePath, "utf8"));
+}
+
+function parsePackResult(stdout) {
+  const parsed = JSON.parse(stdout);
+  const pack = Array.isArray(parsed) ? parsed[0] : parsed;
+  if (!pack?.name || !pack?.version) throw new Error("npm pack did not return package name and version");
+  return {
+    name: pack.name,
+    version: pack.version,
+    filename: pack.filename || "",
+    integrity: pack.integrity || "",
+    shasum: pack.shasum || "",
+    entryCount: pack.entryCount || pack.files?.length || 0,
+  };
+}
+
+function artifactDigest(pack) {
+  if (pack.integrity) return pack.integrity;
+  if (pack.shasum) return `sha1:${pack.shasum}`;
+  throw new Error("npm pack did not return integrity or shasum");
+}
+
+function parseNpmView(stdout) {
+  const raw = String(stdout || "").trim();
+  if (!raw) return undefined;
+  const parsed = JSON.parse(raw);
+  const dist = parsed?.dist || parsed;
+  return {
+    integrity: dist?.integrity || parsed?.["dist.integrity"] || "",
+    shasum: dist?.shasum || parsed?.["dist.shasum"] || "",
+  };
+}
+
+function publishedDigest({ cwd, name, version, registry }) {
+  const result = runNpm({
+    cwd,
+    args: ["view", `${name}@${version}`, "dist.integrity", "dist.shasum", "--json", `--registry=${registry}`],
+    allowFailure: true,
+  });
+  if (result.status !== 0) {
+    const output = `${result.stdout || ""}\n${result.stderr || ""}`;
+    if (/\bE404\b|404 Not Found|is not in this registry/i.test(output)) return undefined;
+    throw new Error(`npm view ${name}@${version} failed\n${output}`.trim());
+  }
+  const view = parseNpmView(result.stdout);
+  return view?.integrity || (view?.shasum ? `sha1:${view.shasum}` : "");
+}
+
+function assertPackageVersion({ pkg, expectedVersion }) {
+  if (pkg.private === true) throw new Error("package.json private must be false before npm publish");
+  if (!pkg.name || typeof pkg.name !== "string") throw new Error("package.json name must be a non-empty string");
+  if (!pkg.version || typeof pkg.version !== "string") throw new Error("package.json version must be a non-empty string");
+  if (expectedVersion && pkg.version !== expectedVersion) {
+    throw new Error(`package.json version must match Buildchain version: package=${pkg.version} buildchain=${expectedVersion}`);
+  }
+  const exactTag = `v${pkg.version}`;
+  if (!EXACT_TAG_PATTERN.test(exactTag)) throw new Error(`unsupported release tag for npm publish: ${exactTag}`);
+  return exactTag;
+}
+
+function writeEvidence({ cwd, evidencePath, evidence }) {
+  const resolved = path.resolve(cwd, evidencePath);
+  fs.mkdirSync(path.dirname(resolved), { recursive: true });
+  fs.writeFileSync(resolved, `${JSON.stringify(evidence, null, 2)}\n`);
+  return resolved;
+}
+
+function writeGitHubOutputs(outputs) {
+  const outputPath = process.env.GITHUB_OUTPUT;
+  if (!outputPath) return;
+  fs.appendFileSync(outputPath, `${Object.entries(outputs)
+    .map(([key, value]) => `${key}=${String(value).replace(/\r?\n/g, " ")}`)
+    .join("\n")}\n`);
+}
+
+export function npmPublishTransaction({
+  cwd = process.cwd(),
+  registry = "https://registry.npmjs.org/",
+  dryRunPublish = false,
+  access = "public",
+  skipRegistryLookup = false,
+} = {}) {
+  const resolvedCwd = path.resolve(cwd);
+  const pkg = readPackageJson(resolvedCwd);
+  const expectedVersion = readEnv("BUILDCHAIN_VERSION");
+  const exactTag = assertPackageVersion({ pkg, expectedVersion });
+  const distTag = readEnv("BUILDCHAIN_NPM_DIST_TAG", pkg.version.includes("-") ? "alpha" : "latest");
+  const pack = parsePackResult(runNpm({
+    cwd: resolvedCwd,
+    args: ["pack", "--dry-run", "--json", `--registry=${registry}`],
+  }).stdout);
+  const digest = artifactDigest(pack);
+  const existingDigest = skipRegistryLookup ? undefined : publishedDigest({
+    cwd: resolvedCwd,
+    name: pkg.name,
+    version: pkg.version,
+    registry,
+  });
+  let publishAction = "already-published";
+  if (existingDigest) {
+    if (existingDigest !== digest) throw new Error(`artifact digest mismatch: npm:${pkg.name}@${pkg.version}`);
+  } else if (dryRunPublish) {
+    publishAction = "dry-run";
+  } else {
+    runNpm({
+      cwd: resolvedCwd,
+      args: ["publish", "--access", access, "--tag", distTag, `--registry=${registry}`],
+    });
+    publishAction = "published";
+    const registryDigest = skipRegistryLookup ? undefined : publishedDigest({
+      cwd: resolvedCwd,
+      name: pkg.name,
+      version: pkg.version,
+      registry,
+    });
+    if (registryDigest && registryDigest !== digest) {
+      throw new Error(`artifact digest mismatch: npm:${pkg.name}@${pkg.version}`);
+    }
+  }
+  const evidencePath = readEnv("BUILDCHAIN_PUBLISH_EVIDENCE");
+  if (!evidencePath) throw new Error("BUILDCHAIN_PUBLISH_EVIDENCE is required");
+  const evidence = {
+    schema: 1,
+    version: expectedVersion || pkg.version,
+    channel: readEnv("BUILDCHAIN_CHANNEL"),
+    source_sha: readEnv("BUILDCHAIN_SOURCE_SHA"),
+    release_sha: readEnv("BUILDCHAIN_RELEASE_SHA"),
+    target_ref: readEnv("BUILDCHAIN_TARGET_REF"),
+    release_material_sha: readEnv("BUILDCHAIN_RELEASE_MATERIAL_SHA", readEnv("BUILDCHAIN_RELEASE_SHA")),
+    publish_tooling_sha: readEnv("BUILDCHAIN_PUBLISH_TOOLING_SHA", readEnv("BUILDCHAIN_RELEASE_SHA")),
+    artifacts: [{
+      group: "node",
+      kind: "npm",
+      name: pkg.name,
+      ref: pkg.version,
+      digest,
+    }],
+  };
+  const resolvedEvidencePath = writeEvidence({ cwd: resolvedCwd, evidencePath, evidence });
+  writeGitHubOutputs({
+    version: pkg.version,
+    "exact-tag": exactTag,
+    "dist-tag": distTag,
+    "artifact-digest": digest,
+    "publish-action": publishAction,
+    "publish-evidence": resolvedEvidencePath,
+  });
+  return {
+    schemaVersion: 1,
+    package: { name: pkg.name, version: pkg.version },
+    exactTag,
+    distTag,
+    registry,
+    publishAction,
+    pack,
+    evidencePath: resolvedEvidencePath,
+    evidence,
+  };
+}
+
+function usage() {
+  return `Usage:
+  node scripts/npm-publish-transaction.mjs [--cwd <dir>] [--registry <url>]
+                                           [--dry-run-publish] [--skip-registry-lookup]
+`;
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  try {
+    const argv = process.argv.slice(2);
+    if (hasFlag(argv, "help") || argv.includes("-h")) {
+      process.stdout.write(usage());
+      process.exit(0);
+    }
+    const result = npmPublishTransaction({
+      cwd: readArg(argv, "cwd", process.cwd()),
+      registry: readArg(argv, "registry", "https://registry.npmjs.org/"),
+      dryRunPublish: hasFlag(argv, "dry-run-publish"),
+      skipRegistryLookup: hasFlag(argv, "skip-registry-lookup"),
+    });
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  } catch (error) {
+    console.error(`npm-publish-transaction: ${error.message}`);
+    process.exitCode = 1;
+  }
+}

package/scripts/update-kfd-1-witness.mjs

@@ -0,0 +1,24 @@
+import { readFileSync, writeFileSync } from "node:fs";
+import crypto from "node:crypto";
+
+const outputPath = ".buildchain/kfd-1/contract-world.witness.json";
+
+const readJson = (filePath) => JSON.parse(readFileSync(filePath, "utf8"));
+const sha256File = (filePath) => crypto.createHash("sha256").update(readFileSync(filePath)).digest("hex");
+
+const witness = readJson(outputPath);
+const standardsSha = sha256File("standards.json");
+const registrySha = sha256File("registry.json");
+
+witness.contractWorld.digest = `sha256:${standardsSha}`;
+witness.canonicalPolicy.sha256 = standardsSha;
+witness.registry.sha256 = registrySha;
+
+for (const surface of witness.surfaces ?? []) {
+  if (!surface.sourcePath || !surface.artifactPath) continue;
+  surface.sourceSha256 = sha256File(surface.sourcePath);
+  surface.expectedSha256 = sha256File(surface.artifactPath);
+}
+
+writeFileSync(outputPath, `${JSON.stringify(witness, null, 2)}\n`);
+console.log(`updated ${outputPath}`);

package/scripts/update-kfd-2-claim.mjs

@@ -0,0 +1,82 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import crypto from "node:crypto";
+import path from "node:path";
+
+const outputPath = ".buildchain/kfd-2/public-release-trust.claim.json";
+
+const readJson = (filePath) => JSON.parse(readFileSync(filePath, "utf8"));
+const sha256File = (filePath) => crypto.createHash("sha256").update(readFileSync(filePath)).digest("hex");
+const pointer = (filePath, extra = {}) => ({
+  path: filePath,
+  sha256: sha256File(filePath),
+  ...extra,
+});
+
+const packageJson = readJson("package.json");
+const releaseAnchor = readJson("kfd.release.json");
+
+const sourceBindings = [
+  pointer("package.json", { id: "package-version-and-exports" }),
+  pointer("kfd.release.json", { id: "anchored-release-version" }),
+  pointer("registry.json", { id: "decision-registry" }),
+  pointer("standards.json", { id: "standards-metadata" }),
+  pointer("release-impact.json", { id: "release-impact-ledger" }),
+  pointer("buildchain.toml", { id: "buildchain-release-contract" }),
+];
+
+const machineEvidence = [
+  pointer("scripts/check.mjs", { id: "self-verification-command" }),
+  pointer(".github/workflows/build.yml", { id: "buildchain-build-workflow" }),
+  pointer(".github/workflows/buildchain-ref-promotion.yml", { id: "buildchain-promotion-workflow" }),
+  pointer("schemas/kfd-2/trust-taxonomy.schema.json", { id: "kfd-2-trust-taxonomy-schema" }),
+  pointer("schemas/kfd-2/release-claims.schema.json", { id: "kfd-2-release-claims-schema" }),
+  pointer("schemas/kfd-2/release-trust-passport.schema.json", { id: "kfd-2-release-trust-passport-schema" }),
+];
+
+const hashes = Object.fromEntries(
+  [...sourceBindings, ...machineEvidence].map((entry) => [entry.id, entry.sha256]),
+);
+
+const claim = {
+  id: "kfd-public-release-trust",
+  public: true,
+  claim:
+    "The KFD npm release is backed by declared source facts, machine-readable evidence, artifact coordinates, verification, audit boundary, responsibility, and explicit residual-risk state.",
+  sourceBindings,
+  machineEvidence,
+  hashes,
+  artifacts: [
+    {
+      name: packageJson.name,
+      version: packageJson.version,
+      path: "package.json",
+      sha256: sha256File("package.json"),
+    },
+    {
+      name: "kfd-release-anchor",
+      version: releaseAnchor.npmVersion,
+      path: "kfd.release.json",
+      sha256: sha256File("kfd.release.json"),
+    },
+  ],
+  verification: {
+    result: "passed",
+    command: "node scripts/check.mjs",
+  },
+  auditBoundary: {
+    scope: "KFD public npm package release facts, package exports, release governance files, and Buildchain release-passport inputs",
+    enumerability: "closed-world",
+  },
+  responsibility: {
+    owner: "KFD maintainers",
+    sourceOwner: "KFD maintainers",
+    verificationOwner: "KFD package self-verification",
+    releaseDecisionOwner: "KFD maintainers",
+    releasePassportProofOwner: "Buildchain",
+  },
+  residualRisk: [],
+};
+
+mkdirSync(path.dirname(outputPath), { recursive: true });
+writeFileSync(outputPath, `${JSON.stringify(claim, null, 2)}\n`);
+console.log(`updated ${outputPath}`);

package/scripts/update-kfd-3-witness.mjs

@@ -0,0 +1,227 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import crypto from "node:crypto";
+import path from "node:path";
+
+const interfacePath = ".buildchain/kfd-3/collaboration-interface.json";
+const prebuildPath = ".buildchain/kfd-3/collaboration-interface.prebuild.json";
+const artifactPath = ".buildchain/kfd-3/collaboration-interface.artifact.json";
+
+const readJson = (filePath) => JSON.parse(readFileSync(filePath, "utf8"));
+const sha256File = (filePath) => crypto.createHash("sha256").update(readFileSync(filePath)).digest("hex");
+const hashablePath = (filePath) => filePath.split("#", 1)[0];
+const pointer = (filePath, description = undefined) => ({
+  path: filePath,
+  sha256: sha256File(hashablePath(filePath)),
+  ...(description ? { description } : {}),
+});
+
+const writeJson = (filePath, value) => {
+  mkdirSync(path.dirname(filePath), { recursive: true });
+  writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`);
+};
+
+const packageJson = readJson("package.json");
+const registry = readJson("registry.json");
+const standards = readJson("standards.json");
+const collaborationInterface = readJson(interfacePath);
+const interfaceSha = sha256File(interfacePath);
+const interfaceDigest = `sha256:${interfaceSha}`;
+
+const decisionDocs = registry.entries.map((entry) => ({
+  id: `decision:${entry.slug}`,
+  sourcePath: entry.path,
+  sha256: sha256File(entry.path),
+}));
+const schemaSurfaces = [
+  "schemas/kfd-standards.schema.json",
+  "schemas/kfd-1/contract-world.schema.json",
+  "schemas/kfd-1/witness.schema.json",
+  "schemas/kfd-2/trust-taxonomy.schema.json",
+  "schemas/kfd-2/release-claims.schema.json",
+  "schemas/kfd-2/release-trust-passport.schema.json",
+  "schemas/kfd-3/collaboration-interface.schema.json",
+  "schemas/kfd-3/witness.schema.json",
+].map((filePath) => ({
+  id: `schema:${filePath.replace(/^schemas\//, "").replace(/\.schema\.json$/, "").replace(/\//g, ":")}`,
+  sourcePath: filePath,
+  sha256: sha256File(filePath),
+}));
+
+const groupedSurfaces = {
+  docs: [
+    { id: "doc:readme", sourcePath: "README.md", sha256: sha256File("README.md") },
+    { id: "doc:trademarks", sourcePath: "TRADEMARKS.md", sha256: sha256File("TRADEMARKS.md") },
+    { id: "doc:docs-map", sourcePath: "docs/MAP.md", sha256: sha256File("docs/MAP.md") },
+    { id: "doc:kfd-2-release-trust", sourcePath: "docs/kfd-2-release-trust.md", sha256: sha256File("docs/kfd-2-release-trust.md") },
+    { id: "doc:kfd-3-collaboration-interface", sourcePath: "docs/kfd-3-collaboration-interface.md", sha256: sha256File("docs/kfd-3-collaboration-interface.md") },
+    ...decisionDocs,
+  ],
+  schemas: schemaSurfaces,
+  standardsMetadata: [
+    { id: "metadata:registry", sourcePath: "registry.json", sha256: sha256File("registry.json") },
+    { id: "metadata:standards", sourcePath: "standards.json", sha256: sha256File("standards.json") },
+    { id: "metadata:release-impact", sourcePath: "release-impact.json", sha256: sha256File("release-impact.json") },
+    { id: "metadata:release-anchor", sourcePath: "kfd.release.json", sha256: sha256File("kfd.release.json") },
+    { id: "metadata:kfd-2-public-release-trust-claim", sourcePath: ".buildchain/kfd-2/public-release-trust.claim.json", sha256: sha256File(".buildchain/kfd-2/public-release-trust.claim.json") },
+  ],
+  packageExports: [
+    { id: "export:package-json", sourcePath: "package.json#exports", sha256: sha256File("package.json") },
+    { id: "export:npm-files", sourcePath: "package.json#files", sha256: sha256File("package.json") },
+  ],
+  siteConsumptionContracts: [
+    { id: "site:kfd-site-bundle", sourcePath: "site/kfd-site.json", sha256: sha256File("site/kfd-site.json") },
+    { id: "site:release-propagation", sourcePath: "buildchain.release-propagation.json", sha256: sha256File("buildchain.release-propagation.json") },
+  ],
+};
+
+const explicitSurfaces = collaborationInterface.surfaces.map((surface) => ({
+  id: surface.id,
+  name: surface.id,
+  kind: surface.kind,
+  participantProfile: Array.isArray(surface.participants) ? surface.participants.join(",") : "",
+  availability: surface.maturity || "shipped",
+  visibility: "public",
+  participantFacing: true,
+  public: true,
+  sourcePath: surface.discoverability?.path || "",
+}));
+
+const declaredSurfaceIds = new Set(explicitSurfaces.map((surface) => surface.id));
+for (const entrypoint of collaborationInterface.minimalEntrypoints) {
+  if (declaredSurfaceIds.has(entrypoint.id)) continue;
+  explicitSurfaces.push({
+    id: entrypoint.id,
+    name: entrypoint.id,
+    kind: "entrypoint",
+    participantProfile: Array.isArray(entrypoint.participants) ? entrypoint.participants.join(",") : "",
+    availability: "shipped",
+    visibility: "public",
+    participantFacing: true,
+    public: true,
+    sourcePath: entrypoint.surface,
+  });
+  declaredSurfaceIds.add(entrypoint.id);
+}
+
+const participantProfiles = collaborationInterface.participants.map((entry) => entry.id);
+const responsibility = {
+  registryFactsOwner: "KFD maintainers",
+  artifactVerificationOwner: "KFD package self-verification",
+  releasePassportProofOwner: "Buildchain",
+};
+const residualRisk = [
+  {
+    id: "human-language-interpretation",
+    definedBy: "https://kfd.libkungfu.dev/schemas/kfd-2/trust-taxonomy.schema.json#/$defs/residualRisk",
+    riskType: "natural-language-semantic-risk",
+    trustImpact: "downgrade-warning",
+    machineProvability: "not-exhaustively-enumerable",
+    agentAction: "semantic-review-required",
+    reason: "Natural-language standard interpretation is inspectable and reviewable but not exhaustively enumerable from package bytes.",
+    owner: "KFD maintainers",
+  },
+];
+
+const prebuild = {
+  schemaVersion: 1,
+  contract: "kungfu-buildchain-kfd-3-collaboration-interface-prebuild-witness",
+  id: "kfd-repository",
+  standard: "kfd-3",
+  supportLevel: "release",
+  source: {
+    repo: "kungfu-systems/kfd",
+  },
+  sourceRegistry: {
+    id: "kfd-collaboration-interface",
+    path: interfacePath,
+    sha256: interfaceSha,
+  },
+  collaborationInterfaceDigest: interfaceDigest,
+  collaborationInterface,
+  participantProfiles,
+  surfaces: explicitSurfaces,
+  ...groupedSurfaces,
+  auditBoundary: {
+    mode: "closed-world",
+    scope: "KFD participant-facing public collaboration/control surfaces shipped in the repository and npm package",
+    reachableSurfaceMode: "declared-boundary",
+    unclassifiedPolicy: "fail",
+    nonExhaustivelyEnumerableSurfaces: residualRisk,
+  },
+  residualRisk,
+  responsibility,
+  expectedArtifactVerification: {
+    command: "node scripts/check.mjs",
+  },
+};
+
+const artifact = {
+  schemaVersion: 1,
+  contract: "kfd-3-witness",
+  id: "kfd-repository",
+  standard: "kfd-3",
+  collaborationInterface: {
+    schemaId: standards.standards["kfd-3"].schemaIds.collaborationInterface,
+    digest: interfaceDigest,
+  },
+  sourceRegistry: {
+    id: "kfd-collaboration-interface",
+    path: interfacePath,
+    sha256: interfaceSha,
+  },
+  artifact: {
+    name: packageJson.name,
+    path: "npm:@kungfu-tech/kfd",
+    digest: interfaceDigest,
+  },
+  surfaces: explicitSurfaces,
+  ...groupedSurfaces,
+  evidence: {
+    minimalEntrypoints: collaborationInterface.minimalEntrypoints.map((entry) => pointer(entry.surface, entry.purpose)),
+    discoverability: [
+      pointer("README.md", "Human and agent entrypoint"),
+      pointer("TRADEMARKS.md", "Official status, trademark, and authority boundary"),
+      pointer("docs/MAP.md", "Documentation routing entrypoint"),
+      pointer("registry.json", "Machine-readable decision index"),
+      pointer("standards.json", "Machine-readable standards metadata"),
+      pointer(".buildchain/kfd-2/public-release-trust.claim.json", "KFD-2 public release trust claim"),
+      pointer("package.json", "Package export map"),
+      pointer("site/kfd-site.json", "Site content projection"),
+    ],
+    transparentConstraints: [
+      pointer("CONTRIBUTING.md", "Append-only decision and contribution constraints"),
+      pointer("TRADEMARKS.md", "Trademark and official-status constraints"),
+      pointer("scripts/check.mjs", "Repository self-verification gate"),
+      pointer("site/kfd-site.json", "Site rendering boundary"),
+    ],
+    choicePaths: [
+      pointer("README.md", "Human reading path"),
+      pointer("registry.json", "Agent registry path"),
+      pointer("standards.json", "Agent standards metadata path"),
+      pointer(".buildchain/kfd-2/public-release-trust.claim.json", "Agent release trust claim path"),
+      pointer("package.json", "Package consumption path"),
+    ],
+    manuals: [
+      pointer("docs/MAP.md"),
+      pointer("TRADEMARKS.md"),
+      pointer("docs/kfd-3-collaboration-interface.md"),
+    ],
+  },
+  closure: {
+    classificationMode: "closed-world",
+    reachableEntrypoints: collaborationInterface.minimalEntrypoints.map((entry) => entry.id),
+    classifiedEntrypoints: collaborationInterface.minimalEntrypoints.map((entry) => entry.id),
+    unclassifiedEntrypoints: [],
+  },
+  verifier: {
+    name: "kfd self-verification",
+    command: "node scripts/check.mjs",
+  },
+  residualRisk,
+  result: "pass",
+};
+
+writeJson(prebuildPath, prebuild);
+writeJson(artifactPath, artifact);
+console.log(`updated ${prebuildPath}`);
+console.log(`updated ${artifactPath}`);