@xemahq/edition-tooling 0.0.0-stage → 0.1.0

package/edition/workspace-sections.mjs

@@ -0,0 +1,287 @@
+// The strict parsers for the product-data sections of `edition-workspace.json`.
+// The library owns these SCHEMAS; the VALUES (which repository holds which
+// service, which sources the runtime images are built from, which repository
+// key a pin role uses) are the data root's. Every parser refuses an unknown key,
+// a missing key and a wrong type, naming the section and the path.
+
+import { developImageRegistryProblem } from './develop-store-root.mjs';
+
+const FILE = 'edition-workspace.json';
+
+const isObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+
+function fail(where, message) {
+  throw new Error(`${FILE}: ${where} ${message}`);
+}
+
+/** An object with exactly `required` plus any of `optional` keys. */
+function exactObject(value, where, required, optional = []) {
+  if (!isObject(value)) {fail(where, 'must be an object');}
+  for (const key of Object.keys(value)) {
+    if (!required.includes(key) && !optional.includes(key)) {fail(where, `has unknown key "${key}"`);}
+  }
+  for (const key of required) {
+    if (!Object.hasOwn(value, key)) {fail(where, `is missing "${key}"`);}
+  }
+  return value;
+}
+
+function text(value, where) {
+  if (typeof value !== 'string' || value.length === 0) {fail(where, 'must be a non-empty string');}
+  return value;
+}
+
+function textList(value, where) {
+  if (!Array.isArray(value)) {fail(where, 'must be an array of strings');}
+  return Object.freeze(value.map((item, i) => text(item, `${where}[${i}]`)));
+}
+
+function list(value, where, parseItem) {
+  if (!Array.isArray(value)) {fail(where, 'must be an array');}
+  return Object.freeze(value.map((item, i) => Object.freeze(parseItem(item, `${where}[${i}]`))));
+}
+
+function uniqueBy(items, where, keyOf) {
+  const seen = new Set();
+  for (const item of items) {
+    const key = keyOf(item);
+    if (seen.has(key)) {fail(where, `declares "${key}" twice`);}
+    seen.add(key);
+  }
+  return items;
+}
+
+/** A repository handle: `repos/<r>` or `submodules/<r>`, the sources-root layout. */
+const REPO_HANDLE = /^(?:repos|submodules)\/[a-z0-9][a-z0-9-]*$/;
+const SOURCE_ID = /^[a-z][a-z0-9-]*$/;
+
+function repoHandle(value, where) {
+  if (typeof value !== 'string' || !REPO_HANDLE.test(value)) {
+    fail(where, `must be a source checkout handle repos/<name> or submodules/<name>; got ${JSON.stringify(value)}`);
+  }
+  return value;
+}
+
+export const RuntimeSubjectKind = Object.freeze({
+  Service: 'service',
+  Host: 'host',
+  RuntimeComponent: 'runtime-component',
+});
+
+const SUBJECT_KINDS = Object.values(RuntimeSubjectKind);
+
+function subjectKind(value, where) {
+  if (!SUBJECT_KINDS.includes(value)) {fail(where, `must be one of ${SUBJECT_KINDS.join(', ')}`);}
+  return value;
+}
+
+/**
+ * What launches a supplemental subject that no platform service binds: the
+ * owner its image-lock row is sealed under. Closed, one member until a second
+ * real case exists: a BIOME, which launches the subject's image itself, so
+ * the subject ships in every edition whose roster contains that biome.
+ */
+export const SupplementalLauncherKind = Object.freeze({
+  Biome: 'biome',
+});
+
+const LAUNCHER_KINDS = Object.values(SupplementalLauncherKind);
+
+function supplementalLauncher(value, where) {
+  exactObject(value, where, ['kind', 'biomeId']);
+  if (!LAUNCHER_KINDS.includes(value.kind)) {fail(`${where}.kind`, `must be one of ${LAUNCHER_KINDS.join(', ')}`);}
+  return Object.freeze({ kind: value.kind, biomeId: text(value.biomeId, `${where}.biomeId`) });
+}
+
+/**
+ * The retired `{repo handle: source id}` string form of a `firstPartySources`
+ * entry. Refused, never read: the entry also declares where the repository
+ * lives, which the develop graph resolves its head from.
+ */
+export class RetiredFirstPartySourceShapeError extends Error {
+  constructor(repo, id) {
+    super(
+      `${FILE}: "firstPartySources"["${repo}"] is the retired source-id string ${JSON.stringify(id)}. ` +
+        `Migrate it to { "sourceId": ${JSON.stringify(id)}, "repositoryUrl": "<the repository's canonical https URL>" }.`,
+    );
+    this.name = 'RetiredFirstPartySourceShapeError';
+  }
+}
+
+/**
+ * Where a first-party source's images come from on the everyday lane: built by the job in the aggregator workspace,
+ * or a satellite producer's own signed develop digest (a source outside the workspace, such as
+ * submodules/xema-host-web). `--images-from` admits a record entry only from the list its source's origin names.
+ */
+export const FirstPartyImageOrigin = Object.freeze({
+  Workspace: 'workspace',
+  Satellite: 'satellite',
+});
+
+const IMAGE_ORIGINS = Object.values(FirstPartyImageOrigin);
+
+/** An issue key, `<PROJECT>-<number>`: the ticket that removes a member's current-resolution exception. */
+const TICKET = /^[A-Z][A-Z0-9]*-[1-9][0-9]*$/;
+
+/**
+ * `firstPartySources`: every first-party repository, keyed by its source
+ * checkout handle, with its declared source id (the identity a runtime subject
+ * is named after) and its repository URL (where it lives: the develop graph
+ * resolves its head there, and a release pin must name the same URL). The URL
+ * is checked canonical and under `sourceRepositoryUrlPrefix` with the whole
+ * config (edition-config.mjs). `imageOrigin` (FirstPartyImageOrigin) is optional
+ * here and has no default: `--images-from` refuses a source that does not declare it.
+ * `currentResolution` (a ticket, `<PROJECT>-<number>`) is optional and has no default: a member that declares it keeps
+ * the CURRENT develop resolution instead of a signed build record until that ticket removes it
+ * (develop-current-resolution.mjs); a member without it never does.
+ * `developImageRegistry` (a lowercase `<host[:port]>/<path>` store root, no scheme, tag, digest, trailing slash or
+ * `/dev`) is the member's develop store: develop images are `<root>/dev/<name>` and build records
+ * `<root>/build-records/<name>` (develop-image-coordinate.mjs). Required: a source declares its store explicitly, even when it is still the owner root of its release images.
+ */
+export function parseFirstPartySources(value) {
+  const where = '"firstPartySources"';
+  if (!isObject(value) || Object.keys(value).length === 0) {
+    fail(where, 'must be a non-empty {repo handle: { sourceId, repositoryUrl }} object');
+  }
+  const entries = Object.entries(value).map(([repo, entry]) => {
+    repoHandle(repo, `${where} key`);
+    if (typeof entry === 'string') {throw new RetiredFirstPartySourceShapeError(repo, entry);}
+    const at = `${where}["${repo}"]`;
+    if (isObject(entry) && !Object.hasOwn(entry, 'developImageRegistry')) {
+      fail(at, `is missing "developImageRegistry": declare the develop store of ${repo} as <host[:port]>/<path> (for example registry.example.com/acme-dev)`);
+    }
+    exactObject(entry, at, ['sourceId', 'repositoryUrl', 'developImageRegistry'], ['imageOrigin', 'currentResolution']);
+    if (typeof entry.sourceId !== 'string' || !SOURCE_ID.test(entry.sourceId)) {
+      fail(`${at}.sourceId`, `must be a lowercase kebab-case source id; got ${JSON.stringify(entry.sourceId)}`);
+    }
+    if (Object.hasOwn(entry, 'imageOrigin') && !IMAGE_ORIGINS.includes(entry.imageOrigin)) {
+      fail(`${at}.imageOrigin`, `must be one of ${IMAGE_ORIGINS.join(', ')}; got ${JSON.stringify(entry.imageOrigin)}`);
+    }
+    if (Object.hasOwn(entry, 'currentResolution') && (typeof entry.currentResolution !== 'string' || !TICKET.test(entry.currentResolution))) {
+      fail(`${at}.currentResolution`, `must be the ticket that removes the exception, <PROJECT>-<number>; got ${JSON.stringify(entry.currentResolution)}`);
+    }
+    const registryProblem = developImageRegistryProblem(entry.developImageRegistry);
+    if (registryProblem !== null) {fail(`${at}.developImageRegistry`, registryProblem);}
+    return [repo, Object.freeze({
+      sourceId: entry.sourceId,
+      repositoryUrl: text(entry.repositoryUrl, `${at}.repositoryUrl`),
+      developImageRegistry: entry.developImageRegistry,
+      ...(Object.hasOwn(entry, 'imageOrigin') ? { imageOrigin: entry.imageOrigin } : {}),
+      ...(Object.hasOwn(entry, 'currentResolution') ? { currentResolution: entry.currentResolution } : {}),
+    })];
+  });
+  uniqueBy(entries, `${where} sourceId`, ([, entry]) => entry.sourceId);
+  uniqueBy(entries, `${where} repositoryUrl`, ([, entry]) => entry.repositoryUrl);
+  return Object.freeze(Object.fromEntries(entries));
+}
+
+function parseRuntimeBinding(value, where) {
+  if (value === null) {return null;}
+  exactObject(value, where, ['subjectKind', 'subjectId']);
+  return { subjectKind: subjectKind(value.subjectKind, `${where}.subjectKind`), subjectId: text(value.subjectId, `${where}.subjectId`) };
+}
+
+export function parsePlatformServiceSources(value) {
+  const where = '"platformServiceSources"';
+  const items = list(value, where, (item, at) => {
+    exactObject(item, at, ['name', 'tier', 'repo', 'manifestPath', 'manifestName', 'imageKey', 'runtimeBinding'], ['installationClass']);
+    return {
+      name: text(item.name, `${at}.name`),
+      tier: text(item.tier, `${at}.tier`),
+      ...(item.installationClass === undefined ? {} : { installationClass: text(item.installationClass, `${at}.installationClass`) }),
+      repo: repoHandle(item.repo, `${at}.repo`),
+      manifestPath: text(item.manifestPath, `${at}.manifestPath`),
+      manifestName: text(item.manifestName, `${at}.manifestName`),
+      imageKey: text(item.imageKey, `${at}.imageKey`),
+      runtimeBinding: parseRuntimeBinding(item.runtimeBinding, `${at}.runtimeBinding`),
+    };
+  });
+  if (items.length === 0) {fail(where, 'must declare at least one platform service');}
+  uniqueBy(items, where, (item) => item.name);
+  uniqueBy(items, `${where} imageKey`, (item) => item.imageKey);
+  return items;
+}
+
+export function parseConnectorSources(value) {
+  const where = '"connectorSources"';
+  exactObject(value, where, ['repository', 'bindings', 'nonProductionIds', 'buildInput']);
+  const bindings = list(value.bindings, `${where}.bindings`, (item, at) => {
+    exactObject(item, at, ['id', 'path']);
+    return { id: text(item.id, `${at}.id`), path: text(item.path, `${at}.path`) };
+  });
+  uniqueBy(bindings, `${where}.bindings`, (item) => item.id);
+  const buildInput = exactObject(value.buildInput, `${where}.buildInput`, ['consumerRepo', 'consumerService', 'destinationRoot']);
+  return Object.freeze({
+    repository: repoHandle(value.repository, `${where}.repository`),
+    bindings,
+    nonProductionIds: textList(value.nonProductionIds, `${where}.nonProductionIds`),
+    buildInput: Object.freeze({
+      consumerRepo: repoHandle(buildInput.consumerRepo, `${where}.buildInput.consumerRepo`),
+      consumerService: text(buildInput.consumerService, `${where}.buildInput.consumerService`),
+      destinationRoot: text(buildInput.destinationRoot, `${where}.buildInput.destinationRoot`),
+    }),
+  });
+}
+
+export function parseRuntimeImageSources(value) {
+  const where = '"runtimeImageSources"';
+  exactObject(value, where, ['supplementalSources', 'crossRepoBuildInputs', 'buildStepContextDirectories']);
+  const supplementalSources = list(value.supplementalSources, `${where}.supplementalSources`, (item, at) => {
+    exactObject(item, at, ['kind', 'id', 'repo', 'path', 'sourceManifestPath'], ['launchedBy']);
+    return {
+      kind: subjectKind(item.kind, `${at}.kind`),
+      id: text(item.id, `${at}.id`),
+      repo: repoHandle(item.repo, `${at}.repo`),
+      path: text(item.path, `${at}.path`),
+      sourceManifestPath: text(item.sourceManifestPath, `${at}.sourceManifestPath`),
+      ...(Object.hasOwn(item, 'launchedBy')
+        ? { launchedBy: supplementalLauncher(item.launchedBy, `${at}.launchedBy`) }
+        : {}),
+    };
+  });
+  uniqueBy(supplementalSources, `${where}.supplementalSources`, (item) => `${item.kind}/${item.id}`);
+  const crossRepoBuildInputs = list(value.crossRepoBuildInputs, `${where}.crossRepoBuildInputs`, (item, at) => {
+    exactObject(item, at, ['consumerRepo', 'consumerService', 'sourceRepo', 'sourcePath', 'destinationPath']);
+    return {
+      consumerRepo: repoHandle(item.consumerRepo, `${at}.consumerRepo`),
+      consumerService: item.consumerService === null ? null : text(item.consumerService, `${at}.consumerService`),
+      sourceRepo: repoHandle(item.sourceRepo, `${at}.sourceRepo`),
+      sourcePath: text(item.sourcePath, `${at}.sourcePath`),
+      destinationPath: text(item.destinationPath, `${at}.destinationPath`),
+    };
+  });
+  const buildStepContextDirectories = list(value.buildStepContextDirectories, `${where}.buildStepContextDirectories`, (item, at) => {
+    exactObject(item, at, ['repo', 'path', 'reason']);
+    return { repo: repoHandle(item.repo, `${at}.repo`), path: text(item.path, `${at}.path`), reason: text(item.reason, `${at}.reason`) };
+  });
+  return Object.freeze({ supplementalSources, crossRepoBuildInputs, buildStepContextDirectories });
+}
+
+/** The pin roles are a closed set the library defines; their repository keys are data. */
+export const PinRole = Object.freeze({
+  Data: 'data',
+  Kernel: 'kernel',
+  Deploy: 'deploy',
+});
+
+export function parsePinRoles(value) {
+  const where = '"pinRoles"';
+  exactObject(value, where, Object.values(PinRole));
+  const keys = Object.values(PinRole).map((role) => [role, text(value[role], `${where}.${role}`)]);
+  uniqueBy(keys, where, ([, key]) => key);
+  return Object.freeze(Object.fromEntries(keys));
+}
+
+export function parseConfinedBiomes(value) {
+  const where = '"confinedBiomes"';
+  const items = list(value, where, (item, at) => {
+    exactObject(item, at, ['biomeId', 'holds', 'consequence', 'admittedEditions']);
+    return {
+      biomeId: text(item.biomeId, `${at}.biomeId`),
+      holds: text(item.holds, `${at}.holds`),
+      consequence: text(item.consequence, `${at}.consequence`),
+      admittedEditions: textList(item.admittedEditions, `${at}.admittedEditions`),
+    };
+  });
+  return uniqueBy(items, where, (item) => item.biomeId);
+}

