@kungfu-tech/kfd 1.0.0-alpha.2 → 1.0.0-alpha.20

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,35 @@
+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 standards = readJson("standards.json");
+const standardsSha = sha256File("standards.json");
+const registrySha = sha256File("registry.json");
+const surfaceRegister = standards.standards?.["kfd-1"]?.surfaceRegister;
+const registeredSurfaces = new Map((surfaceRegister?.surfaces ?? []).map((surface) => [surface.id, surface]));
+
+witness.contractWorld.digest = `sha256:${standardsSha}`;
+witness.canonicalPolicy.sha256 = standardsSha;
+witness.registry.sha256 = registrySha;
+witness.compatibilityImpactClasses = surfaceRegister?.compatibilityImpactClasses ?? [];
+witness.surfaces = [...registeredSurfaces.values()].map((registered) => ({
+  name: registered.id,
+  sourcePath: registered.sourcePath,
+  sourceSha256: sha256File(registered.sourcePath),
+  artifactPath: registered.sourcePath,
+  expectedSha256: sha256File(registered.sourcePath),
+  byteForByte: true,
+  class: registered.class,
+  classes: registered.classes ?? [registered.class],
+  description: registered.description,
+  weldRationale: registered.weldRationale,
+  impactProjection: registered.impactProjection,
+}));
+
+writeFileSync(outputPath, `${JSON.stringify(witness, null, 2)}\n`);
+console.log(`updated ${outputPath}`);

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

