@termix-ssh/plugin-sdk 1.0.0

package/README.md

@@ -0,0 +1,52 @@
+<div align="center">
+
+<img src="https://raw.githubusercontent.com/Termix-SSH/Termix/main/public/icon.svg" width="120" height="120" alt="Termix Logo" />
+
+<h1>Termix Plugin SDK</h1>
+
+<p>Everything you need to build a Termix plugin</p>
+
+</div>
+
+<br />
+
+## Overview
+
+`@termix-ssh/plugin-sdk` is what every [Termix](https://github.com/Termix-SSH/Termix) plugin builds against, including the ones that ship with Termix. It has the types for a plugin's backend and frontend, table definitions, the manifest schema, test helpers, and the `termix-plugin` CLI. The easiest way to start is the [Termix Plugin Template](https://github.com/Termix-SSH/Termix-Plugin-Template).
+
+<br />
+
+## Installation
+
+```bash
+npm install --save-dev @termix-ssh/plugin-sdk
+```
+
+<br />
+
+## CLI
+
+```bash
+npx termix-plugin build                  # bundle dist/backend.js and dist/frontend.js
+npx termix-plugin test                   # run the plugin's Vitest suite
+npx termix-plugin validate               # check manifest.json and the files it names
+npx termix-plugin migrations             # write migrations from the table definitions
+npx termix-plugin pack                   # write <id>-<version>.tmxplug
+npx termix-plugin sign <file.tmxplug>    # sign it, needs TERMIX_PLUGIN_SIGNING_KEY
+npx termix-plugin verify <file.tmxplug> --key <base64>   # check a signature
+npx termix-plugin keygen --out <dir>     # make a new signing key pair
+```
+
+<br />
+
+## Support
+
+To report a bug or request a feature, open a [support ticket](https://github.com/Termix-SSH/Support/issues/new/choose). You need to be logged in to GitHub. Please be as detailed as possible, preferably in English.
+
+For discussions and questions, join the [Discord](https://discord.gg/jVQGdvHDrf) server.
+
+<br />
+
+## License
+
+Distributed under the Apache License Version 2.0. See [LICENSE](https://github.com/Termix-SSH/Termix/blob/main/LICENSE) for more information.

package/cli/commands/build.mjs

@@ -0,0 +1,246 @@
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import * as esbuild from "esbuild";
+import { BACKEND_EXTERNALS, FRONTEND_EXTERNALS } from "../lib/externals.mjs";
+import { staticUrlImports } from "../lib/static-url-imports.mjs";
+import { readManifest, resolveEntry, copyDir } from "../lib/plugin-dir.mjs";
+
+const BACKEND_ENTRIES = [
+  "src/backend/index.ts",
+  "src/backend/index.mjs",
+  "src/backend/index.js",
+];
+const FRONTEND_ENTRIES = [
+  "src/frontend/index.tsx",
+  "src/frontend/index.ts",
+  "src/frontend/index.mjs",
+  "src/frontend/index.js",
+];
+
+/**
+ * A bundled CommonJS package that calls require("react/jsx-runtime") (or any
+ * other host-provided package) cannot reach it: the package is external, and
+ * esbuild's ESM output has no require, so the plugin throws "Dynamic require
+ * is not supported" as soon as it loads. Each such require is pointed at a
+ * small ES module that imports the external and re-exports it, which esbuild
+ * can hand to CommonJS code.
+ */
+export function externalRequireInterop(externals) {
+  const names = new Set(externals.filter((name) => !name.includes("*")));
+  return {
+    name: "termix-external-require",
+    setup(build) {
+      build.onResolve({ filter: /.*/ }, (args) => {
+        if (args.kind !== "require-call" || !names.has(args.path)) return;
+        return { path: args.path, namespace: "termix-external-require" };
+      });
+      build.onLoad(
+        { filter: /.*/, namespace: "termix-external-require" },
+        (args) => {
+          const id = JSON.stringify(args.path);
+          return {
+            contents: `import * as mod from ${id};\nexport * from ${id};\nexport default mod.default ?? mod;\n`,
+            loader: "js",
+          };
+        },
+      );
+    },
+  };
+}
+
+const SDK_PATCHES = path.join(
+  path.dirname(fileURLToPath(import.meta.url)),
+  "..",
+  "patches",
+);
+
+/**
+ * Patches a dependency before it is bundled, so the fix ships inside the
+ * plugin rather than depending on whoever ran npm install.
+ *
+ * package.json "termix": { "patches": ["xterm-android-ime"] } names patches
+ * the SDK ships for libraries several plugins share. Any .cjs file in the
+ * plugin's own patches/ folder runs too. Every patch must be safe to run
+ * twice.
+ */
+export function applyPatches(cwd, pluginId) {
+  const pkgPath = path.join(cwd, "package.json");
+  const pkg = fs.existsSync(pkgPath)
+    ? JSON.parse(fs.readFileSync(pkgPath, "utf8"))
+    : {};
+  const scripts = [];
+  for (const name of pkg.termix?.patches ?? []) {
+    const file = path.join(SDK_PATCHES, `${name}.cjs`);
+    if (!/^[a-z0-9-]+$/.test(name) || !fs.existsSync(file)) {
+      throw new Error(`${pluginId}: the SDK has no patch named "${name}"`);
+    }
+    scripts.push(file);
+  }
+  const own = path.join(cwd, "patches");
+  if (fs.existsSync(own)) {
+    for (const file of fs.readdirSync(own).sort()) {
+      if (file.endsWith(".cjs")) scripts.push(path.join(own, file));
+    }
+  }
+  for (const file of scripts) {
+    const result = spawnSync(process.execPath, [file], {
+      cwd,
+      env: { ...process.env, TERMIX_PATCH_ROOT: cwd },
+      stdio: "inherit",
+    });
+    if (result.status !== 0) {
+      throw new Error(`${pluginId}: patch ${path.basename(file)} failed`);
+    }
+  }
+}
+
+const THEME_CSS = path.join(
+  path.dirname(fileURLToPath(import.meta.url)),
+  "..",
+  "..",
+  "dist",
+  "host",
+  "theme.css",
+);
+
+/**
+ * Compiles the Tailwind classes the plugin's frontend uses into
+ * dist/frontend.css, against the theme core ships in the SDK. Core only
+ * compiles its own classes, so a class no core file happens to use would
+ * otherwise have no CSS at all. Appended to whatever CSS the bundle already
+ * produced (a library's stylesheet the plugin imports).
+ */
+/**
+ * Moves a plugin's Tailwind layers under their own names. Core orders
+ * termix-plugin-utilities above its base styles and below its own utilities,
+ * so a plugin's copy of `.hidden` can never beat core's `md:flex` just
+ * because the plugin's file loaded later.
+ */
+export function lowerPluginLayers(css) {
+  return css.replace(
+    /@layer (properties|utilities)(?=[\s{;,])/g,
+    "@layer termix-plugin-$1",
+  );
+}
+
+export async function buildTailwind(cwd, outDir) {
+  const { compile, optimize } = await import("@tailwindcss/node");
+  const { Scanner } = await import("@tailwindcss/oxide");
+  if (!fs.existsSync(THEME_CSS)) {
+    throw new Error("The SDK theme is missing. Run: npm run build:sdk");
+  }
+  const input = [
+    '@import "tailwindcss/theme.css" theme(reference);',
+    `@import ${JSON.stringify(THEME_CSS.replaceAll("\\", "/"))};`,
+    '@import "tailwindcss/utilities.css" layer(utilities);',
+  ].join("\n");
+  const compiler = await compile(input, {
+    base: path.dirname(THEME_CSS),
+    onDependency: () => {},
+  });
+  const scanner = new Scanner({
+    sources: [
+      {
+        base: path.join(cwd, "src", "frontend"),
+        pattern: "**/*",
+        negated: false,
+      },
+    ],
+  });
+  // Flattened and minified the way core's own CSS is, so it does not rely
+  // on native CSS nesting.
+  const css = lowerPluginLayers(
+    optimize(compiler.build(scanner.scan()), { minify: true }).code.trim(),
+  );
+  if (!css) return;
+  const target = path.join(outDir, "frontend.css");
+  const existing = fs.existsSync(target) ? fs.readFileSync(target, "utf8") : "";
+  fs.writeFileSync(target, `${existing}${existing ? "\n" : ""}${css}\n`);
+}
+
+export async function build({ cwd }) {
+  const manifest = readManifest(cwd);
+  const pluginId = manifest.id ?? path.basename(cwd);
+  const outDir = path.join(cwd, "dist");
+
+  applyPatches(cwd, pluginId);
+
+  fs.rmSync(outDir, { recursive: true, force: true });
+  fs.mkdirSync(outDir, { recursive: true });
+
+  const backendEntry = resolveEntry(cwd, BACKEND_ENTRIES);
+  if (!backendEntry) {
+    throw new Error(
+      `${pluginId}: no backend entry (looked for ${BACKEND_ENTRIES.join(", ")})`,
+    );
+  }
+
+  await esbuild.build({
+    entryPoints: [backendEntry],
+    outfile: path.join(outDir, "backend.js"),
+    bundle: true,
+    format: "esm",
+    platform: "node",
+    target: "node22",
+    sourcemap: true,
+    logLevel: "warning",
+    // A native dependency's compiled .node binary is resolved by the
+    // package's own relative paths, which break once esbuild inlines its JS
+    // elsewhere. Declaring it in nativeDependencies keeps it a real
+    // node_modules import instead, resolved at runtime like a host-provided
+    // package.
+    external: [...BACKEND_EXTERNALS, ...(manifest.nativeDependencies ?? [])],
+    // Bundled CJS deps still call require() for Node builtins at runtime.
+    // ESM has no ambient require, so give esbuild's require shim a real one.
+    banner: {
+      js: "import { createRequire as __termixCreateRequire } from 'node:module'; const require = __termixCreateRequire(import.meta.url);",
+    },
+  });
+
+  // Without this Node finds the host's typeless package.json, tries backend.js
+  // as CommonJS first and warns before reparsing it as ESM.
+  fs.writeFileSync(
+    path.join(outDir, "package.json"),
+    `${JSON.stringify({ type: "module" }, null, 2)}\n`,
+  );
+
+  const frontendEntry = resolveEntry(cwd, FRONTEND_ENTRIES);
+  if (frontendEntry) {
+    await esbuild.build({
+      entryPoints: [frontendEntry],
+      outfile: path.join(outDir, "frontend.js"),
+      bundle: true,
+      format: "esm",
+      platform: "browser",
+      target: "es2022",
+      jsx: "automatic",
+      sourcemap: true,
+      logLevel: "warning",
+      external: FRONTEND_EXTERNALS,
+      // Vite replaces these in the dev server; a plugin bundle has to have
+      // them too, or code that reads them throws when the plugin loads.
+      define: {
+        "process.env.NODE_ENV": '"production"',
+        "import.meta.env.DEV": "false",
+        "import.meta.env.PROD": "true",
+        "import.meta.env.MODE": '"production"',
+        "import.meta.env.SSR": "false",
+        "import.meta.env":
+          '{"DEV":false,"PROD":true,"MODE":"production","SSR":false,"BASE_URL":"/"}',
+      },
+      plugins: [
+        externalRequireInterop(FRONTEND_EXTERNALS),
+        staticUrlImports({ outDir }),
+      ],
+    });
+  }
+
+  if (frontendEntry) await buildTailwind(cwd, outDir);
+
+  copyDir(path.join(cwd, "locales"), path.join(outDir, "locales"));
+  copyDir(path.join(cwd, "migrations"), path.join(outDir, "migrations"));
+
+  console.log(`built ${pluginId}`);
+}

package/cli/commands/migrations.mjs

@@ -0,0 +1,248 @@
+/**
+ * Generates a plugin's migrations from its table definitions.
+ *
+ * Not drizzle-kit. Core's own SQLite schema is hand-written DDL and only the
+ * client-server engines use drizzle migrations, so a plugin on drizzle-kit
+ * would still need a hand-rolled SQLite path, three configs and three
+ * generated schema modules. This diffs the definitions against a committed
+ * snapshot and writes plain SQL for all three dialects, which is what the
+ * server's runner applies.
+ *
+ * Usage, from a plugin directory:
+ *   termix-plugin migrations [name]
+ *   termix-plugin migrations --check    verifies nothing is undeclared
+ *
+ * The plugin exports its definitions from src/backend/tables.ts as `tables`.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import * as esbuild from "esbuild";
+import { BACKEND_EXTERNALS } from "../lib/externals.mjs";
+import { readManifest, resolveEntry } from "../lib/plugin-dir.mjs";
+
+const DIALECTS = ["sqlite", "postgres", "mysql"];
+
+const TABLE_ENTRIES = [
+  "src/backend/tables.ts",
+  "src/backend/tables.mjs",
+  "src/backend/tables.js",
+];
+
+/** Loads the plugin's table definitions by bundling them to a temp file. */
+async function loadDefinitions(cwd) {
+  const entry = resolveEntry(cwd, TABLE_ENTRIES);
+  if (!entry) return null;
+
+  // Emitted inside the plugin rather than in the system temp dir: the SDK
+  // stays external to the bundle, so the output has to sit somewhere node can
+  // resolve @termix-ssh/plugin-sdk from.
+  const outdir = fs.mkdtempSync(path.join(cwd, ".termix-tables-"));
+  const outfile = path.join(outdir, "tables.mjs");
+
+  try {
+    await esbuild.build({
+      entryPoints: [entry],
+      outfile,
+      bundle: true,
+      format: "esm",
+      platform: "node",
+      target: "node22",
+      logLevel: "warning",
+      external: BACKEND_EXTERNALS,
+    });
+
+    const module = await import(`file://${outfile.split(path.sep).join("/")}`);
+    const tables = module.tables ?? module.default;
+    if (!Array.isArray(tables)) {
+      throw new Error(
+        `${path.relative(cwd, entry)} must export a "tables" array of defineTable() results`,
+      );
+    }
+    return tables;
+  } finally {
+    fs.rmSync(outdir, { recursive: true, force: true });
+  }
+}
+
+function snapshotPath(cwd) {
+  return path.join(cwd, "migrations", "snapshot.json");
+}
+
+function readSnapshot(cwd) {
+  const file = snapshotPath(cwd);
+  if (!fs.existsSync(file)) return { version: 1, tables: {} };
+  return JSON.parse(fs.readFileSync(file, "utf8"));
+}
+
+/** What a definition looks like in the snapshot, so a diff can compare them. */
+function snapshotTable(definition) {
+  return {
+    columns: definition.columns,
+    indexes: definition.indexes,
+    ...(definition.adopts ? { adopts: definition.adopts } : {}),
+  };
+}
+
+function nextSequence(cwd) {
+  let highest = 0;
+  for (const dialect of DIALECTS) {
+    const dir = path.join(cwd, "migrations", dialect);
+    if (!fs.existsSync(dir)) continue;
+    for (const file of fs.readdirSync(dir)) {
+      const match = /^(\d{4})_/.exec(file);
+      if (match) highest = Math.max(highest, Number(match[1]));
+    }
+  }
+  return highest + 1;
+}
+
+/**
+ * What changed since the snapshot.
+ *
+ * New tables and new columns are generated. A changed or removed column is
+ * reported rather than guessed at: renames and type changes need a data
+ * decision this cannot make, so the author writes that migration by hand.
+ */
+function diff(previous, definitions) {
+  const created = [];
+  const added = [];
+  const manual = [];
+
+  for (const definition of definitions) {
+    const before = previous.tables[definition.name];
+    if (!before) {
+      created.push(definition);
+      continue;
+    }
+
+    for (const [property, column] of Object.entries(definition.columns)) {
+      const existing = before.columns[property];
+      if (!existing) {
+        added.push({ definition, property, column });
+        continue;
+      }
+      if (JSON.stringify(existing) !== JSON.stringify(column)) {
+        manual.push(`${definition.name}.${property} changed type or modifiers`);
+      }
+    }
+
+    for (const property of Object.keys(before.columns)) {
+      if (!definition.columns[property]) {
+        manual.push(`${definition.name}.${property} was removed`);
+      }
+    }
+  }
+
+  for (const name of Object.keys(previous.tables)) {
+    if (!definitions.some((definition) => definition.name === name)) {
+      manual.push(`table ${name} was removed`);
+    }
+  }
+
+  return { created, added, manual };
+}
+
+export async function migrations({ cwd, args }) {
+  const manifest = readManifest(cwd);
+  const pluginId = manifest.id ?? path.basename(cwd);
+  const check = args.includes("--check");
+  const name = args.find((arg) => !arg.startsWith("--")) ?? "update";
+
+  const definitions = await loadDefinitions(cwd);
+  if (definitions === null) {
+    console.log(`${pluginId}: no table definitions, nothing to generate`);
+    return;
+  }
+
+  const { LEGACY_TABLE_OWNERS } = await import(
+    new URL("../../dist/db.js", import.meta.url).href
+  );
+  for (const definition of definitions) {
+    if (
+      definition.adopts &&
+      LEGACY_TABLE_OWNERS[definition.adopts] !== pluginId
+    ) {
+      throw new Error(
+        `${pluginId}: table ${definition.name} adopts "${definition.adopts}", which belongs to the "${LEGACY_TABLE_OWNERS[definition.adopts]}" plugin`,
+      );
+    }
+  }
+
+  const { createTableSql, adoptTableSql, addColumnSql } = await loadEmitter();
+
+  const previous = readSnapshot(cwd);
+  const { created, added, manual } = diff(previous, definitions);
+
+  if (manual.length > 0) {
+    for (const problem of manual) console.error(`  ${problem}`);
+    throw new Error(
+      `${pluginId}: these changes need a hand-written migration, because a rename or a type change is a data decision.`,
+    );
+  }
+
+  if (created.length === 0 && added.length === 0) {
+    console.log(`${pluginId}: migrations are up to date`);
+    return;
+  }
+
+  if (check) {
+    throw new Error(
+      `${pluginId}: table definitions have changed but no migration was generated. Run: termix-plugin migrations`,
+    );
+  }
+
+  const sequence = String(nextSequence(cwd)).padStart(4, "0");
+  const file = `${sequence}_${name.replace(/[^a-z0-9_]/gi, "_").toLowerCase()}.sql`;
+
+  for (const dialect of DIALECTS) {
+    const statements = [];
+    for (const definition of created) {
+      // An adopted table renames the legacy one into place, creating it first
+      // on a fresh install, so existing rows are kept rather than copied.
+      statements.push(
+        ...(definition.adopts
+          ? adoptTableSql(dialect, pluginId, definition)
+          : createTableSql(dialect, pluginId, definition)),
+      );
+    }
+    for (const entry of added) {
+      statements.push(
+        addColumnSql(dialect, pluginId, entry.definition, entry.property),
+      );
+    }
+
+    const dir = path.join(cwd, "migrations", dialect);
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(
+      path.join(dir, file),
+      `-- ${pluginId} ${sequence}: ${name}\n-- Generated by termix-plugin migrations. Review before committing.\n\n${statements.join("\n")}\n`,
+    );
+  }
+
+  const snapshot = { version: 1, tables: {} };
+  for (const definition of definitions) {
+    snapshot.tables[definition.name] = snapshotTable(definition);
+  }
+  fs.writeFileSync(snapshotPath(cwd), `${JSON.stringify(snapshot, null, 2)}\n`);
+
+  console.log(
+    `${pluginId}: wrote ${DIALECTS.length} dialect files for ${sequence}_${name}`,
+  );
+}
+
+/**
+ * The DDL emitter, shared with the server.
+ *
+ * One mapping, two consumers: the SQL written here is the SQL the server's
+ * migration runner applies, so a second copy could drift into producing a
+ * migration the runner cannot reproduce.
+ */
+async function loadEmitter() {
+  const entry = new URL("../../dist/ddl.js", import.meta.url);
+  if (!fs.existsSync(fileURLToPath(entry))) {
+    throw new Error("The plugin SDK is not built yet. Run: npm run build:sdk");
+  }
+  return import(entry.href);
+}

package/cli/commands/pack.mjs

@@ -0,0 +1,42 @@
+import fs from "node:fs";
+import path from "node:path";
+import { readManifest } from "../lib/plugin-dir.mjs";
+import { collectFiles, createTmxplug } from "../lib/tmxplug.mjs";
+import { sha256 } from "../lib/signing.mjs";
+import { validate } from "./validate.mjs";
+
+function readOption(args, name) {
+  const index = args.indexOf(name);
+  if (index === -1) return null;
+  const value = args[index + 1];
+  if (!value) throw new Error(`${name} needs a value`);
+  return value;
+}
+
+/**
+ * Writes <id>-<version>.tmxplug. Validates first and refuses on any error,
+ * so a broken manifest never becomes a release.
+ */
+export async function pack({ cwd, args = [] }) {
+  const manifest = readManifest(cwd);
+  const pluginId = manifest.id ?? path.basename(cwd);
+  const version = manifest.version ?? "0.0.0";
+
+  if (!fs.existsSync(path.join(cwd, "dist", "backend.js"))) {
+    throw new Error(`${pluginId}: nothing built. Run termix-plugin build.`);
+  }
+
+  await validate({ cwd });
+
+  const outDir = path.resolve(cwd, readOption(args, "--out") ?? ".");
+  fs.mkdirSync(outDir, { recursive: true });
+  const outfile = path.join(outDir, `${pluginId}-${version}.tmxplug`);
+
+  const archive = createTmxplug(cwd, collectFiles(cwd));
+  fs.writeFileSync(outfile, archive);
+
+  console.log(`packed ${path.basename(outfile)}`);
+  console.log(`  size    ${archive.length}`);
+  console.log(`  sha256  ${sha256(archive).toString("hex")}`);
+  return outfile;
+}

package/cli/commands/sign.mjs

@@ -0,0 +1,83 @@
+import fs from "node:fs";
+import path from "node:path";
+import {
+  SIGNING_KEY_ENV,
+  generateKeyPair,
+  loadPrivateKey,
+  sha256,
+  signArtifact,
+  verifyArtifact,
+} from "../lib/signing.mjs";
+
+function readOption(args, name) {
+  const index = args.indexOf(name);
+  if (index === -1) return null;
+  const value = args[index + 1];
+  if (!value) throw new Error(`${name} needs a value`);
+  return value;
+}
+
+function artifactArg(cwd, args) {
+  const file = args.find((arg) => arg.endsWith(".tmxplug"));
+  if (!file) throw new Error("Pass the .tmxplug file to use");
+  const full = path.resolve(cwd, file);
+  if (!fs.existsSync(full)) throw new Error(`${file} does not exist`);
+  return full;
+}
+
+/** Writes <file>.sig: base64 Ed25519 over the sha256 of the .tmxplug. */
+export async function sign({ cwd, args = [], env = process.env }) {
+  const file = artifactArg(cwd, args);
+  const key = loadPrivateKey(env[SIGNING_KEY_ENV]);
+  const buffer = fs.readFileSync(file);
+  const signature = signArtifact(buffer, key);
+  fs.writeFileSync(`${file}.sig`, `${signature}\n`);
+  console.log(`signed ${path.basename(file)}`);
+  console.log(`  sha256     ${sha256(buffer).toString("hex")}`);
+  console.log(`  signature  ${signature}`);
+  return signature;
+}
+
+/** Checks a .tmxplug against its .sig and one or more public keys. */
+export async function verify({ cwd, args = [] }) {
+  const file = artifactArg(cwd, args);
+  const keys = (readOption(args, "--key") ?? "")
+    .split(",")
+    .map((key) => key.trim())
+    .filter(Boolean);
+  if (keys.length === 0) throw new Error("Pass --key <base64 public key>");
+  const sigFile = readOption(args, "--sig") ?? `${file}.sig`;
+  if (!fs.existsSync(sigFile)) throw new Error(`${sigFile} does not exist`);
+
+  const matched = verifyArtifact(
+    fs.readFileSync(file),
+    fs.readFileSync(sigFile, "utf8"),
+    keys,
+  );
+  if (!matched)
+    throw new Error(`${path.basename(file)}: signature is not valid`);
+  console.log(`ok  ${path.basename(file)} signed by key ${matched}`);
+  return matched;
+}
+
+/**
+ * Writes a new private key to a file and prints the public half. The
+ * private key never goes to stdout, so it does not end up in a CI log.
+ */
+export async function keygen({ cwd, args = [] }) {
+  const outDir = path.resolve(cwd, readOption(args, "--out") ?? ".");
+  const keyFile = path.join(outDir, "termix-plugin-signing.key");
+  if (fs.existsSync(keyFile)) {
+    throw new Error(`${keyFile} already exists; move it first`);
+  }
+  const pair = generateKeyPair();
+  fs.mkdirSync(outDir, { recursive: true });
+  fs.writeFileSync(keyFile, `${pair.privateKey}\n`, { mode: 0o600 });
+  console.log(`private key  ${keyFile}`);
+  console.log(`public key   ${pair.publicKey}`);
+  console.log(`key id       ${pair.keyId}`);
+  console.log(
+    `Store the private key as ${SIGNING_KEY_ENV}, then delete the file.`,
+  );
+  return { keyFile, publicKey: pair.publicKey, keyId: pair.keyId };
+}