@warpgogol/forge 2.7.0 → 2.8.1

package/src/types.ts

@@ -0,0 +1,221 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Canonical forge runtime types — autonomous, no @warpgogol/* dependencies.
+Structurally compatible with @warpgogol/site-kernel types so that forge modules
+can be registered in a Warpgogol kernel without direct dependency.</purpose>
+<non-goals>
+  <item>Do not import from @warpgogol/site-kernel or any @warpgogol/* package.</item>
+  <item>Do not add Warpgogol-specific fields to ForgeRuntimeContext — keep it minimal and portable.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>Initial canonical forge types: ForgeCommandInput, ForgeCommandResult, ForgeRuntimeContext, ForgeFlagSpec, Diagnostic, CommandRegistry, ForgeLogger.</item>
+  <item>RFC-0518: add GateMetadata, GateSeverity, GatePhase, GateConditional types and optional gate field to ForgeCommandMetadata (structurally compatible with @warpgogol/site-kernel).</item>
+</CHANGE_SUMMARY>
+*/
+
+// ---------------------------------------------------------------------------
+// Command input / output
+// ---------------------------------------------------------------------------
+
+export type ForgeFlagValue = boolean | string | string[];
+
+export interface ForgeCommandInput {
+  argv: string[];
+  flags: Record<string, ForgeFlagValue>;
+}
+
+export interface ForgeCommandTiming {
+  durationMs?: number;
+  startedAt?: string;
+  endedAt?: string;
+}
+
+export interface ForgeNextStep {
+  action: string;
+  kind: "required" | "optional";
+}
+
+export interface ForgeCommandResult<TData = unknown> {
+  data?: TData;
+  nextSteps?: ForgeNextStep[];
+  exitCode?: number;
+  summary?: string;
+  timing?: ForgeCommandTiming;
+}
+
+// ---------------------------------------------------------------------------
+// Flag specs (RFC-0260 lineage)
+// ---------------------------------------------------------------------------
+
+export interface ForgeFlagSpec {
+  kind: "boolean" | "string" | "string[]";
+  required?: boolean;
+  default?: ForgeFlagValue;
+  description: string;
+}
+
+// ---------------------------------------------------------------------------
+// Command metadata / definition
+// ---------------------------------------------------------------------------
+
+export type ForgeCommandScope = "app" | "workspace";
+
+export interface ForgeCommandMetadata {
+  description: string;
+  scope: ForgeCommandScope;
+  mutatesState?: boolean;
+  requiresNetwork?: boolean;
+  supportsAllSites?: boolean;
+  timeoutMs?: number;
+  expectedDurationMs?: number;
+  longRunning?: boolean;
+  cacheable?: boolean;
+  hidden?: boolean;
+  /**
+   * RFC-0518: declarative gate metadata. Optional. Structurally compatible
+   * with GateMetadata from @warpgogol/site-kernel. Does NOT affect execution.
+   */
+  gate?: GateMetadata;
+}
+
+// ---------------------------------------------------------------------------
+// RFC-0518: declarative gate metadata (structurally compatible with @warpgogol/site-kernel)
+// ---------------------------------------------------------------------------
+
+export type GateSeverity = "error" | "warning" | "mixed";
+export type GatePhase = "author" | "postbuild" | "workspace" | "mission" | "release";
+
+export interface GateConditional {
+  kind: "entitlement" | "flag" | "config";
+  ref: string;
+  description: string;
+}
+
+export interface GateMetadata {
+  severity: GateSeverity;
+  phase: GatePhase;
+  conditional?: GateConditional;
+  surfaces?: string[];
+  rules?: string[];
+  blocks?: string[];
+}
+
+export interface ForgeRegisteredCommandInfo extends ForgeCommandMetadata {
+  name: string;
+  provider: "workspace" | "site";
+  siteName?: string;
+  module?: string;
+  flags?: Record<string, ForgeFlagSpec>;
+  reads?: string[];
+  writes?: string[];
+  hidden?: boolean;
+}
+
+export interface ForgeCommandDefinition<TData = unknown> extends ForgeCommandMetadata {
+  name: string;
+  flags?: Record<string, ForgeFlagSpec>;
+  reads?: string[];
+  writes?: string[];
+  execute(
+    input: ForgeCommandInput,
+    context: ForgeRuntimeContext,
+  ): Promise<void | ForgeCommandResult<TData>> | void | ForgeCommandResult<TData>;
+}
+
+// ---------------------------------------------------------------------------
+// Diagnostic (RFC-0203 lineage)
+// ---------------------------------------------------------------------------
+
+export type DiagnosticSeverity = "error" | "warning" | "info";
+
+export interface DiagnosticEvidence {
+  kind: "rule" | "rendered" | "source" | "config" | "cache" | "runtime";
+  ruleFile?: string;
+  ruleId?: string;
+  file?: string;
+  url?: string;
+  snippet?: string;
+}
+
+export interface Diagnostic {
+  ruleId: string;
+  severity: DiagnosticSeverity;
+  message: string;
+  file?: string;
+  line?: number;
+  column?: number;
+  fixHint?: string;
+  evidence?: DiagnosticEvidence[];
+  data?: Record<string, unknown>;
+  id?: string;
+  blockId?: string;
+  suggestion?: string;
+}
+
+export interface CheckResult {
+  command: string;
+  status: "pass" | "warn" | "fail";
+  diagnostics: Diagnostic[];
+  summary: { error: number; warning: number; info: number };
+}
+
+// ---------------------------------------------------------------------------
+// Logger — minimal, structurally compatible with KernelLogger
+// ---------------------------------------------------------------------------
+
+export interface ForgeLogger {
+  section(message: string, details?: unknown): void;
+  info(message: string, details?: unknown): void;
+  warn(message: string, details?: unknown): void;
+  error(message: string, details?: unknown): void;
+  success(message: string, details?: unknown): void;
+}
+
+// ---------------------------------------------------------------------------
+// CommandRegistry — interface injection for command discovery
+// ---------------------------------------------------------------------------
+
+export interface CommandRegistry {
+  listCommandNames(): string[];
+  listCommands(): ForgeRegisteredCommandInfo[];
+  getCommand(name: string): ForgeCommandDefinition | undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Runtime context — minimal, portable
+// ---------------------------------------------------------------------------
+
+export type ForgeOutputFormat = "pretty" | "json";
+
+export interface ForgeSiteContext {
+  name: string;
+  directory: string;
+  toolsDirectory: string;
+  configPath?: string;
+  packageName?: string;
+}
+
+export interface ForgeRuntimeContext {
+  workspaceRoot: string;
+  logger: ForgeLogger;
+  dryRun: boolean;
+  outputFormat: ForgeOutputFormat;
+  /**
+   * Optional command registry — provided by the runner (forge CLI or site-kernel).
+   * Forge commands that need to discover other commands (e.g. rfc lifecycle validation)
+   * access this through the context instead of importing a kernel-specific function.
+   */
+  commandRegistry?: CommandRegistry;
+  /** Optional target site/app context — provided when running in app-scoped mode. */
+  site?: ForgeSiteContext;
+  /** True only when --site <name> was passed explicitly by the caller. */
+  siteExplicit?: boolean;
+  /**
+   * Optional forge root override — provided when a command is called from
+   * another command (e.g. forge.create delegates to forge.init and forge.scaffold
+   * in a new directory where resolveForgeRoot would fail). When set, handlers
+   * use this instead of calling resolveForgeRoot(workspaceRoot).
+   */
+  forgeRoot?: string;
+}

package/src/utils/fs-atomic.ts

@@ -0,0 +1,93 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Atomic file-write primitive — canonical forge utility. Writes to a temp
+file then renames, with bounded retry for Windows EPERM/EBUSY.</purpose>
+<non-goals>
+  <item>Do not provide cross-process locks — convergent atomic writes are sufficient.</item>
+  <item>Do not fall back to non-atomic writes — fail loudly.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>Moved from @warpgogol/site-kernel/fs-atomic to forge as canonical source (dependency inversion).</item>
+</CHANGE_SUMMARY>
+*/
+
+import { writeFile, rename as fsRename, unlink } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { dirname, join, basename } from "node:path";
+import { randomBytes } from "node:crypto";
+
+export interface WriteFileAtomicOptions {
+  retries?: number;
+}
+
+let renameImpl: typeof fsRename = fsRename;
+
+export function __setRenameImplForTests(impl: typeof fsRename | undefined): void {
+  renameImpl = impl ?? fsRename;
+}
+
+const DEFAULT_RETRIES = 10;
+const RETRY_BACKOFF_MS = 50;
+const RETRYABLE_CODES = new Set(["EPERM", "EBUSY"]);
+
+function isRetryableError(error: unknown): boolean {
+  if (!error || typeof error !== "object") return false;
+  const code = (error as NodeJS.ErrnoException).code;
+  return typeof code === "string" && RETRYABLE_CODES.has(code);
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function makeTempPath(filePath: string): string {
+  const dir = dirname(filePath);
+  const name = basename(filePath);
+  const random = randomBytes(6).toString("hex");
+  return join(dir, `${name}.${random}.tmp`);
+}
+
+export async function writeFileAtomic(
+  filePath: string,
+  content: string | Uint8Array,
+  options?: WriteFileAtomicOptions,
+): Promise<void> {
+  const retries = options?.retries ?? DEFAULT_RETRIES;
+  const tempPath = makeTempPath(filePath);
+  let tempWritten = false;
+
+  try {
+    await writeFile(tempPath, content);
+    tempWritten = true;
+
+    let attempt = 0;
+    for (;;) {
+      try {
+        await renameImpl(tempPath, filePath);
+        return;
+      } catch (error) {
+        if (attempt >= retries || !isRetryableError(error)) {
+          throw error;
+        }
+        attempt += 1;
+        if (existsSync(filePath)) {
+          try {
+            await unlink(filePath);
+          } catch {
+            // If unlink also fails, the retry loop will try again.
+          }
+        }
+        await sleep(RETRY_BACKOFF_MS * attempt);
+      }
+    }
+  } finally {
+    if (tempWritten) {
+      try {
+        await unlink(tempPath);
+      } catch {
+        // Expected in the success path (temp file already renamed away).
+      }
+    }
+  }
+}

package/src/utils/fs-idempotent.ts

@@ -0,0 +1,41 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Idempotent file-write primitive — canonical forge utility. Writes only
+when file content differs, delegating to writeFileAtomic for the actual write.
+Reduces unnecessary disk writes and git churn in Compass and Werkstatt commands.</purpose>
+<non-goals>
+  <item>Do not provide cross-process locks — convergent atomic writes are sufficient.</item>
+  <item>Do not fall back to non-atomic writes — fail loudly.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0556: moved from @warpgogol/site-kernel/fs-idempotent to forge as canonical source (dependency inversion).</item>
+  <item>RFC-0603: extended to accept Uint8Array (Buffer) content for idempotent binary file writes — PNG preview images.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { readFile } from "node:fs/promises";
+import { writeFileAtomic } from "./fs-atomic.ts";
+
+export async function writeFileIfChanged(
+  filePath: string,
+  content: string | Uint8Array,
+): Promise<"written" | "unchanged"> {
+  try {
+    if (typeof content === "string") {
+      const existing = await readFile(filePath, "utf8");
+      if (existing === content) {
+        return "unchanged";
+      }
+    } else {
+      const existing = await readFile(filePath);
+      if (Buffer.compare(existing, Buffer.from(content)) === 0) {
+        return "unchanged";
+      }
+    }
+  } catch {
+    // File does not exist — proceed to write.
+  }
+  await writeFileAtomic(filePath, content);
+  return "written";
+}

package/src/utils/fs-trash-sync.ts

@@ -0,0 +1,37 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Synchronous trash-can deletion — shells out to `trash-put` (trash-cli)
+on Linux/macOS and PowerShell Recycle Bin on Windows. Used by synchronous
+code paths that cannot use the async `trash` npm package.</purpose>
+<non-goals>
+  <item>Do not use for async code paths — use trashPath from fs-trash.ts instead.</item>
+  <item>Requires `trash-put` (trash-cli) installed on Linux/macOS. On Windows, uses PowerShell Recycle Bin API (no external binary needed).</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>Initial implementation: sync wrapper for `trash-put` (Linux/macOS) and PowerShell Recycle Bin (Windows).</item>
+</CHANGE_SUMMARY>
+*/
+
+import { existsSync, statSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+
+export function trashSync(targetPath: string): void {
+  if (!existsSync(targetPath)) return;
+  if (process.platform === "win32") {
+    const isDir = statSync(targetPath).isDirectory();
+    const method = isDir ? "DeleteDirectory" : "DeleteFile";
+    const escaped = targetPath.replace(/'/g, "''");
+    execFileSync(
+      "powershell",
+      [
+        "-NoProfile",
+        "-Command",
+        `Add-Type -AssemblyName Microsoft.VisualBasic; [Microsoft.VisualBasic.FileIO.FileSystem]::${method}('${escaped}', 'OnlyErrorDialogs', 'SendToRecycleBin')`,
+      ],
+      { stdio: "pipe" },
+    );
+  } else {
+    execFileSync("trash-put", [targetPath], { stdio: "pipe" });
+  }
+}

package/src/utils/fs-trash.ts

@@ -0,0 +1,24 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Trash-can deletion primitive — moves files/directories to the OS
+trash/recycle bin instead of permanently deleting them. Uses the `trash`
+npm package which implements the FreeDesktop.org Trash specification on
+Linux (no external `trash-put` binary required) and the Recycle Bin on
+Windows.</purpose>
+<non-goals>
+  <item>Do not implement trash eviction or retention policies — the OS manages that.</item>
+  <item>Do not use for ephemeral cleanup (lock files, temp files, atomic write leftovers) — those are system-internal and should use fs.unlink directly.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>Initial implementation: wraps npm `trash` package with glob disabled for safe path handling.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { existsSync } from "node:fs";
+import trash from "trash";
+
+export async function trashPath(targetPath: string): Promise<void> {
+  if (!existsSync(targetPath)) return;
+  await trash(targetPath, { glob: false });
+}

package/src/utils/fs.ts

@@ -0,0 +1,74 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Trivial filesystem utilities — inlined from @warpgogol/share to avoid dependency.</purpose>
+<non-goals>
+  <item>Do not add non-filesystem utilities here — use dedicated utility modules.</item>
+  <item>Do not introduce @warpgogol/* imports — this package must remain dependency-free.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>Initial inline of collectFiles, fileExists from @warpgogol/werkstatt-shared/share/fs.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { readdir, stat } from "node:fs/promises";
+import { join } from "node:path";
+
+export interface CollectFilesOptions {
+  extensions?: string[];
+  ignore?: (name: string) => boolean;
+  withDirs?: boolean;
+}
+
+function defaultIgnore(name: string): boolean {
+  return name.startsWith("-") || name.startsWith("old-");
+}
+
+export async function collectFiles(
+  root: string,
+  options: CollectFilesOptions = {},
+): Promise<string[]> {
+  const { extensions, ignore = defaultIgnore, withDirs = false } = options;
+  const results: string[] = [];
+
+  // fs.walk.lint: allow — this is the canonical collectFiles implementation,
+  // inlined from @warpgogol/werkstatt-shared/share/fs to keep @warpgogol/forge dependency-free (RFC-0303).
+  async function walk(dir: string): Promise<void> {
+    let entries;
+    try {
+      entries = await readdir(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+
+    for (const entry of entries) {
+      if (ignore(entry.name)) continue;
+
+      const full = join(dir, entry.name);
+
+      if (entry.isDirectory()) {
+        if (withDirs) results.push(full);
+        await walk(full);
+        continue;
+      }
+
+      if (!entry.isFile()) continue;
+
+      if (extensions && !extensions.some((ext) => entry.name.endsWith(ext))) continue;
+
+      results.push(full);
+    }
+  }
+
+  await walk(root);
+  return results;
+}
+
+export async function fileExists(path: string): Promise<boolean> {
+  try {
+    await stat(path);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/utils/generated-marker.ts

@@ -0,0 +1,166 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Canonical GENERATED_MARKER constant and advisory header builder for
+generated-file governance. Moved from @warpgogol/site-kernel to forge as canonical
+source (dependency inversion).</purpose>
+<non-goals>
+  <item>Do not perform file I/O — operates on in-memory content strings only.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>Moved from @warpgogol/site-kernel/generated-marker to forge as canonical source.</item>
+  <item>Added optional commandPrefix to GeneratedHeaderInput — defaults to "forge" for autonomous mode; site-kernel passes "pnpm exec werkstatt run".</item>
+</CHANGE_SUMMARY>
+*/
+
+export const GENERATED_MARKER =
+  "GENERATED. Do not change this line unless the file contains project specific changes.";
+
+export function hasGeneratedMarker(content: string): boolean {
+  return content.includes(GENERATED_MARKER);
+}
+
+export interface StripGeneratedMarkerResult {
+  changed: boolean;
+  content: string;
+}
+
+function escapeRegex(str: string): string {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+const DO_NOT_EDIT_LINE = "DO NOT EDIT THIS FILE. Changes are overwritten on the next build.";
+
+export function stripGeneratedMarker(content: string): StripGeneratedMarkerResult {
+  const raw = GENERATED_MARKER;
+  let result = content;
+  let changed = false;
+
+  const applyAll = (patterns: RegExp[]): void => {
+    for (const pattern of patterns) {
+      const next = result.replace(pattern, "");
+      if (next !== result) {
+        changed = true;
+        result = next;
+      }
+    }
+  };
+
+  applyAll([
+    new RegExp(`<!--[ \\t]*\\n[\\s\\S]*?${escapeRegex(raw)}[\\s\\S]*?-->\\n?`, "g"),
+    new RegExp(`/\\*[ \\t]*\\n[\\s\\S]*?${escapeRegex(raw)}[\\s\\S]*?\\*/\\n?`, "g"),
+  ]);
+
+  for (const token of ["//", "#"]) {
+    const t = escapeRegex(token);
+    const advisoryLine = (suffix: string): string => `(?:[ \\t]*${t}[ \\t]*${suffix}\\n)?`;
+    const pattern = new RegExp(
+      `^[ \\t]*${t}[ \\t]*${escapeRegex(raw)}\\n` +
+        advisoryLine(escapeRegex(DO_NOT_EDIT_LINE)) +
+        advisoryLine("Owner command:.*") +
+        advisoryLine("Edit instead:.*") +
+        advisoryLine("Regenerate:.*"),
+      "gm",
+    );
+    applyAll([pattern]);
+  }
+
+  applyAll([
+    new RegExp(`^\\s*<!--\\s*${escapeRegex(raw)}\\s*-->\\n?`, "gm"),
+    new RegExp(`^\\s*//\\s*${escapeRegex(raw)}\\n?`, "gm"),
+    new RegExp(`^\\s*/\\*\\s*${escapeRegex(raw)}\\s*\\*/\\n?`, "gm"),
+    new RegExp(`^\\s*#\\s*${escapeRegex(raw)}\\n?`, "gm"),
+    new RegExp(`^\\s*${escapeRegex(raw)}\\n?`, "gm"),
+  ]);
+
+  if (result.includes(raw)) {
+    const next = result.split(raw).join("");
+    if (next !== result) {
+      changed = true;
+      result = next;
+    }
+  }
+
+  return { changed, content: result };
+}
+
+export interface GeneratedHeaderInput {
+  filePath: string;
+  ownerCommand: string;
+  templatePath?: string;
+  site?: string;
+  /**
+   * Command prefix for the regenerate hint. Defaults to "forge" (autonomous mode).
+   * Site-kernel callers pass "pnpm exec werkstatt run" for Warpgogol context.
+   */
+  commandPrefix?: string;
+}
+
+type GeneratedHeaderCommentStyle = "line-slash" | "line-hash" | "block-html" | "block-css";
+
+function commentStyleForPath(filePath: string): GeneratedHeaderCommentStyle {
+  const lower = filePath.toLowerCase().replace(/\\/g, "/");
+  const base = lower.slice(lower.lastIndexOf("/") + 1);
+  if (
+    base === ".gitattributes" ||
+    base === "_headers" ||
+    base === "_redirects" ||
+    base.endsWith(".txt") ||
+    base.endsWith(".yml") ||
+    base.endsWith(".yaml")
+  ) {
+    return "line-hash";
+  }
+  if (base.endsWith(".md")) return "block-html";
+  if (base.endsWith(".css")) return "block-css";
+  return "line-slash";
+}
+
+export function buildGeneratedHeader(input: GeneratedHeaderInput): string {
+  const style = commentStyleForPath(input.filePath);
+  const prefix = input.commandPrefix ?? "forge";
+  const regenerateCommand = input.site
+    ? `${prefix} ${input.ownerCommand} --site ${input.site}`
+    : `${prefix} ${input.ownerCommand}`;
+  const editInstead = input.templatePath
+    ? `Edit instead: ${input.templatePath}`
+    : `Edit instead: the ${input.ownerCommand} generator source (not this file).`;
+
+  const lines = [
+    GENERATED_MARKER,
+    DO_NOT_EDIT_LINE,
+    `Owner command: ${input.ownerCommand}`,
+    editInstead,
+    `Regenerate:   ${regenerateCommand}`,
+  ];
+
+  switch (style) {
+    case "line-slash":
+      return `${lines.map((line) => `// ${line}`).join("\n")}\n`;
+    case "line-hash":
+      return `${lines.map((line) => `# ${line}`).join("\n")}\n`;
+    case "block-css":
+      return `/*\n${lines.map((line) => `  ${line}`).join("\n")}\n*/\n`;
+    case "block-html":
+      return `<!--\n${lines.map((line) => `  ${line}`).join("\n")}\n-->\n`;
+  }
+}
+
+export function isGeneratedMarkerTextCandidate(filePath: string): boolean {
+  const ext = filePath.slice(filePath.lastIndexOf(".")).toLowerCase();
+  const TEXT_EXTS = new Set([
+    ".txt",
+    ".xml",
+    ".md",
+    ".yml",
+    ".yaml",
+    ".css",
+    ".js",
+    ".mjs",
+    ".ts",
+    ".json",
+    ".html",
+    ".astro",
+  ]);
+  return TEXT_EXTS.has(ext);
+}

package/src/utils/hash.ts

@@ -0,0 +1,19 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Trivial hash utility — inlined from @warpgogol/fingerprint to avoid dependency.</purpose>
+<non-goals>
+  <item>Do not add non-hash utilities here — use dedicated utility modules.</item>
+  <item>Do not introduce @warpgogol/* imports — this package must remain dependency-free.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>Initial inline of byteHash from @warpgogol/fingerprint/primitives.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { createHash } from "node:crypto";
+
+export function byteHash(bytes: Uint8Array | string): string {
+  const input = typeof bytes === "string" ? Buffer.from(bytes, "utf8") : bytes;
+  return `sha256:${createHash("sha256").update(input).digest("hex")}`;
+}