@@ -0,0 +1,304 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import crypto from "node:crypto";
+import path from "node:path";
+
+const releaseClaimPath = ".buildchain/kfd-2/public-release-trust.claim.json";
+const trustClaimsPath = ".buildchain/kfd-2/kfd-foundation.trust-claims.json";
+const trustAssessmentPath = ".buildchain/kfd-2/kfd-foundation.trust-assessment.json";
+
+const readJson = (filePath) => JSON.parse(readFileSync(filePath, "utf8"));
+const sha256File = (filePath) => crypto.createHash("sha256").update(readFileSync(filePath)).digest("hex");
+const digestFile = (filePath) => `sha256:${sha256File(filePath)}`;
+const pointer = (filePath, extra = {}) => ({
+  path: filePath,
+  sha256: sha256File(filePath),
+  ...extra,
+});
+const artifactPointer = (kind, filePath, extra = {}) => ({
+  kind,
+  path: filePath,
+  sha256: sha256File(filePath),
+  ...extra,
+});
+const evidence = (type, filePath, description, extra = {}) => ({
+  type,
+  pointer: artifactPointer(type === "schema" ? "schema" : type === "witness" ? "witness" : "file", filePath),
+  machineProvability: "machine-verifiable",
+  description,
+  ...extra,
+});
+const evidenceResult = (type, filePath, description, extra = {}) => ({
+  type,
+  result: "pass",
+  machineProvability: "machine-verifiable",
+  path: filePath,
+  digest: digestFile(filePath),
+  description,
+  ...extra,
+});
+const responsibility = {
+  owner: "KFD maintainers",
+  sourceOwner: "KFD maintainers",
+  verificationOwner: "KFD package self-verification",
+  decisionOwner: "KFD maintainers",
+};
+const naturalLanguageResidualRisk = {
+  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 cannot be exhaustively proved from package bytes.",
+  owner: "KFD maintainers",
+};
+const writeJson = (filePath, value) => {
+  mkdirSync(path.dirname(filePath), { recursive: true });
+  writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`);
+  console.log(`updated ${filePath}`);
+};
+
+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" }),
+  pointer("buildchain.contract-lock.json", { id: "buildchain-runtime-contract-lock" }),
+];
+
+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/trust-claims.schema.json", { id: "kfd-2-trust-claims-schema" }),
+  pointer("schemas/kfd-2/trust-assessment.schema.json", { id: "kfd-2-trust-assessment-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 releaseClaim = {
+  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: [],
+};
+
+writeJson(releaseClaimPath, releaseClaim);
+
+const trustClaims = {
+  schemaVersion: 1,
+  contract: "kfd-2-trust-claims",
+  standard: "kfd-2",
+  projection: {
+    kind: "generic",
+    description: "KFD self-dogfood claims for assessing KFD-1, KFD-3, and KFD-4 from the generic KFD-2 trust model.",
+  },
+  claims: [
+    {
+      id: "kfd-1-contract-world-trust",
+      statement:
+        "KFD-1 is trustable as the KFD package contract-world rule because its surface register, schema, witness, and verification command are inspectable from committed package facts.",
+      subject: {
+        kind: "contract-world",
+        id: "kfd-1-surface-register",
+        standard: "kfd-1",
+        description: "KFD-1 non-drifting fact-source and compatibility-impact surface register.",
+      },
+      facts: [
+        artifactPointer("file", "standards.json"),
+        artifactPointer("schema", "schemas/kfd-1/contract-world.schema.json"),
+      ],
+      evidence: [
+        evidence("schema", "schemas/kfd-1/contract-world.schema.json", "KFD-1 contract-world schema is published as a package surface."),
+        evidence("file", "scripts/check.mjs", "The package check gate validates the KFD-1 schema, surface register, witness, and hashes."),
+      ],
+      verification: {
+        command: "node scripts/check.mjs",
+        expectedResult: "pass",
+      },
+      auditBoundary: {
+        scope: "KFD package KFD-1 surface-register, schema, witness, and self-verification gate",
+        enumerability: "closed-world",
+      },
+      residualRisk: [],
+      responsibility,
+      status: "enforced",
+    },
+    {
+      id: "kfd-3-collaboration-interface-trust",
+      statement:
+        "KFD-3 is trustable as a participant-facing collaboration interface because KFD publishes the declared interface, explicit value evidence, prebuild witness, artifact witness, extension path, and closure check.",
+      subject: {
+        kind: "collaboration-interface",
+        id: "kfd-3-collaboration-interface",
+        standard: "kfd-3",
+        description: "KFD package collaboration interface for humans, agents, maintainers, package consumers, site consumers, and release systems.",
+      },
+      facts: [
+        artifactPointer("file", ".buildchain/kfd-3/collaboration-interface.json"),
+      ],
+      evidence: [
+        evidence("schema", "schemas/kfd-3/collaboration-interface.schema.json", "KFD-3 collaboration interface schema is published."),
+        evidence("file", ".buildchain/kfd-3/collaboration-interface.json", "KFD-3 source collaboration interface declares reachable participant-facing surfaces and value evidence."),
+        evidence("file", "scripts/check.mjs", "The package check gate validates KFD-3 interface closure and witness parity."),
+      ],
+      verification: {
+        command: "node scripts/check.mjs",
+        expectedResult: "warning",
+      },
+      auditBoundary: {
+        scope: "KFD participant-facing collaboration surfaces, extension paths, and shipped witness files",
+        enumerability: "closed-world",
+      },
+      residualRisk: [naturalLanguageResidualRisk],
+      responsibility,
+      status: "enforced",
+    },
+    {
+      id: "kfd-4-observer-perspective-trust",
+      statement:
+        "KFD-4 is trustable as an observer-perspective interface because KFD publishes the schema, standards metadata, decision text, and verification gate for observer-relative timeline views.",
+      subject: {
+        kind: "observer-perspective",
+        id: "kfd-4-observer-perspective",
+        standard: "kfd-4",
+        description: "KFD-4 observer-perspective schema for perspective-bearing timeline views.",
+      },
+      facts: [
+        artifactPointer("file", "decisions/KFD-4.md"),
+        artifactPointer("file", "standards.json"),
+        artifactPointer("schema", "schemas/kfd-4/observer-perspective.schema.json"),
+      ],
+      evidence: [
+        evidence("schema", "schemas/kfd-4/observer-perspective.schema.json", "KFD-4 observer-perspective schema is published."),
+        evidence("file", "standards.json", "Standards metadata exposes the KFD-4 schema ID, path, interface version, and concept names."),
+        evidence("file", "scripts/check.mjs", "The package check gate validates the KFD-4 schema and standards metadata."),
+      ],
+      verification: {
+        command: "node scripts/check.mjs",
+        expectedResult: "pass",
+      },
+      auditBoundary: {
+        scope: "KFD-4 decision text, observer-perspective schema, standards metadata, and self-verification gate",
+        enumerability: "closed-world",
+      },
+      residualRisk: [],
+      responsibility,
+      status: "enforced",
+    },
+  ],
+  schemaEvolution: {
+    compatibilityRule:
+      "Compatible additions may keep schemaVersion 1; semantic, required-field, verification-meaning, or responsibility-boundary changes require a new interface version or contract.",
+  },
+};
+writeJson(trustClaimsPath, trustClaims);
+
+const trustClaimsDigest = digestFile(trustClaimsPath);
+const assessment = {
+  schemaVersion: 1,
+  contract: "kfd-2-trust-assessment",
+  standard: "kfd-2",
+  assessedClaims: {
+    schemaId: "https://kfd.libkungfu.dev/schemas/kfd-2/trust-claims.schema.json",
+    path: trustClaimsPath,
+    digest: trustClaimsDigest,
+  },
+  result: "warning",
+  projection: {
+    kind: "generic",
+    description: "Generic KFD-2 assessment of KFD-owned foundation and practice guideline claims.",
+  },
+  assessments: [
+    {
+      id: "assess-kfd-1-contract-world-trust",
+      claimId: "kfd-1-contract-world-trust",
+      subject: trustClaims.claims[0].subject,
+      result: "pass",
+      facts: trustClaims.claims[0].facts.map((entry) => evidenceResult(entry.kind, entry.path, `Fact ${entry.path} is present and hashable.`)),
+      evidence: trustClaims.claims[0].evidence.map((entry) => evidenceResult(entry.type, entry.pointer.path, entry.description)),
+      auditBoundary: trustClaims.claims[0].auditBoundary,
+      responsibility,
+      residualRisk: [],
+    },
+    {
+      id: "assess-kfd-3-collaboration-interface-trust",
+      claimId: "kfd-3-collaboration-interface-trust",
+      subject: trustClaims.claims[1].subject,
+      result: "warning",
+      facts: trustClaims.claims[1].facts.map((entry) => evidenceResult(entry.kind, entry.path, `Fact ${entry.path} is present and hashable.`)),
+      evidence: trustClaims.claims[1].evidence.map((entry) => evidenceResult(entry.type, entry.pointer.path, entry.description)),
+      auditBoundary: trustClaims.claims[1].auditBoundary,
+      responsibility,
+      residualRisk: [naturalLanguageResidualRisk],
+    },
+    {
+      id: "assess-kfd-4-observer-perspective-trust",
+      claimId: "kfd-4-observer-perspective-trust",
+      subject: trustClaims.claims[2].subject,
+      result: "pass",
+      facts: trustClaims.claims[2].facts.map((entry) => evidenceResult(entry.kind, entry.path, `Fact ${entry.path} is present and hashable.`)),
+      evidence: trustClaims.claims[2].evidence.map((entry) => evidenceResult(entry.type, entry.pointer.path, entry.description)),
+      auditBoundary: trustClaims.claims[2].auditBoundary,
+      responsibility,
+      residualRisk: [],
+    },
+  ],
+  unboundClaims: [],
+  downgradeReasons: [
+    {
+      id: "kfd-3-natural-language-semantics",
+      riskType: "natural-language-semantic-risk",
+      trustImpact: "downgrade-warning",
+      reason: "KFD-3 exposes machine-checkable collaboration surfaces and value evidence, but the human-language meaning of trusted value and non-coercive cooperation remains a reviewable semantic responsibility.",
+      agentAction: "semantic-review-required",
+      source: "kfd-3-collaboration-interface-trust",
+    },
+  ],
+  responsibility,
+  schemaEvolution: trustClaims.schemaEvolution,
+};
+writeJson(trustAssessmentPath, assessment);