ai-delivery-workflow 0.2.2 → 0.4.0

package/lib/frontend-guard.mjs

@@ -0,0 +1,288 @@
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+import { spawnSync } from "node:child_process";
+import {
+  readYamlMapping,
+  requireSha256,
+  resolveContainedPath,
+  sha256File,
+} from "./artifact-files.mjs";
+import {
+  parsePrototypeCatalogCsv,
+  prototypeRevisionCatalogContracts,
+} from "./prototype-revision.mjs";
+import { buildPrototypeReviewTarget } from "./prototype-review-target.mjs";
+
+function normalizedRelative(value, label) {
+  const normalized = String(value || "").replaceAll("\\", "/").replace(/^\.\//, "");
+  if (!normalized || path.posix.isAbsolute(normalized)
+      || normalized.split("/").some((part) => part === ".." || !part)) {
+    throw new Error(`${label} must be a normalized relative path.`);
+  }
+  return normalized;
+}
+
+function insidePath(candidate, root) {
+  return candidate === root || candidate.startsWith(`${root}/`);
+}
+
+function requireGovernedSource(sourceRef, sourceKind, frontendRoots, extensions) {
+  const covered = frontendRoots.some((root) => insidePath(sourceRef, root))
+    && (sourceKind === "directory"
+      || extensions.includes(path.posix.extname(sourceRef).toLowerCase()));
+  if (!covered) {
+    throw new Error(`Declared UI source is outside the governed frontend scope: ${sourceRef}`);
+  }
+}
+
+function ownershipRules(value, label, options = {}) {
+  if (value === undefined) return [];
+  if (!Array.isArray(value)) throw new Error(`${label} must be a list.`);
+  return value.map((entry) => {
+    const sourceRef = normalizedRelative(entry?.source_ref, `${label} source_ref`);
+    if (!new Set(["file", "directory"]).has(entry?.source_kind)) {
+      throw new Error(`${label} source_kind must be file or directory.`);
+    }
+    const pageIds = Array.isArray(entry.page_ids)
+      ? [...new Set(entry.page_ids.map((item) => String(item || "")))].sort()
+      : [];
+    if (!pageIds.length || pageIds.some((item) => !/^P[0-9]{2,}(?:-[0-9]{2,})?$/.test(item))) {
+      throw new Error(`${label} page_ids are invalid.`);
+    }
+    if (options.requireFile && entry.source_kind !== "file") {
+      throw new Error(`${label} source_kind must be file.`);
+    }
+    const approvedChecksum = options.requireChecksum
+      ? requireSha256(entry.approved_checksum, `${label} approved_checksum`)
+      : null;
+    return {
+      sourceRef,
+      sourceKind: entry.source_kind,
+      pageIds,
+      approvedChecksum,
+    };
+  });
+}
+
+function readFrontendScope(target) {
+  const revision = readYamlMapping(target.revisionFile, "Prototype revision");
+  const binding = revision.frontend_scope;
+  if (binding?.algorithm !== "sha256") {
+    throw new Error("Prototype revision must bind a sha256 Frontend Change Scope.");
+  }
+  const scopeFile = resolveContainedPath(
+    target.contentRoot,
+    binding.ref,
+    "Frontend Change Scope",
+  );
+  if (sha256File(scopeFile) !== requireSha256(binding.checksum, "Frontend Change Scope")) {
+    throw new Error("Frontend Change Scope checksum mismatch.");
+  }
+  const scope = readYamlMapping(scopeFile, "Frontend Change Scope");
+  if (scope.schema_version !== 1 || scope.artifact_type !== "frontend-change-scope") {
+    throw new Error("Frontend Change Scope identity is invalid.");
+  }
+  const codeRoot = normalizedRelative(scope.code_root, "Frontend Change Scope code_root");
+  const frontendRoots = Array.isArray(scope.frontend_roots)
+    ? scope.frontend_roots.map((item) => normalizedRelative(item, "Frontend root"))
+    : [];
+  const extensions = Array.isArray(scope.ui_file_extensions)
+    ? scope.ui_file_extensions.map((item) => String(item || "").toLowerCase())
+    : [];
+  if (!frontendRoots.length || !extensions.length
+      || extensions.some((item) => !/^\.[a-z0-9]+$/.test(item))) {
+    throw new Error("Frontend Change Scope roots or UI file extensions are invalid.");
+  }
+  return {
+    revision,
+    scope,
+    codeRoot,
+    frontendRoots,
+    extensions,
+    sharedComponents: ownershipRules(scope.shared_components, "Shared component ownership"),
+    routeRegistries: ownershipRules(scope.route_registries, "Route registry ownership", {
+      requireFile: true,
+      requireChecksum: true,
+    }),
+  };
+}
+
+function readUiMappings(target, revision) {
+  const binding = revision.catalogs?.ui_mapping;
+  const mappingFile = resolveContainedPath(
+    target.contentRoot,
+    binding?.ref,
+    "Prototype UI Mapping catalog",
+  );
+  if (binding?.algorithm !== "sha256"
+      || sha256File(mappingFile) !== requireSha256(binding?.checksum, "Prototype UI Mapping catalog")) {
+    throw new Error("Prototype UI Mapping catalog checksum mismatch.");
+  }
+  const parsed = parsePrototypeCatalogCsv(
+    fs.readFileSync(mappingFile, "utf8"),
+    "Prototype UI Mapping catalog",
+  );
+  if (parsed.header !== prototypeRevisionCatalogContracts.ui_mapping) {
+    throw new Error("Prototype UI Mapping catalog header is invalid.");
+  }
+  return parsed.rows.filter((row) => row.lifecycle_status === "active");
+}
+
+function changedCodePath(projectRoot, codeRoot, changedPath) {
+  const root = path.resolve(projectRoot);
+  const codeDirectory = resolveContainedPath(root, codeRoot, "Frontend code root");
+  const absolute = path.isAbsolute(changedPath)
+    ? path.resolve(changedPath)
+    : path.resolve(root, changedPath);
+  const projectRelation = path.relative(root, absolute);
+  if (projectRelation === ".." || projectRelation.startsWith(`..${path.sep}`)) {
+    throw new Error(`Changed path resolves outside the project: ${changedPath}`);
+  }
+  const codeRelation = path.relative(codeDirectory, absolute);
+  if (codeRelation === ".." || codeRelation.startsWith(`..${path.sep}`) || path.isAbsolute(codeRelation)) {
+    return null;
+  }
+  return codeRelation.replaceAll("\\", "/");
+}
+
+export function verifyFrontendChangePaths(projectRoot, changedPaths, options = {}) {
+  const target = buildPrototypeReviewTarget(projectRoot, {
+    experience: options.experience || ".workflow/experience",
+    revision: options.revision,
+    now: options.now,
+  });
+  if (target.mode !== "prototype-revision") {
+    throw new Error("Frontend changes require an approved, unexpired Visual Standard and frozen Prototype revision.");
+  }
+  const {
+    revision, codeRoot, frontendRoots, extensions, sharedComponents, routeRegistries,
+  } = readFrontendScope(target);
+  const mappings = readUiMappings(target, revision);
+  for (const mapping of mappings) {
+    requireGovernedSource(
+      normalizedRelative(mapping.frontend_source_ref, "UI Mapping frontend_source_ref"),
+      "file",
+      frontendRoots,
+      extensions,
+    );
+  }
+  for (const ownership of [...sharedComponents, ...routeRegistries]) {
+    requireGovernedSource(
+      ownership.sourceRef,
+      ownership.sourceKind,
+      frontendRoots,
+      extensions,
+    );
+  }
+  const guardedFiles = [];
+  const affectedPageIds = new Set();
+  for (const changedPath of changedPaths) {
+    const relative = changedCodePath(projectRoot, codeRoot, changedPath);
+    if (relative === null
+        || !frontendRoots.some((root) => insidePath(relative, root))
+        || !extensions.includes(path.posix.extname(relative).toLowerCase())) continue;
+    guardedFiles.push(relative);
+    const matching = mappings.filter((mapping) =>
+      normalizedRelative(mapping.frontend_source_ref, "UI Mapping frontend_source_ref") === relative);
+    const sharedOwnership = sharedComponents.filter((entry) =>
+      entry.sourceKind === "file"
+        ? relative === entry.sourceRef
+        : insidePath(relative, entry.sourceRef));
+    const routeOwnership = routeRegistries.filter((entry) =>
+      entry.sourceKind === "file"
+        ? relative === entry.sourceRef
+        : insidePath(relative, entry.sourceRef));
+    if (!matching.length && !sharedOwnership.length && !routeOwnership.length) {
+      throw new Error(`Frontend UI file is not covered by the approved UI Mapping: ${relative}`);
+    }
+    for (const mapping of matching) affectedPageIds.add(mapping.page_id);
+    for (const ownership of routeOwnership) {
+      const actualChecksum = options.routeRegistryChecksums?.get(relative);
+      if (actualChecksum && actualChecksum !== ownership.approvedChecksum) {
+        throw new Error(`Approved route registry checksum mismatch: ${relative}`);
+      }
+    }
+    for (const ownership of [...sharedOwnership, ...routeOwnership]) {
+      for (const pageId of ownership.pageIds) affectedPageIds.add(pageId);
+    }
+  }
+  const pageById = new Map(target.pages.map((page) => [page.page_id, page]));
+  for (const pageId of affectedPageIds) {
+    const page = pageById.get(pageId);
+    if (!page || page.review_status !== "approved") {
+      throw new Error(`Frontend change requires a current approved Prototype Page receipt: ${pageId}.`);
+    }
+  }
+  return {
+    valid: true,
+    prototype_revision_id: target.targetId,
+    prototype_revision_checksum: target.targetChecksum,
+    guarded_files: [...new Set(guardedFiles)].sort(),
+    affected_page_ids: [...affectedPageIds].sort(),
+  };
+}
+
+function requireGitRef(value, label) {
+  const ref = String(value || "");
+  if (!ref || ref.startsWith("-") || /[\0\r\n]/.test(ref)) {
+    throw new Error(`${label} Git ref is invalid.`);
+  }
+  return ref;
+}
+
+export function verifyFrontendDiff(projectRoot, options = {}) {
+  const target = buildPrototypeReviewTarget(projectRoot, {
+    experience: options.experience || ".workflow/experience",
+    revision: options.revision,
+    now: options.now,
+  });
+  if (target.mode !== "prototype-revision") {
+    throw new Error("Frontend changes require an approved, unexpired Visual Standard and frozen Prototype revision.");
+  }
+  const { codeRoot, routeRegistries } = readFrontendScope(target);
+  const codeDirectory = resolveContainedPath(projectRoot, codeRoot, "Frontend code root");
+  const base = requireGitRef(options.base, "Base");
+  const head = requireGitRef(options.head || "HEAD", "Head");
+  const diff = spawnSync("git", [
+    "-C", codeDirectory, "diff", "--name-only", "-z", `${base}...${head}`, "--",
+  ], { encoding: "utf8", windowsHide: true, maxBuffer: 8 * 1024 * 1024 });
+  if (diff.error || diff.status !== 0) {
+    throw new Error(`Cannot independently read frontend Git diff: ${diff.error?.message || diff.stderr.trim() || `git exited ${diff.status}`}`);
+  }
+  const changed = diff.stdout.split("\0").filter(Boolean);
+  const changedSet = new Set(changed.map((item) => item.replaceAll("\\", "/")));
+  const routeRegistryChecksums = new Map();
+  for (const registry of routeRegistries.filter((entry) => changedSet.has(entry.sourceRef))) {
+    const blob = spawnSync("git", [
+      "-C", codeDirectory, "show", `${head}:${registry.sourceRef}`,
+    ], { encoding: null, windowsHide: true, maxBuffer: 8 * 1024 * 1024 });
+    if (blob.error || blob.status !== 0) {
+      throw new Error(
+        `Cannot independently read route registry from Head: ${registry.sourceRef}.`,
+      );
+    }
+    routeRegistryChecksums.set(
+      registry.sourceRef,
+      crypto.createHash("sha256").update(blob.stdout).digest("hex"),
+    );
+  }
+  const report = verifyFrontendChangePaths(
+    projectRoot,
+    changed.map((item) => `${codeRoot}/${item.replaceAll("\\", "/")}`),
+    { ...options, routeRegistryChecksums },
+  );
+  return {
+    ...report,
+    git_diff: { base, head, changed_file_count: changed.length },
+  };
+}
+
+export function runFrontendGuardCommand(projectRoot, action, options = {}) {
+  if (action === "check-file") {
+    if (!options.path) throw new Error("frontend-guard check-file requires --path.");
+    return verifyFrontendChangePaths(projectRoot, [options.path], options);
+  }
+  if (action === "verify-diff") return verifyFrontendDiff(projectRoot, options);
+  throw new Error(`Unknown frontend-guard action: ${action}`);
+}

package/lib/fs-utils.mjs

@@ -0,0 +1,53 @@
+import fs from "node:fs";
+import path from "node:path";
+
+export function atomicWrite(file, content) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const temporary = `${file}.${process.pid}.${Date.now()}.tmp`;
+  fs.writeFileSync(temporary, content, "utf8");
+  fs.renameSync(temporary, file);
+}
+
+export function filesUnder(root) {
+  if (!fs.existsSync(root)) return [];
+  const files = [];
+  const visit = (directory) => {
+    for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+      const absolute = path.join(directory, entry.name);
+      if (entry.isDirectory()) visit(absolute);
+      else if (entry.isFile()) files.push(absolute);
+    }
+  };
+  visit(root);
+  return files.sort((left, right) => left.localeCompare(right));
+}
+
+export function assertPathInside(root, target) {
+  const realRoot = fs.realpathSync(root);
+  let existingAncestor = path.resolve(target);
+  while (!fs.existsSync(existingAncestor)) {
+    const parent = path.dirname(existingAncestor);
+    if (parent === existingAncestor) break;
+    existingAncestor = parent;
+  }
+  const realAncestor = fs.realpathSync(existingAncestor);
+  const relative = path.relative(realRoot, realAncestor);
+  if (relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative))) return target;
+  throw new Error(`Path resolves outside the project: ${target} -> ${realAncestor}`);
+}
+
+export function resolveContainedRelativePath(root, relative, allowedPrefixes = []) {
+  const value = String(relative || "");
+  if (!value || value.includes("\\") || value.includes("\0")
+    || path.posix.isAbsolute(value) || path.posix.normalize(value) !== value
+    || value === ".." || value.startsWith("../")) {
+    throw new Error(`Invalid migration path: ${value || "missing"}.`);
+  }
+  if (allowedPrefixes.length && !allowedPrefixes.some((prefix) =>
+    value === prefix || value.startsWith(`${prefix}/`))) {
+    throw new Error(`Migration path is outside its allowed area: ${value}.`);
+  }
+  const target = path.resolve(root, ...value.split("/"));
+  assertPathInside(root, target);
+  return target;
+}