package/package.json

@@ -1,6 +1,85 @@
 {
   "name": "@xemahq/edition-tooling",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "The Xema edition pipeline: resolve, seal, check, develop-snapshot and evidence verbs for a distribution data root. Ships the `xema-edition` bin and the `candidate-edition` library. Not an operator tool: the operator CLI is @xemahq/xema.",
+  "license": "LicenseRef-Xema-BSL-1.1",
+  "author": "Neuralchowder Inc. <developer@xema.dev> (https://xema.dev)",
+  "homepage": "https://xema.dev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xema-dev/xema-base.git",
+    "directory": "packages/edition/edition-tooling"
+  },
+  "bugs": "https://github.com/xema-dev/xema-base/issues",
+  "type": "commonjs",
+  "engines": {
+    "node": ">=22.20.0 <23"
+  },
+  "main": "dist/cli.js",
+  "exports": {
+    ".": {
+      "types": "./dist/cli.d.ts",
+      "require": "./dist/cli.js",
+      "default": "./dist/cli.js"
+    },
+    "./candidate-edition": {
+      "import": "./edition/candidate-edition.mjs",
+      "default": "./edition/candidate-edition.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "xema-edition": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "edition/**/*.mjs",
+    "edition/*.json",
+    "!edition/**/*.test.mjs",
+    "!edition/**/*-contract-tests.mjs",
+    "!edition/test-fixtures/**",
+    "edition/README.md"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "dependencies": {
+    "@xemahq/distribution-source-hash": "^0.2.2",
+    "commander": "^12.1.0",
+    "yaml": "^2.6.1",
+    "zod": "^4.6.1",
+    "@xemahq/biome-sdk": "^25.0.0",
+    "@xemahq/oci-closure": "^0.1.0",
+    "@xemahq/biome-supply-chain": "^0.9.0",
+    "@xemahq/contracts": "^0.120.0"
+  },
+  "devDependencies": {
+    "@types/jest": "^30.0.0",
+    "@types/node": "25.2.3",
+    "esbuild": "^0.28.2",
+    "eslint": "^9.39.4",
+    "jest": "^30.3.0",
+    "prettier": "3.6.2",
+    "ts-jest": "^29.4.9",
+    "ts-node": "^10.9.2",
+    "typescript": "5.9.3",
+    "@xemahq/biome-test-utils": "^12.4.6",
+    "@xemahq/eslint-config": "^0.14.3"
+  },
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "tsc -p tsconfig.build.json && node ./scripts/post-build.cjs && node ./scripts/build-evidence-verifier.mjs",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "lint": "eslint . --max-warnings 0",
+    "lint:fix": "eslint . --fix",
+    "test": "jest --config jest.config.cjs && pnpm run test:edition",
+    "test:edition": "node scripts/run-edition-tests.mjs \"edition/*.test.mjs\" \"edition/*-contract-tests.mjs\"",
+    "verify:pack": "node ./scripts/verify-packed-assets.cjs",
+    "typecheck": "tsc --noEmit"
+  },
+  "xemaRelease": {
+    "sourceDigest": "sha256:83a084363b21bcdf698f3de93377171f8b3dedd5ada007c4f96b472b6f787b80",
+    "sha": "a32f8f5509b7ea239deb38216e4996e6286b10e8"
+  }
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.