@xemahq/xema 0.59.0 → 0.60.1

package/edition/resolve-chart-set.mjs

@@ -1,376 +0,0 @@
-#!/usr/bin/env node
-// resolve-chart-set — pin the Helm chart-set version an install resolves, so
-// that no human has to.
-//
-// ─────────────────────────────────────────────────────────────────────────────
-// WHY THIS EXISTS
-//
-//   `xema-appliance provision` pulls charts from the configured chart registry
-//   at an explicitly pinned `XEMA_CHART_VERSION`, and REFUSES to run without
-//   one ("refusing to pull a floating chart version"). Nothing set it. The
-//   value was typed by an operator, which made every platform update a step
-//   somebody had to remember and get right — exactly the maintenance surface
-//   the images plane already removed for itself with images.lock.json.
-//
-//   This resolves it instead, and writes the answer to a lock the appliance
-//   reads. The env var survives as an override, never as the only source.
-//
-// WHY IT IS RESOLVED AND NOT COMPUTED
-//
-//   The version cannot be derived from this repository: it is minted by the two
-//   publish-charts workflows (xema-deploy and xema-infra-services) at publish
-//   time. So the only truthful way to pin it is to ask the registry which
-//   versions actually exist, and that is what this does.
-//
-// EACH PUBLISHER IS PINNED INDEPENDENTLY
-//
-//   One OCI namespace, two publishers, and an install resolves charts from
-//   BOTH — a deployments/*/infra-plan.json names components from each in the
-//   same list. Each closes its own half with an index chart, written only after
-//   every chart of that half is pushed, signed and proved served.
-//
-//   They used to be pinned by ONE shared version, which meant both had to mint
-//   the same string, which meant deriving it from the only input they could both
-//   reproduce — the UTC date — which capped publishing at once a day. The shared
-//   pin was the coupling and the day of latency was its price. Each half is now
-//   pinned separately: a publisher that has not run does not hold the other back.
-//
-// WHICH VERSION IS CURRENT, WHEN COORDINATES DO NOT SORT
-//
-//   Index versions are content-derived (`0.0.0-h<hash>`), so semver precedence
-//   says nothing about which is newest — hashes have no order. The registry
-//   does: `helm push` stamps `org.opencontainers.image.created` into the
-//   manifest, so the current index is the one most recently pushed, read from
-//   the registry rather than guessed from the tag.
-//
-//   Deliberately NOT a moving `latest` tag. Helm derives the OCI tag from the
-//   chart version and will not push a non-semver one, and a moving pointer is
-//   exactly what this plane's image rules refuse — a late run can reach it after
-//   a newer one moved it. Every coordinate here stays immutable.
-//
-// FAIL-CLOSED
-//
-//   No eligible version is an ERROR, never an empty or stale pin. A lock that
-//   silently kept yesterday's value because today's read failed is the exact
-//   shape this plane has been bitten by: a claim that outlives its evidence.
-
-import { existsSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
-
-import {
-  EDITION_CHART_SET_FILE,
-  CHART_SET_LOCK_SCHEMA_VERSION,
-  EditionChartSetCheck,
-  OCI_DIGEST_PATTERN,
-  assertRosteredChartSetLock,
-  checkEditionChartSet,
-  writeEditionChartSet,
-} from './edition-chart-set.mjs';
-import { vendorChartSetConfig } from './edition-config.mjs';
-import { WorkspaceRoot, configureEditionWorkspaceFromProcess, dataRoot, editionsRoot, isEntryModule } from './edition-workspace.mjs';
-import { serializeJson } from './lib.mjs';
-import { mapWithConcurrency } from './map-with-concurrency.mjs';
-import { OrasRegistry } from './oras.mjs';
-import {
-  loadRegistryCredentialDeclarations,
-  resolveRegistryCredential,
-} from './registry-credentials.mjs';
-
-if (isEntryModule(import.meta.url)) {
-  configureEditionWorkspaceFromProcess([WorkspaceRoot.Data, WorkspaceRoot.Editions, WorkspaceRoot.Kernel], { refuseOthers: true });
-}
-
-export const CHART_SET_LOCK_FILE = 'chart-set.lock.json';
-export const chartSetLockPath = () => join(dataRoot(), CHART_SET_LOCK_FILE);
-
-/**
- * The chart registry and its publishers.
- *
- * ONE PIN for every edition, and EVERY EDITION CARRIES IT. The set that
- * satisfies the widest edition satisfies the narrowest, so there is one answer
- * to "which chart set do editions take now" — this lock. But the chart
- * generation a deployment renders is part of its edition (owner ruling
- * 2026-10-04), so each edition holds a byte-identical copy as
- * `<id>/chart-set.lock.json`, hashed into its coordinate and published with it.
- * This script is the one writer of the pin AND every copy, and dist-check
- * refuses a copy that differs — so the copies cannot disagree
- * (edition-chart-set.mjs).
- */
-const chartRegistry = () => vendorChartSetConfig().chartRegistry;
-export const chartSetPublishers = () => vendorChartSetConfig().chartPublishers;
-
-/** `<host>/<path>` -> the repository path the registry API addresses. */
-export function registryRepository(indexName) {
-  return `${chartRegistry().replace(/^oci:\/\/[^/]+\//, '')}/${indexName}`;
-}
-
-function registryAuthority() {
-  return chartRegistry().replace(/^oci:\/\//, '').split('/')[0];
-}
-
-/**
- * cosign publishes a signature as a TAG (`sha256-<digest>.sig`) beside the
- * artifact it signs. Those are not versions and must never be pinned.
- */
-export function isVersionTag(tag) {
-  return !tag.startsWith('sha256-');
-}
-
-/**
- * The newest index version for ONE publisher, by registry creation time.
- * `candidates` is `[{ tag, createdAt }]`; returns the tag or null.
- *
- * A tag whose manifest carries no creation stamp is REFUSED rather than sorted
- * last: guessing an order for a coordinate whose age is unknown is how a stale
- * set gets pinned as current.
- */
-export function selectNewestIndex(candidates) {
-  if (!Array.isArray(candidates)) {return null;}
-  if (candidates.length === 0) {return null;}
-  const undated = candidates.filter((c) => !c.createdAt);
-  if (undated.length > 0) {
-    throw new Error(
-      `index version(s) ${undated.map((c) => c.tag).join(', ')} carry no ` +
-        'org.opencontainers.image.created stamp, so "which is current" cannot be answered. ' +
-        'Refusing to guess.',
-    );
-  }
-  return [...candidates].sort(
-    (a, b) => Date.parse(b.createdAt) - Date.parse(a.createdAt),
-  )[0].tag;
-}
-
-const DIGEST_PATTERN = OCI_DIGEST_PATTERN;
-
-/** Registry reads in flight at once while reading a chart set. */
-const CHART_FETCH_CONCURRENCY = 6;
-
-/** The index chart annotation listing the charts the publisher closed the set with. */
-export const INDEX_ROSTER_ANNOTATION = 'xema.dev/chart-set-charts';
-
-/**
- * The lock for `publishers`: each publisher's index version, the manifest digest
- * the registry served for that index (`indexDigestsByIndex`), and its sealed roster.
- */
-export function buildLock(versionsByIndex, rostersByIndex, indexDigestsByIndex, publishers = chartSetPublishers()) {
-  // Every publisher's VERSION first: a pin that resolved nothing for one half is
-  // the more fundamental refusal, whatever its roster.
-  for (const publisher of publishers) {
-    if (!versionsByIndex[publisher.index]) {
-      throw new Error(`no index version was resolved for '${publisher.index}'`);
-    }
-  }
-  return {
-    // Every member is `{version, digest}` (its OCI manifest digest) and each
-    // publisher pins its index chart by `indexDigest`, so the lock itself is the
-    // trust anchor; `publishers[].version` is per publisher, not one shared version.
-    schemaVersion: CHART_SET_LOCK_SCHEMA_VERSION,
-    registry: chartRegistry(),
-    publishers: publishers.map((publisher) => {
-      const version = versionsByIndex[publisher.index];
-      if (!version) {
-        throw new Error(`no index version was resolved for '${publisher.index}'`);
-      }
-      // THE ROSTER, sealed: chart name → {version, digest}, so an edition that
-      // copies this lock selects and verifies every chart without the registry.
-      const roster = rostersByIndex?.[publisher.index];
-      if (!roster || Object.keys(roster).length === 0) {
-        throw new Error(`no roster was read for '${publisher.index}@${version}'`);
-      }
-      const charts = {};
-      for (const name of Object.keys(roster).sort()) {
-        const member = roster[name];
-        if (!DIGEST_PATTERN.test(String(member?.digest))) {
-          throw new Error(`${publisher.index}@${version}: ${name} has no sha256 manifest digest`);
-        }
-        charts[name] = { version: member.version, digest: member.digest };
-      }
-      // The digest the registry served for the index manifest the roster was read from.
-      const indexDigest = indexDigestsByIndex?.[publisher.index];
-      if (!DIGEST_PATTERN.test(String(indexDigest))) {
-        throw new Error(`no index manifest digest was read for '${publisher.index}@${version}' (got ${JSON.stringify(indexDigest ?? null)}; a release index needs sha256:<64 hex>)`);
-      }
-      return { ...publisher, version, indexDigest, charts };
-    }),
-  };
-}
-
-/**
- * The roster an index chart carries: its `xema.dev/chart-set-charts`
- * annotation, one `{"name","version"[,"digest"]}` JSON object per line, read from the
- * chart's OCI config blob (helm stores Chart.yaml's metadata there). The blob is
- * fetched by digest and hash-checked by the client. Returns name → {version,
- * digest?}; `digest` is present only when the index carries one.
- */
-export function parseIndexRoster(annotation, label) {
-  if (typeof annotation !== 'string' || annotation.trim().length === 0) {
-    throw new Error(`${label} carries no xema.dev/chart-set-charts roster`);
-  }
-  const charts = {};
-  for (const line of annotation.split('\n').map((l) => l.trim()).filter(Boolean)) {
-    const member = JSON.parse(line);
-    if (typeof member?.name !== 'string' || typeof member?.version !== 'string') {
-      throw new Error(`${label}: roster line is not {name, version}: ${line}`);
-    }
-    if (Object.hasOwn(charts, member.name)) {throw new Error(`${label}: roster names ${member.name} twice`);}
-    if (member.digest !== undefined && !DIGEST_PATTERN.test(String(member.digest))) {
-      throw new Error(`${label}: ${member.name} carries a malformed digest: ${member.digest}`);
-    }
-    charts[member.name] = member.digest === undefined
-      ? { version: member.version }
-      : { version: member.version, digest: member.digest };
-  }
-  return Object.fromEntries(Object.entries(charts).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)));
-}
-
-/**
- * Give every member a manifest digest: the index's own when it carries one,
- * else the registry's for `<name>:<version>` (`lookup`). Both present and
- * different is refused.
- */
-export async function sealRoster(roster, lookup, label) {
-  const sealed = {};
-  const members = Object.entries(roster);
-  const registryDigests = await mapWithConcurrency(members, CHART_FETCH_CONCURRENCY, ([name, member]) => lookup(name, member.version));
-  for (const [position, [name, member]] of members.entries()) {
-    const registryDigest = registryDigests[position];
-    if (!DIGEST_PATTERN.test(String(registryDigest))) {
-      throw new Error(`${label}: registry returned no sha256 manifest digest for ${name}:${member.version}`);
-    }
-    if (member.digest !== undefined && member.digest !== registryDigest) {
-      throw new Error(
-        `${label}: ${name}:${member.version} index digest ${member.digest} != registry ${registryDigest}`,
-      );
-    }
-    sealed[name] = { version: member.version, digest: member.digest ?? registryDigest };
-  }
-  return sealed;
-}
-
-/** The annotations of an index chart's served manifest `served` ({digest, bytes}), read from its OCI config blob (helm stores Chart.yaml's metadata there). */
-export async function manifestAnnotations(client, indexName, version, served) {
-  const repository = registryRepository(indexName);
-  const manifest = JSON.parse(served.bytes.toString('utf8'));
-  const configDigest = manifest?.config?.digest;
-  if (typeof configDigest !== 'string') {throw new Error(`${indexName}@${version}: manifest names no config blob`);}
-  const config = JSON.parse((await client.getBlob(repository, configDigest)).toString('utf8'));
-  return config?.annotations ?? {};
-}
-
-/** The roster and the served manifest digest of the index chart `<indexName>:<version>`, from ONE manifest read. */
-export async function indexRosterAndDigest(client, indexName, version) {
-  const served = await client.getManifestByTag(registryRepository(indexName), version);
-  const annotations = await manifestAnnotations(client, indexName, version, served);
-  return { roster: parseIndexRoster(annotations[INDEX_ROSTER_ANNOTATION], `${indexName}@${version}`), indexDigest: served.digest };
-}
-
-/** The `sealRoster` lookup through `client`: the manifest digest the registry serves for `<name>:<version>`. */
-export const registryChartDigest = (client) => async (name, version) => (await client.getManifestByTag(registryRepository(name), version)).digest;
-
-/** Every edition directory (one holding a distribution.lock.json) under the editions root. */
-function editionDirs() {
-  return readdirSync(editionsRoot(), { withFileTypes: true })
-    .filter((entry) => entry.isDirectory() && existsSync(join(editionsRoot(), entry.name, 'distribution.lock.json')))
-    .map((entry) => join(editionsRoot(), entry.name))
-    .sort();
-}
-
-/** The registry client for the chart registry, with the data root's declared credential. */
-export function chartRegistryClient() {
-  const credential = resolveRegistryCredential({ authority: registryAuthority(), declarations: loadRegistryCredentialDeclarations() });
-  return new OrasRegistry({ credential });
-}
-
-export function readLock(path = chartSetLockPath()) {
-  try {
-    return JSON.parse(readFileSync(path, 'utf8'));
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Every index tag of one publisher, with the creation stamp the registry
- * recorded for it.
- */
-async function indexCandidates(client, indexName) {
-  const repository = registryRepository(indexName);
-  const tags = (await client.listTags(repository)).filter(isVersionTag);
-  return mapWithConcurrency(tags, CHART_FETCH_CONCURRENCY, async (tag) => {
-    const manifest = await client.getManifestByTag(repository, tag);
-    const document = JSON.parse(manifest.bytes.toString('utf8'));
-    return {
-      tag,
-      createdAt: document?.annotations?.['org.opencontainers.image.created'] ?? null,
-    };
-  });
-}
-
-/** Read every publisher's newest index through `client`: its version, its roster, and the manifest digest the registry served for it. */
-export async function resolveFromRegistry(client = chartRegistryClient()) {
-
-  const versionsByIndex = {};
-  const rostersByIndex = {};
-  const indexDigestsByIndex = {};
-  for (const { index, repo } of chartSetPublishers()) {
-    const candidates = await indexCandidates(client, index);
-    const version = selectNewestIndex(candidates);
-    if (!version) {
-      throw new Error(
-        `${index} has no published version, so ${repo} has never closed a chart set. ` +
-          'An index is written only after its publisher pushes, signs and proves served every ' +
-          'chart of its half — its absence means that half has never completed.',
-      );
-    }
-    versionsByIndex[index] = version;
-    const { roster, indexDigest } = await indexRosterAndDigest(client, index, version);
-    indexDigestsByIndex[index] = indexDigest;
-    // The registry is asked for every member, so an index digest is checked
-    // against it and a member without one still gets sealed.
-    rostersByIndex[index] = await sealRoster(roster, registryChartDigest(client), `${index}@${version}`);
-  }
-  return { versionsByIndex, rostersByIndex, indexDigestsByIndex };
-}
-
-async function main(argv) {
-  const check = argv.includes('--check');
-  const { versionsByIndex, rostersByIndex, indexDigestsByIndex } = await resolveFromRegistry();
-  const next = buildLock(versionsByIndex, rostersByIndex, indexDigestsByIndex);
-  assertRosteredChartSetLock(next, CHART_SET_LOCK_FILE);
-  const pinText = serializeJson(next);
-  const current = readLock();
-  // The pin AND every edition's copy of it: one writer, one run, so the N copies
-  // of one fact cannot disagree (edition-chart-set.mjs).
-  const staleEditions = editionDirs().filter((dir) => checkEditionChartSet(dir, pinText) !== EditionChartSetCheck.GREEN);
-  const changed = serializeJson(current) !== pinText || staleEditions.length > 0;
-
-  const describe = next.publishers
-    .map((publisher) => `${publisher.index}=${publisher.version}`)
-    .join(' ');
-
-  if (check) {
-    if (changed) {
-      throw new Error(
-        `${CHART_SET_LOCK_FILE} is stale${staleEditions.length ? ` (and ${staleEditions.length} edition copy/copies differ from it)` : ''}. The registry's current indexes are ${describe}. ` +
-          "Run 'node resolve-chart-set.mjs' and commit the result.",
-      );
-    }
-    process.stdout.write(`chart-set: ${describe} (lock is current)\n`);
-    return;
-  }
-
-  if (!changed) {
-    process.stdout.write(`chart-set: ${describe} (unchanged)\n`);
-    return;
-  }
-  writeFileSync(chartSetLockPath(), pinText);
-  for (const dir of editionDirs()) {writeEditionChartSet(dir, pinText);}
-  process.stdout.write(`chart-set: ${describe} (pin + ${editionDirs().length} edition ${EDITION_CHART_SET_FILE})\n`);
-}
-
-if (isEntryModule(import.meta.url)) {
-  main(process.argv.slice(2)).catch((error) => {
-    process.stderr.write(`resolve-chart-set: ${error.message}\n`);
-    process.exit(1);
-  });
-}