package/lib/history-anchor.mjs

@@ -0,0 +1,98 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+function sha256(value) {
+  return crypto.createHash("sha256").update(value).digest("hex");
+}
+
+function stableValue(value) {
+  if (Array.isArray(value)) return value.map(stableValue);
+  if (!value || typeof value !== "object") return value;
+  return Object.fromEntries(Object.keys(value).sort().map((key) => [key, stableValue(value[key])]));
+}
+
+export function structuredDocumentChecksum(value, checksumField, stringify) {
+  const unsigned = { ...value };
+  delete unsigned[checksumField];
+  return sha256(stringify(stableValue(unsigned)));
+}
+
+export function historyAnchorId(value) {
+  const anchorId = String(value || "");
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(anchorId)) {
+    throw new Error(`History anchor ID is invalid: ${anchorId || "missing"}.`);
+  }
+  return anchorId;
+}
+
+export function readVerifiedHistoryAnchor({
+  historySnapshots,
+  events,
+  streams,
+  readStructured,
+  stringify,
+}) {
+  const pointerFile = path.join(historySnapshots, "latest.yaml");
+  if (!fs.existsSync(pointerFile)) return null;
+  const pointer = readStructured(pointerFile, "latest history anchor pointer");
+  if (pointer.schema_version !== 1 || !pointer.anchor_id || !pointer.anchor_checksum
+    || structuredDocumentChecksum(pointer, "pointer_checksum", stringify)
+      !== pointer.pointer_checksum) {
+    throw new Error("Latest history anchor pointer is invalid.");
+  }
+  const anchorId = historyAnchorId(pointer.anchor_id);
+  const directory = path.join(historySnapshots, anchorId);
+  const anchorFile = path.join(directory, "anchor.yaml");
+  const anchor = readStructured(anchorFile, `history anchor ${anchorId}`);
+  if (anchor.schema_version !== 1 || anchor.anchor_id !== anchorId
+    || anchor.anchor_checksum !== pointer.anchor_checksum
+    || structuredDocumentChecksum(anchor, "anchor_checksum", stringify) !== anchor.anchor_checksum) {
+    throw new Error(`History anchor checksum is invalid: ${anchorId}.`);
+  }
+  const snapshots = {};
+  const snapshotFiles = {};
+  for (const [stream, descriptor] of streams) {
+    const metadata = anchor.streams?.[stream];
+    if (!metadata || !Number.isInteger(metadata.revision) || metadata.revision < 0
+      || !/^[a-f0-9]{64}$/.test(metadata.view_checksum || "")
+      || (metadata.record_checksum !== null && !/^[a-f0-9]{64}$/.test(metadata.record_checksum || ""))) {
+      throw new Error(`History anchor stream metadata is invalid: ${anchorId}/${stream}.`);
+    }
+    const snapshotFile = path.join(directory, descriptor.snapshotFile);
+    if (!fs.existsSync(snapshotFile)
+      || sha256(fs.readFileSync(snapshotFile)) !== metadata.view_checksum) {
+      throw new Error(`History anchor snapshot checksum is invalid: ${anchorId}/${stream}.`);
+    }
+    snapshots[stream] = descriptor.normalize(readStructured(
+      snapshotFile,
+      `history anchor snapshot ${anchorId}/${stream}`,
+    ));
+    if (snapshots[stream].revision !== metadata.revision) {
+      throw new Error(`History anchor snapshot revision is invalid: ${anchorId}/${stream}.`);
+    }
+    snapshotFiles[stream] = snapshotFile;
+  }
+  const eventOffset = anchor.event_index?.offset_bytes;
+  const eventCount = anchor.event_index?.event_count;
+  const currentEventBytes = fs.existsSync(events) ? fs.statSync(events).size : 0;
+  if (!Number.isInteger(eventOffset) || eventOffset < 0 || eventOffset > currentEventBytes
+    || !Number.isInteger(eventCount) || eventCount < 0
+    || eventCount !== Object.values(anchor.streams)
+      .reduce((total, stream) => total + stream.revision, 0)) {
+    throw new Error(`History anchor event index metadata is invalid: ${anchorId}.`);
+  }
+  if (eventOffset > 0) {
+    const descriptor = fs.openSync(events, "r");
+    try {
+      const boundary = Buffer.alloc(1);
+      fs.readSync(descriptor, boundary, 0, 1, eventOffset - 1);
+      if (boundary[0] !== 0x0a) {
+        throw new Error(`History anchor event index boundary is invalid: ${anchorId}.`);
+      }
+    } finally {
+      fs.closeSync(descriptor);
+    }
+  }
+  return { pointer, pointerFile, anchor, anchorFile, snapshots, snapshotFiles };
+}