@loomhelm/multi-task-flow 0.0.0-stage → 0.2.1

package/toolkit/skills/bin/modules/visual/report_create.ts

@@ -0,0 +1,321 @@
+import {
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  realpathSync,
+  renameSync,
+  symlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { randomBytes } from "node:crypto";
+import { join, relative, resolve } from "node:path";
+import {
+  cloneReportFile,
+  identity,
+  removeStagingPath,
+  type FileIdentity,
+  REG_CLI_COMMAND,
+} from "./isolation";
+import { renameNoReplace } from "./secure_io";
+import {
+  defaultSnapshotRoot,
+  containedPathWithoutSymlinks,
+  expandUserPath,
+  formatUtcTimestamp,
+  isIndependentRegularFile,
+  isRealDirectory,
+  isRegularFile,
+  pathWithin,
+  repoScope,
+  sha256FileSync,
+} from "./paths";
+import {
+  cloneReportOutputs,
+  htmlReportIssue,
+  snapshotIntegrityIssue,
+} from "./report_artifacts";
+import {
+  containedDirectoryTree,
+  diffOutputIssue,
+  isDirectoryWithNames,
+  validatePairs,
+  validatedItemLists,
+  type ImagePair,
+  type ManifestPair,
+  REPORT_ROOT_ENTRIES,
+  REPORT_TOKEN,
+} from "./report_validate";
+import { runRegCli, type CloneFile, type RunRegCli } from "./report_runtime";
+
+function pathIdentityIntact(
+  path: string,
+  root: string,
+  original: FileIdentity,
+): boolean {
+  try {
+    const current = identity(path);
+    return (
+      lstatSync(path).isDirectory() &&
+      current.dev === original.dev &&
+      current.ino === original.ino &&
+      containedPathWithoutSymlinks(path, root) === resolve(path)
+    );
+  } catch {
+    return false;
+  }
+}
+
+function cryptoToken(): string {
+  return randomBytes(8).toString("hex");
+}
+
+function sealStaging(
+  staging: string,
+  parent: string,
+  root: string,
+  original: FileIdentity,
+): string {
+  if (!pathIdentityIntact(staging, root, original))
+    throw new Error("reg-cli replaced or moved the staging directory");
+  const sealed = join(parent, `.sealed-report-${cryptoToken()}`);
+  renameSync(staging, sealed);
+  return sealed;
+}
+
+function realpathSafe(path: string): string {
+  try {
+    return realpathSync(path);
+  } catch {
+    return "";
+  }
+}
+
+function populatePublicationStage(
+  source: string,
+  publication: string,
+  root: string,
+  pairs: ManifestPair[],
+  clone: CloneFile,
+): void {
+  if (
+    !isDirectoryWithNames(
+      source,
+      new Set(
+        [...REPORT_ROOT_ENTRIES].filter((name) => name !== "manifest.json"),
+      ),
+    )
+  )
+    throw new Error("reg-cli produced unexpected top-level report artifacts");
+  if (
+    !["actual", "expected", "diff"].every((folder) =>
+      isRealDirectory(join(source, folder)),
+    )
+  )
+    throw new Error("reg-cli replaced an input or diff directory");
+  if (
+    !isIndependentRegularFile(join(source, "report.html")) ||
+    !isIndependentRegularFile(join(source, "reg.json"))
+  )
+    throw new Error("reg-cli outputs must be independent regular files");
+  const filenames = new Set(pairs.map((pair) => pair.filename));
+  for (const folder of ["actual", "expected"])
+    if (!isDirectoryWithNames(join(source, folder), filenames))
+      throw new Error(`reg-cli changed or added snapshot inputs in ${folder}`);
+  for (const pair of pairs)
+    for (const [folder, key] of [
+      ["actual", "actual_snapshot"],
+      ["expected", "expected_snapshot"],
+    ] as const) {
+      const link = join(source, folder, pair.filename);
+      if (
+        !lstatSync(link).isSymbolicLink() ||
+        realpathSafe(link) !== resolve(pair[key])
+      )
+        throw new Error("reg-cli changed an input snapshot link");
+    }
+  const integrity = snapshotIntegrityIssue(pairs, root);
+  if (integrity) throw new Error(integrity);
+  mkdirSync(join(publication, "diff"));
+  const regJson = JSON.parse(
+    readFileSync(join(source, "reg.json"), "utf8"),
+  ) as unknown;
+  const items = validatedItemLists(regJson, filenames);
+  const diffIssue = diffOutputIssue(
+    join(source, "diff"),
+    items.diffItems,
+    items.failedItems,
+  );
+  if (diffIssue) throw new Error(diffIssue);
+  cloneReportOutputs(source, publication, items, clone);
+  let publishedItems: ReturnType<typeof validatedItemLists>;
+  try {
+    publishedItems = validatedItemLists(
+      JSON.parse(readFileSync(join(publication, "reg.json"), "utf8")),
+      filenames,
+    );
+  } catch (error) {
+    if (error instanceof Error && error.message.startsWith("reg-cli"))
+      throw error;
+    throw new Error("published reg-cli JSON is invalid");
+  }
+  const publishedDiffIssue = diffOutputIssue(
+    join(publication, "diff"),
+    publishedItems.diffItems,
+    publishedItems.failedItems,
+  );
+  if (publishedDiffIssue) throw new Error(publishedDiffIssue);
+  for (const folder of ["actual", "expected"])
+    mkdirSync(join(publication, folder));
+  for (const pair of pairs)
+    for (const [folder, key] of [
+      ["actual", "actual_snapshot"],
+      ["expected", "expected_snapshot"],
+    ] as const) {
+      const sourceImage = resolve(pair[key]);
+      if (
+        containedPathWithoutSymlinks(sourceImage, root) !== sourceImage ||
+        !isRegularFile(sourceImage)
+      )
+        throw new Error("snapshot input disappeared or escaped the asset root");
+      const link = join(publication, folder, pair.filename);
+      symlinkSync(relative(resolve(publication, folder), sourceImage), link);
+    }
+  if (
+    !["actual", "expected"].every((folder) =>
+      isDirectoryWithNames(join(publication, folder), filenames),
+    )
+  )
+    throw new Error("published snapshot links are incomplete");
+  const htmlIssue = htmlReportIssue(
+    join(publication, "report.html"),
+    publishedItems,
+  );
+  if (htmlIssue) throw new Error(htmlIssue);
+  const finalDiffIssue = diffOutputIssue(
+    join(publication, "diff"),
+    publishedItems.diffItems,
+    publishedItems.failedItems,
+  );
+  if (finalDiffIssue) throw new Error(finalDiffIssue);
+}
+
+export function createReport(options: {
+  pairs: ImagePair[];
+  cwd: string;
+  storeRoot?: string;
+  now?: Date;
+  token?: string;
+  runRegCli?: RunRegCli;
+  cloneFile?: CloneFile;
+  beforePublish?: () => void;
+}): Record<string, unknown> {
+  const root = realpathSync(
+    resolve(expandUserPath(options.storeRoot ?? defaultSnapshotRoot())),
+  );
+  const checked = validatePairs(options.pairs, root);
+  const timestamp = options.now ?? new Date();
+  const token = options.token ?? cryptoToken().slice(0, 8);
+  if (!REPORT_TOKEN.test(token))
+    throw new Error("report token must be a single safe path component");
+  const scope = repoScope(resolve(expandUserPath(options.cwd))).repoScope;
+  const date = formatUtcTimestamp(timestamp);
+  const parent = containedDirectoryTree(
+    join(
+      root,
+      scope,
+      date.slice(0, 4),
+      date.slice(4, 6),
+      date.slice(6, 8),
+      "reg-cli-reports",
+    ),
+    root,
+  );
+  const reportDir = join(parent, `${date}-${token}`);
+  if (existsSync(reportDir))
+    throw new Error(`report already exists: ${reportDir}`);
+  const staging = mkdtempSync(join(parent, ".report-"));
+  const stagingIdentity = identity(staging);
+  const runner = options.runRegCli ?? runRegCli;
+  const clone = options.cloneFile ?? cloneReportFile;
+  let sealed: string | undefined;
+  let publication: string | undefined;
+  let publicationIdentity: FileIdentity | undefined;
+  let committed = false;
+  try {
+    for (const folder of ["actual", "expected", "diff"])
+      mkdirSync(join(staging, folder));
+    const manifestPairs: ManifestPair[] = checked.map((pair) => {
+      const filename = `${pair.name}${pair.actual.slice(pair.actual.lastIndexOf("."))}`;
+      symlinkSync(
+        relative(join(staging, "actual"), pair.actual),
+        join(staging, "actual", filename),
+      );
+      symlinkSync(
+        relative(join(staging, "expected"), pair.expected),
+        join(staging, "expected", filename),
+      );
+      return {
+        name: pair.name,
+        filename,
+        expected_snapshot: pair.expected,
+        expected_sha256: sha256FileSync(pair.expected),
+        actual_snapshot: pair.actual,
+        actual_sha256: sha256FileSync(pair.actual),
+      };
+    });
+    const runtime = runner(staging, REG_CLI_COMMAND);
+    sealed = sealStaging(staging, parent, root, stagingIdentity);
+    if (runtime)
+      removeStagingPath(
+        join(sealed, runtime.runtimeName),
+        runtime.runtimeIdentity,
+      );
+    if (!pathIdentityIntact(sealed, root, stagingIdentity))
+      throw new Error("reg-cli replaced or moved the staging directory");
+    publication = mkdtempSync(join(parent, ".publication-"));
+    publicationIdentity = identity(publication);
+    populatePublicationStage(sealed, publication, root, manifestPairs, clone);
+    const manifest = {
+      created_at_utc: timestamp.toISOString(),
+      repo_scope: scope,
+      pairs: manifestPairs,
+      generated_files: ["report.html", "reg.json", "diff/"],
+    };
+    writeFileSync(
+      join(publication, "manifest.json"),
+      `${JSON.stringify(manifest, null, 2)}\n`,
+      "utf8",
+    );
+    if (
+      !isDirectoryWithNames(publication, REPORT_ROOT_ENTRIES) ||
+      !pathIdentityIntact(publication, root, publicationIdentity) ||
+      !isRealDirectory(parent) ||
+      !containedPathWithoutSymlinks(parent, root) ||
+      !pathWithin(root, reportDir)
+    )
+      throw new Error(
+        "report path contains a symlink or escapes the snapshot store",
+      );
+    const issue = snapshotIntegrityIssue(manifestPairs, root);
+    if (issue) throw new Error(issue);
+    options.beforePublish?.();
+    renameNoReplace(publication, reportDir, root);
+    const afterIssue = snapshotIntegrityIssue(manifestPairs, root);
+    if (afterIssue) throw new Error(afterIssue);
+    committed = true;
+    return {
+      report_html: join(reportDir, "report.html"),
+      report_dir: reportDir,
+      pairs: checked.length,
+    };
+  } finally {
+    if (!committed && publication && publicationIdentity)
+      removeStagingPath(publication, publicationIdentity);
+    if (!committed && existsSync(reportDir) && publicationIdentity)
+      removeStagingPath(reportDir, publicationIdentity);
+    if (sealed) removeStagingPath(sealed, stagingIdentity);
+    if (existsSync(staging)) removeStagingPath(staging, stagingIdentity);
+  }
+}

package/toolkit/skills/bin/modules/visual/report_runtime.ts

@@ -0,0 +1,232 @@
+import {
+  accessSync,
+  copyFileSync,
+  constants,
+  lstatSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  realpathSync,
+  writeFileSync,
+} from "node:fs";
+import {
+  basename,
+  delimiter,
+  dirname,
+  isAbsolute,
+  join,
+  resolve,
+} from "node:path";
+import {
+  identity,
+  removeStagingPath,
+  runSandboxedCommand,
+  sandboxAvailable,
+  type RunResult,
+  REG_CLI_COMMAND,
+  REG_CLI_VERSION,
+} from "./isolation";
+import { isRealDirectory, isRegularFile, pathWithin } from "./paths";
+
+export type RunRegCli = (
+  directory: string,
+  command?: readonly string[],
+) => RunResult | undefined;
+export type CloneFile = (source: string, destination: string) => void;
+
+const packageRoot = resolve(import.meta.dir, "../../reg-cli-report");
+
+function commandPath(command: string, pathValue?: string): string {
+  for (const directory of (pathValue ?? "").split(delimiter)) {
+    const candidate = join(directory || ".", command);
+    try {
+      const canonical = realpathSync(candidate);
+      if (!lstatSync(canonical).isFile()) continue;
+      accessSync(canonical, constants.X_OK);
+      return canonical;
+    } catch {}
+  }
+  throw new Error(`${command} is unavailable`);
+}
+
+export const runRegCli: RunRegCli = (directory, command = REG_CLI_COMMAND) => {
+  if (command.join(" ") !== REG_CLI_COMMAND.join(" "))
+    throw new Error(
+      "reg-cli command is fixed; custom commands are not supported",
+    );
+  if (!isRealDirectory(directory))
+    throw new Error("reg-cli staging directory is not a regular directory");
+  if (!sandboxAvailable())
+    throw new Error(
+      "reg-cli reports require macOS sandbox-exec; refusing to run unsandboxed",
+    );
+  const runtime = mkdtempSync(join(directory, ".reg-cli-runtime-"));
+  const runtimeIdentity = identity(runtime);
+  let completed = false;
+  try {
+    const runtimeHome = join(runtime, "home");
+    const runtimeTmp = join(runtime, "tmp");
+    const npmCache = join(runtime, "npm-cache");
+    const packageDirectory = join(runtime, "package");
+    for (const path of [runtimeHome, runtimeTmp, npmCache, packageDirectory])
+      mkdirSync(path);
+    const npmrc = join(runtime, "global.npmrc");
+    writeFileSync(npmrc, "", "utf8");
+    for (const filename of ["package.json", "package-lock.json"])
+      copyFileSync(
+        join(packageRoot, filename),
+        join(packageDirectory, filename),
+      );
+    const env: Record<string, string> = {};
+    for (const key of [
+      "PATH",
+      "LANG",
+      "LC_ALL",
+      "LC_CTYPE",
+      "HTTP_PROXY",
+      "HTTPS_PROXY",
+      "ALL_PROXY",
+      "NO_PROXY",
+      "http_proxy",
+      "https_proxy",
+      "all_proxy",
+      "no_proxy",
+    ])
+      if (process.env[key]) env[key] = process.env[key] as string;
+    Object.assign(env, {
+      HOME: runtimeHome,
+      TMPDIR: runtimeTmp,
+      TMP: runtimeTmp,
+      TEMP: runtimeTmp,
+      npm_config_cache: npmCache,
+      npm_config_logs_dir: join(npmCache, "_logs"),
+      npm_config_userconfig: "/dev/null",
+      npm_config_globalconfig: npmrc,
+      npm_config_ignore_scripts: "true",
+      npm_config_audit: "false",
+      npm_config_fund: "false",
+      npm_config_update_notifier: "false",
+      CI: "1",
+    });
+    const node = commandPath("node", env.PATH);
+    const npm = commandPath("npm", env.PATH);
+    const npmBin = dirname(npm);
+    const npmPackage = dirname(npmBin);
+    const npmNodeModules = dirname(npmPackage);
+    const nodeLib = dirname(npmNodeModules);
+    const nodeRoot = dirname(nodeLib);
+    if (
+      basename(npm) !== "npm-cli.js" ||
+      [npmBin, npmPackage, npmNodeModules, nodeLib]
+        .map((path) => basename(path))
+        .join("/") !== "bin/npm/node_modules/lib"
+    )
+      throw new Error(
+        "npm installation layout is unsupported; refusing to run unsandboxed",
+      );
+    if (dirname(dirname(node)) !== nodeRoot)
+      throw new Error("node and npm must belong to the same installation");
+    const npmRoot = npmPackage;
+    runSandboxedCommand(
+      directory,
+      [
+        node,
+        npm,
+        "ci",
+        "--prefix",
+        packageDirectory,
+        "--ignore-scripts",
+        "--no-audit",
+        "--no-fund",
+        "--no-update-notifier",
+        "--registry=https://registry.npmjs.org/",
+      ],
+      {
+        runtimeDir: runtime,
+        env,
+        allowNetwork: true,
+        label: "pinned-reg-cli-installation",
+        additionalReadPaths: [runtime, node, npmRoot],
+        includeStagingRead: false,
+        includeSnapshotReads: false,
+        workingDirectory: packageDirectory,
+      },
+    );
+    let installedPackageDirectory = join(
+      packageDirectory,
+      "node_modules",
+      "reg-cli",
+    );
+    const runtimeRoot = realpathSync(runtime);
+    if (!isRealDirectory(installedPackageDirectory))
+      throw new Error("npm did not install the pinned reg-cli package");
+    installedPackageDirectory = realpathSync(installedPackageDirectory);
+    if (!pathWithin(runtimeRoot, installedPackageDirectory))
+      throw new Error("pinned reg-cli package escaped the runtime directory");
+    const manifestPath = join(installedPackageDirectory, "package.json");
+    if (!isRegularFile(manifestPath))
+      throw new Error("pinned reg-cli package metadata is missing");
+    let manifest: Record<string, unknown>;
+    try {
+      const parsed: unknown = JSON.parse(readFileSync(manifestPath, "utf8"));
+      if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+        throw new Error("not an object");
+      manifest = parsed as Record<string, unknown>;
+    } catch {
+      throw new Error("pinned reg-cli package metadata is invalid");
+    }
+    if (manifest.version !== REG_CLI_VERSION)
+      throw new Error("npm installed an unexpected reg-cli version");
+    const bin = manifest.bin;
+    const entry =
+      bin && typeof bin === "object" && !Array.isArray(bin)
+        ? (bin as Record<string, unknown>)["reg-cli"]
+        : undefined;
+    if (
+      typeof entry !== "string" ||
+      isAbsolute(entry) ||
+      /^[A-Za-z]:[\\/]/.test(entry) ||
+      entry.split(/[\\/]/).includes("..")
+    )
+      throw new Error("pinned reg-cli package has no expected executable");
+    let executable: string;
+    try {
+      executable = realpathSync(resolve(installedPackageDirectory, entry));
+    } catch {
+      throw new Error("pinned reg-cli executable is missing");
+    }
+    if (
+      !pathWithin(installedPackageDirectory, executable) ||
+      !isRegularFile(executable)
+    )
+      throw new Error("pinned reg-cli executable is missing");
+    runSandboxedCommand(
+      directory,
+      [
+        node,
+        executable,
+        "actual",
+        "expected",
+        "diff",
+        "-R",
+        "report.html",
+        "-J",
+        "reg.json",
+        "-I",
+      ],
+      {
+        runtimeDir: runtime,
+        env,
+        allowNetwork: false,
+        label: "reg-cli",
+        additionalReadPaths: [node],
+        includeSnapshotReads: true,
+        workingDirectory: directory,
+      },
+    );
+    completed = true;
+    return { runtimeName: runtime.split("/").at(-1) ?? "", runtimeIdentity };
+  } finally {
+    if (!completed) removeStagingPath(runtime, runtimeIdentity);
+  }
+};