@xemahq/xema 0.26.0 → 0.27.0

package/edition/resolve-edition.mjs

@@ -0,0 +1,186 @@
+#!/usr/bin/env node
+// resolve-edition — the release lock set of one edition, in the order the
+// distribution plane has always run it: `resolve-distribution <id>` (the
+// distribution, authorization and chart-set locks) and then
+// `resolve-images <id> --trusted-write-v3` (the images lock).
+//
+//   node resolve-edition.mjs <root flags> <edition-id> --trusted-write-v3
+//       write the whole lock set into the editions root. The flag is the
+//       operator's explicit acknowledgement that the images lock is rewritten
+//       UNSEALED (a resolve never produces an `imageDigest`; `xema edition seal`
+//       writes them afterwards). Without it nothing is written.
+//   node resolve-edition.mjs <root flags> <edition-id> --check
+//       resolve the whole lock set into a scratch copy of the editions root and
+//       compare each lock with the committed one; exit 1 on any difference.
+//       Nothing committed is written, and the flag above is refused alongside
+//       it. Like is compared with like: the resolve timestamp is normalized out
+//       and the committed images lock is read through `withoutSealedDigests`,
+//       because a resolve emits no `imageDigest` and a sealed lock differs from
+//       a fresh resolve by exactly that field.
+
+import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { AUTHORIZATION_LOCK_FILENAME } from './authorization-base.mjs';
+import { fetchCatalogue } from './catalogue-fetch.mjs';
+import {
+  CATALOGUE_FLAG,
+  CATALOGUE_TOKEN_ENV_FLAG,
+  CATALOGUE_USERNAME_FLAG,
+  CHANNEL_FLAG,
+  DEFINITION_FLAG,
+  SOURCE_IMAGE_FLAG,
+} from './customer-flags.mjs';
+import { assertCanonicalDistributionId } from './distribution-paths.mjs';
+import { EditionChannel, EditionLockFile } from './edition-constants.mjs';
+import {
+  WorkspaceRoot,
+  configureEditionWorkspace,
+  configureEditionWorkspaceFromProcess,
+  configuredWorkspace,
+  editionsRoot,
+  isEntryModule,
+} from './edition-workspace.mjs';
+import { comparableDistributionLock, loadKernelDistributionSchemas } from './lib.mjs';
+import { parseSourceImages, resolveCustomerEdition, writeCustomerEdition } from './resolve-customer-edition.mjs';
+import { writeResolvedDistribution } from './resolve-distribution.mjs';
+import { writeResolvedImages } from './resolve-images.mjs';
+import { withoutSealedDigests } from './seal-image-digests.mjs';
+import { readStrictJsonFile } from './strict-json.mjs';
+
+// A customer resolve (`--catalogue`) has no vendor editions root: `--out` IS its
+// editions root, the directory its `<id>/` locks are written under.
+if (isEntryModule(import.meta.url)) {
+  if (process.argv.includes(CATALOGUE_FLAG)) {
+    const at = process.argv.indexOf('--out');
+    if (at < 0 || process.argv[at + 1] === undefined) {throw new Error(`--out <dir> is required with ${CATALOGUE_FLAG}`);}
+    mkdirSync(process.argv[at + 1], { recursive: true });
+    process.argv.splice(at, 1, '--editions-root');
+    configureEditionWorkspaceFromProcess([WorkspaceRoot.Data, WorkspaceRoot.Editions, WorkspaceRoot.Sources, WorkspaceRoot.Kernel, WorkspaceRoot.Cache, WorkspaceRoot.SourceHash]);
+  } else {
+    configureEditionWorkspaceFromProcess([WorkspaceRoot.Data, WorkspaceRoot.Editions, WorkspaceRoot.Sources, WorkspaceRoot.Kernel, WorkspaceRoot.Cache, WorkspaceRoot.SourceHash]);
+  }
+}
+
+const CHECK_FLAG = '--check';
+const TRUSTED_WRITE_FLAG = '--trusted-write-v3';
+
+/** The locks one resolve writes, and the only files `--check` compares. */
+export const RESOLVED_LOCK_FILES = Object.freeze([
+  EditionLockFile.Distribution,
+  AUTHORIZATION_LOCK_FILENAME,
+  EditionLockFile.ChartSet,
+  EditionLockFile.Images,
+]);
+
+/**
+ * A lock's comparable text. The resolve timestamp is the one field that changes
+ * between identical resolves; the sealed `imageDigest` of the images lock is a
+ * fact about what SHIPPED that a resolve never reproduces, so it is subtracted
+ * from the committed side (a fresh resolve carries none).
+ */
+export function comparableLock(file, text, schemas) {
+  const lock = JSON.parse(text);
+  if (file === EditionLockFile.Distribution) {return comparableDistributionLock(schemas, lock);}
+  const { resolvedAt: _resolvedAt, ...rest } = file === EditionLockFile.Images ? withoutSealedDigests(lock) : lock;
+  return JSON.stringify(rest);
+}
+
+/** `{ id, check }` from the arguments after the root flags; the write flag is required to write and refused with `--check`. */
+export function parseResolveEditionArgs(args) {
+  const [id, ...rest] = args;
+  const known = [CHECK_FLAG, TRUSTED_WRITE_FLAG];
+  const usage = `usage: resolve-edition.mjs <root flags> <edition-id> (${CHECK_FLAG} | ${TRUSTED_WRITE_FLAG})`;
+  if (!id || rest.some((argument) => !known.includes(argument))) {throw new Error(usage);}
+  const check = rest.includes(CHECK_FLAG);
+  const trustedWrite = rest.includes(TRUSTED_WRITE_FLAG);
+  if (check === trustedWrite) {
+    throw new Error(
+      check
+        ? `${CHECK_FLAG} writes nothing committed and does not take ${TRUSTED_WRITE_FLAG}`
+        : `refusing to write a lock set without ${TRUSTED_WRITE_FLAG}: the images lock is rewritten unsealed; ${usage}`,
+    );
+  }
+  return { id, check };
+}
+
+export async function writeResolvedLockSet(id) {
+  await writeResolvedDistribution(id);
+  await writeResolvedImages(id, { trustedWriteV3: true });
+}
+
+export async function checkResolvedLockSet(id) {
+  const committedRoot = editionsRoot();
+  const scratch = mkdtempSync(join(tmpdir(), 'xema-edition-check-'));
+  try {
+    const schemas = await loadKernelDistributionSchemas();
+    cpSync(committedRoot, scratch, {
+      recursive: true,
+      filter: (source) => !/(^|[\\/])(\.git|node_modules)$/.test(source),
+    });
+    configureEditionWorkspace({ ...configuredWorkspace(), [WorkspaceRoot.Editions]: scratch });
+    await writeResolvedLockSet(id);
+    const drift = RESOLVED_LOCK_FILES.filter((file) => {
+      const committed = join(committedRoot, id, file);
+      const fresh = join(scratch, id, file);
+      if (!existsSync(committed) || !existsSync(fresh)) {return existsSync(committed) !== existsSync(fresh);}
+      return comparableLock(file, readFileSync(committed, 'utf8'), schemas) !== comparableLock(file, readFileSync(fresh, 'utf8'), schemas);
+    });
+    if (drift.length > 0) {
+      throw new Error(`${id}: the committed ${drift.join(', ')} differ from a fresh resolve; resolve the edition and commit the result`);
+    }
+  } finally {
+    rmSync(scratch, { recursive: true, force: true });
+  }
+}
+
+const CUSTOMER_VALUE_FLAGS = [DEFINITION_FLAG, CATALOGUE_FLAG, CHANNEL_FLAG, CATALOGUE_USERNAME_FLAG, CATALOGUE_TOKEN_ENV_FLAG];
+
+/** The arguments of a customer resolve (the root flags and `--out` are already consumed). */
+export function parseCustomerResolveArgs(args) {
+  const values = new Map();
+  const sourceImages = [];
+  for (let i = 0; i < args.length; i += 1) {
+    const flag = args[i];
+    const value = args[i + 1];
+    if (![...CUSTOMER_VALUE_FLAGS, SOURCE_IMAGE_FLAG].includes(flag) || value === undefined || value.startsWith('--')) {
+      throw new Error(`unexpected argument ${JSON.stringify(flag)} in a customer resolve (${DEFINITION_FLAG}, ${CATALOGUE_FLAG}, ${CHANNEL_FLAG}, ${SOURCE_IMAGE_FLAG} take a value)`);
+    }
+    i += 1;
+    if (flag === SOURCE_IMAGE_FLAG) {sourceImages.push(value);} else if (values.has(flag)) {throw new Error(`${flag} given twice`);} else {values.set(flag, value);}
+  }
+  for (const required of [DEFINITION_FLAG, CATALOGUE_FLAG, CHANNEL_FLAG]) {
+    if (!values.has(required)) {throw new Error(`a customer resolve requires ${required}`);}
+  }
+  if (!Object.values(EditionChannel).includes(values.get(CHANNEL_FLAG))) {
+    throw new Error(`${CHANNEL_FLAG} must be one of ${Object.values(EditionChannel).join(' | ')}`);
+  }
+  return { values, sourceImages: parseSourceImages(sourceImages) };
+}
+
+async function mainCustomer() {
+  const { values, sourceImages } = parseCustomerResolveArgs(process.argv.slice(2));
+  const { catalogue, digest } = await fetchCatalogue({
+    ref: values.get(CATALOGUE_FLAG),
+    username: values.get(CATALOGUE_USERNAME_FLAG),
+    tokenEnv: values.get(CATALOGUE_TOKEN_ENV_FLAG),
+  });
+  const resolved = await resolveCustomerEdition({ rawDefinition: readStrictJsonFile(values.get(DEFINITION_FLAG)), catalogue, catalogueDigest: digest, sourceImages, channel: values.get(CHANNEL_FLAG) });
+  const { dir } = writeCustomerEdition(editionsRoot(), resolved);
+  console.log(`[edition:resolve] ${resolved.id}: customer edition against catalogue ${catalogue.offeringId} ${digest}, written to ${dir}`);
+}
+
+async function main() {
+  if (process.argv.includes(CATALOGUE_FLAG)) {return mainCustomer();}
+  const { id, check } = parseResolveEditionArgs(process.argv.slice(2));
+  assertCanonicalDistributionId(id);
+  await (check ? checkResolvedLockSet(id) : writeResolvedLockSet(id));
+}
+
+if (isEntryModule(import.meta.url)) {
+  main().catch((error) => {
+    console.error(`[edition:resolve] ${error.message}`);
+    process.exit(1);
+  });
+}