@xemahq/xema 0.58.0 → 0.59.1

package/edition/develop-catalogue-free-resolve.mjs

@@ -0,0 +1,280 @@
+// develop-catalogue-free-resolve — the catalogue-free CUSTOMER develop resolve:
+//
+//   xema edition develop resolve --definition-at <owner>/<repo>,<path>,<dataRoot> --offering <owner>/<repo>,<path>,<dataRoot>
+//       --pins <file> --out <dir> --registry <root> --engine-repository <repository> --engine-signer <certificate identity>
+//       --cosign <abs path> --offering-previous-lock <file> --offering-previous-lock-sha256 <hex>
+//       (--previous-lock <file> --previous-lock-sha256 <hex> | --first-seal) [--source-image <source>=<registry>/<prefix>]... [--local]
+//
+// A dev deployment of a customer definition resolves the vendor offering it builds on IN THE SAME CALL instead of
+// pinning a published catalogue: no catalogue.pin.json is read (its presence beside the definition is refused, never
+// a fallback), and no public flag substitutes a catalogue file. Two workspaces, two steps, one CLI:
+//
+//   vendor    a child `develop resolve <offering id> --pins <vendor pins> --local` of this CLI on the VENDOR roots
+//             (the roots this call was given), unchanged: it writes the vendor artifact and catalogue.json into a
+//             scratch directory. --offering names the offering's directory inside the vendor data checkout, held to
+//             it like follow's --definition-at (the checkout is the declared repository, clean at the vendor data
+//             pin, the data root and the directory where the triple says). Never defaulted.
+//   customer  the definition repository fetched at --pins "definition-repository" (the walk's git source fetch, by
+//             exact commit) and its tree at that commit checked out from the object store into this call's private
+//             scratch before the vendor step runs (a temporary index, symlinks as plain files): the shared fetch cache
+//             is never read again, so a cache tree that moves or changes mid-run cannot change what is resolved. The
+//             workspace is re-stated on the scratch copy's roots (data = <copy>/<dataRoot>, editions = the parent of
+//             <copy>/<path>, a fresh sources root, the same cache), and the customer resolve run against the catalogue
+//             the vendor step wrote. The edition's pins are the catalogue-free form
+//             (edition-contract.json provenancePins.customerForms): the vendor pins, the customer's own
+//             sources/<name> commits, "definition-repository" and the definition digest, never a catalogue pin.
+//             The catalogue CONTENT digest is sha256 of the EXACT catalogue.json bytes the vendor step wrote (parsed
+//             strictly, so a duplicate key refuses), the convention of the catalogue layer digest of an offering
+//             artifact (produce-edition-catalogue-evidence's predicate catalogueDigest). It goes into the distribution
+//             lock only, as catalogueContentDigest (kernel edition protocol v37), never catalogueDigest: no catalogue
+//             artifact exists, so the lock never names one (catalogue-lock-field.mjs).
+//
+// --pins is the COMPLETE frozen set; nothing here reads a head. It is split once, before anything is fetched: a
+// sources/<name> key the definition declares is the customer's own, every other key but "definition-repository" goes
+// to the vendor step (which refuses what its offering does not declare). A source name both the offering and the
+// definition declare is refused before the vendor step: its one pin could not say whose source it is.
+
+import { execFileSync, spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { basename, dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { sha256Digest } from './canonical-evidence-json.mjs';
+import { CATALOGUE_PIN_FILE } from './catalogue-pin.mjs';
+import { CATALOGUE_FILE, parseCatalogue } from './catalogue.mjs';
+import { customerPreviousSeal, customerSourceImages, declaredSourceNamesOf, resolveCustomerChannelEdition } from './customer-edition-verbs.mjs';
+import { DEFINITION_AT_FLAG, OFFERING_FLAG, OFFERING_PREVIOUS_LOCK_FLAG, OFFERING_PREVIOUS_LOCK_SHA256_FLAG } from './customer-flags.mjs';
+import { assertDefinitionCheckout, parseFollowDefinition } from './develop-follow.mjs';
+import { customerDevelopGitBundleVerifier } from './develop-git-bundles.mjs';
+import { assertCanonicalDistributionId } from './distribution-paths.mjs';
+import { LOCAL_WORKFLOW, parseEditionDescriptor, snapshotEditionTarget, workflowFromEnv, writeEditionArtifact } from './edition-artifact.mjs';
+import { resetEditionWorkspaceConfig } from './edition-config.mjs';
+import { CATALOGUE_PIN_KEY, DEFINITION_PIN_KEY, DEFINITION_REPOSITORY_PIN_KEY, EDITION_DESCRIPTOR_FILE, EditionChannel, EditionKind, VENDOR_MEMBER_PIN_PATTERN } from './edition-constants.mjs';
+import { WorkspaceRoot, cacheDir, configureEditionWorkspace, configuredWorkspace, editionsRoot, workspaceArgv } from './edition-workspace.mjs';
+import { descriptorEvidenceTrust } from './evidence-trust-policy.mjs';
+import { materializeGitSource } from './external-source-walk.mjs';
+import { serializeJson } from './lib.mjs';
+import { dataPinKey, isSourcePinKey, sortedSnapshotPins, sourceNameOfPinKey } from './pin-source.mjs';
+import { parseStrictJson, readStrictJsonFile } from './strict-json.mjs';
+
+export { DEFINITION_REPOSITORY_PIN_KEY };
+/** The definition file in a definition directory (the editions-root layout). */
+const DEFINITION_FILE = 'xema-distribution.json';
+const SHA_PATTERN = /^[0-9a-f]{40}$/;
+const ENTRY = join(dirname(fileURLToPath(import.meta.url)), 'develop-edition.mjs');
+
+/**
+ * `sha256:<hex>` of the exact catalogue.json bytes the vendor step wrote (the catalogue layer digest convention): the
+ * lock's catalogueContentDigest, never a pin.
+ */
+export const catalogueContentDigestOf = (bytes) => sha256Digest(bytes);
+
+/**
+ * --pins checked and split once, before anything is fetched: `{ definitionRepositoryCommit, members }`, the members
+ * every other key. "catalogue" and "definition" are computed, never input.
+ */
+export function splitCatalogueFreePins(pins) {
+  if (pins === null || typeof pins !== 'object' || Array.isArray(pins)) {throw new Error('--pins must be an object mapping pin key -> 40-hex commit');}
+  for (const computed of [CATALOGUE_PIN_KEY, DEFINITION_PIN_KEY]) {
+    if (computed in pins) {throw new Error(`--pins names "${computed}": a catalogue-free resolve computes the definition digest and pins no catalogue`);}
+  }
+  const { [DEFINITION_REPOSITORY_PIN_KEY]: definitionRepositoryCommit, ...members } = pins;
+  if (typeof definitionRepositoryCommit !== 'string' || !SHA_PATTERN.test(definitionRepositoryCommit)) {
+    throw new Error(`--pins "${DEFINITION_REPOSITORY_PIN_KEY}" must be the 40-hex commit the definition repository is read at, got ${JSON.stringify(definitionRepositoryCommit)}`);
+  }
+  if (!Object.keys(members).some((key) => VENDOR_MEMBER_PIN_PATTERN.test(key))) {
+    throw new Error('--pins carries no vendor member pin (repos/<x> or submodules/<x>): a catalogue-free resolve resolves the vendor offering from them');
+  }
+  return { definitionRepositoryCommit, members };
+}
+
+/**
+ * The members of --pins between the two steps: `{ own, vendor }`, own the sources/<name> keys the definition declares.
+ * `offering` and `definition` are `{ label, sourceNames }`: a source name both declare is refused, naming both.
+ */
+export function partitionCatalogueFreePins(members, { offering, definition }) {
+  const vendorNames = new Set(offering.sourceNames);
+  const shared = [...new Set(definition.sourceNames)].filter((name) => vendorNames.has(name));
+  if (shared.length > 0) {
+    throw new Error(`the source${shared.length === 1 ? '' : 's'} ${shared.map((name) => `"${name}"`).join(', ')} ${shared.length === 1 ? 'is' : 'are'} declared by both the offering ${offering.label} and the definition ${definition.label}: a catalogue-free resolve splits each sources/<name> pin to one of them, so a source name is declared once`);
+  }
+  const ownNames = new Set(definition.sourceNames);
+  const own = {};
+  const vendor = {};
+  for (const [key, commit] of Object.entries(members)) {
+    if (isSourcePinKey(key) && ownNames.has(sourceNameOfPinKey(key))) {own[key] = commit;} else {vendor[key] = commit;}
+  }
+  return { own, vendor: sortedSnapshotPins(vendor) };
+}
+
+/** The definition repository at `commit`, through the source walk's fetch by exact commit; returns its (shared cache) directory. */
+export function fetchDefinitionRepository({ repository, commit, env }) {
+  const source = { kind: 'git', name: DEFINITION_REPOSITORY_PIN_KEY, url: `https://github.com/${repository}.git`, ref: commit };
+  return materializeGitSource({ source, cacheRoot: join(cacheDir(), 'definition-repositories', ...repository.split('/')), env }).directory;
+}
+
+/**
+ * The tree of `commit` in the repository at `repository`, written into the new directory `into` from the object store
+ * (a temporary index beside `into`, never the repository's own index or worktree; symlinks as plain files, so nothing
+ * read from `into` resolves outside it). Returns `into`.
+ */
+export function materializeDefinitionCommit({ repository, commit, into }) {
+  mkdirSync(into);
+  const env = { ...process.env, GIT_INDEX_FILE: `${into}.index`, GIT_NO_LAZY_FETCH: '1' };
+  const git = (args) => execFileSync('git', ['-C', repository, '-c', 'core.symlinks=false', ...args], { env, stdio: ['ignore', 'pipe', 'pipe'] });
+  try {
+    git(['read-tree', `${commit}^{tree}`]);
+    git(['checkout-index', '--all', `--prefix=${into}/`]);
+  } finally {
+    rmSync(`${into}.index`, { force: true });
+  }
+  return into;
+}
+
+/** The argv of the vendor step's child `develop resolve` (after the node binary). */
+export function vendorResolveArgs({ offeringId, pinsFile, outDir, options, roots }) {
+  // Always --local: the child is a step of this call, not a release workflow; its descriptor never leaves the scratch
+  // directory, and the edition this call writes records this call's own workflow (LOCAL_WORKFLOW only under --local).
+  // The child finds and proves the engine itself (--engine-repository/--engine-signer), and seals against the OFFERING's
+  // own previous seal (the images lock `develop follow` froze), held by the child to its sha256 and to the offering's id.
+  return [
+    ENTRY, 'resolve', offeringId, '--pins', pinsFile, '--out', outDir, '--registry', options['--registry'],
+    '--engine-repository', options['--engine-repository'], '--engine-signer', options['--engine-signer'], '--cosign', options['--cosign'],
+    '--previous-lock', options[OFFERING_PREVIOUS_LOCK_FLAG], '--previous-lock-sha256', options[OFFERING_PREVIOUS_LOCK_SHA256_FLAG],
+    '--local', ...roots,
+  ];
+}
+
+/** The vendor step: a child `develop resolve` of this CLI on the vendor roots, writing into `outDir`. */
+export function runVendorResolve({ offeringId, pinsFile, outDir, options, env, roots }) {
+  const result = spawnSync(process.execPath, vendorResolveArgs({ offeringId, pinsFile, outDir, options, roots }), { env, stdio: ['ignore', 'ignore', 'inherit'] });
+  if (result.error !== undefined || result.status !== 0) {
+    throw new Error(`the vendor resolve of the offering "${offeringId}" failed (${result.error?.message ?? `exit ${result.status ?? result.signal}`}); its refusal is above`);
+  }
+}
+
+/**
+ * The catalogue the vendor step wrote, its digest, the engine it proved, and the proof the vendor artifact is that offering
+ * at those pins. (The digest is of `bytes` as read, the same bytes parsed: never a re-serialisation.)
+ */
+export function readVendorCatalogue({ outDir, offeringId, vendorPins }) {
+  const path = join(outDir, CATALOGUE_FILE);
+  const bytes = readFileSync(path);
+  const catalogue = parseCatalogue(parseStrictJson(bytes.toString('utf8'), path));
+  if (catalogue.offeringId !== offeringId || catalogue.channel !== EditionChannel.Develop) {
+    throw new Error(`the vendor step wrote the catalogue of "${catalogue.offeringId}" (${catalogue.channel}), not of the develop offering "${offeringId}"`);
+  }
+  const descriptor = parseEditionDescriptor(readStrictJsonFile(join(outDir, EDITION_DESCRIPTOR_FILE)));
+  if (serializeJson(sortedSnapshotPins(descriptor.provenance.pins)) !== serializeJson(vendorPins)) {
+    throw new Error(`the vendor step resolved "${offeringId}" at other pins than the vendor pins it was given`);
+  }
+  return { catalogue, catalogueContentDigest: catalogueContentDigestOf(bytes), engineImage: descriptor.engine.image };
+}
+
+/** Run `body` with the workspace on `roots`, restoring the previous roots after. */
+async function onRoots(roots, body) {
+  const restored = configuredWorkspace();
+  resetEditionWorkspaceConfig();
+  configureEditionWorkspace(roots);
+  try {
+    return await body();
+  } finally {
+    resetEditionWorkspaceConfig();
+    configureEditionWorkspace(restored);
+  }
+}
+
+/**
+ * The catalogue-free customer develop resolve (see the header). Writes the artifact to --out and returns
+ * `{ id, pins, target, catalogueContentDigest, engineImage }`. The edition records the engine the vendor step proved, and
+ * carries the customer's own composed generations from --previous-lock (or --first-seal) under the customer's id.
+ * `fetchDefinition`, `vendorResolve`, `resolveCustomer`, `evidenceTrust` and `write` are replaced by tests; `print`
+ * receives the target.
+ */
+export async function resolveCatalogueFree({
+  options,
+  env = process.env,
+  fetchDefinition = fetchDefinitionRepository,
+  vendorResolve = runVendorResolve,
+  resolveCustomer = resolveCustomerChannelEdition,
+  evidenceTrust = descriptorEvidenceTrust,
+  write = writeEditionArtifact,
+  print = (line) => console.log(line),
+}) {
+  const definition = parseFollowDefinition(options[DEFINITION_AT_FLAG], DEFINITION_AT_FLAG);
+  const offering = parseFollowDefinition(options[OFFERING_FLAG], OFFERING_FLAG);
+  const rawPins = readStrictJsonFile(options['--pins']);
+  const offeringId = assertDefinitionCheckout({ definition: offering, dataSha: rawPins?.[dataPinKey()], flag: OFFERING_FLAG, shaLabel: `--pins "${dataPinKey()}"` });
+  const { definitionRepositoryCommit, members } = splitCatalogueFreePins(rawPins);
+  const offeringLabel = `${offering.repository}:${offering.path}/${DEFINITION_FILE}`;
+  const offeringSourceNames = declaredSourceNamesOf(readStrictJsonFile(join(editionsRoot(), offeringId, DEFINITION_FILE)));
+  const vendorRoots = configuredWorkspace();
+  const scratch = mkdtempSync(join(tmpdir(), 'xema-catalogue-free-'));
+  try {
+    const cached = fetchDefinition({ repository: definition.repository, commit: definitionRepositoryCommit, env });
+    const checkout = materializeDefinitionCommit({ repository: cached, commit: definitionRepositoryCommit, into: join(scratch, DEFINITION_REPOSITORY_PIN_KEY) });
+    const definitionDir = join(checkout, definition.path);
+    const definitionLabel = `${definition.repository}:${definition.path}/${DEFINITION_FILE}`;
+    if (existsSync(join(definitionDir, CATALOGUE_PIN_FILE))) {
+      throw new Error(`${definition.repository}:${definition.path} carries ${CATALOGUE_PIN_FILE}: a definition is resolved against its pinned catalogue (--definition <file>) or catalogue-free, never both`);
+    }
+    const rawDefinition = readStrictJsonFile(join(definitionDir, DEFINITION_FILE));
+    assertCanonicalDistributionId(rawDefinition?.id);
+    if (rawDefinition.id !== basename(definition.path)) {
+      throw new Error(`${definitionLabel} is "${rawDefinition.id}", not the directory's "${basename(definition.path)}"`);
+    }
+    const split = partitionCatalogueFreePins(members, {
+      offering: { label: offeringLabel, sourceNames: offeringSourceNames },
+      definition: { label: definitionLabel, sourceNames: declaredSourceNamesOf(rawDefinition) },
+    });
+    const sourceImages = customerSourceImages(options, rawDefinition);
+    const vendorOut = join(scratch, 'vendor');
+    const pinsFile = join(scratch, 'vendor-pins.json');
+    writeFileSync(pinsFile, serializeJson(split.vendor));
+    vendorResolve({ offeringId, pinsFile, outDir: vendorOut, options, env, roots: workspaceArgv() });
+    const { catalogue, catalogueContentDigest, engineImage } = readVendorCatalogue({ outDir: vendorOut, offeringId, vendorPins: split.vendor });
+    const sources = join(scratch, 'sources');
+    mkdirSync(sources);
+    const customerRoots = {
+      [WorkspaceRoot.Data]: join(checkout, definition.dataRoot),
+      [WorkspaceRoot.Editions]: dirname(definitionDir),
+      [WorkspaceRoot.Sources]: sources,
+      [WorkspaceRoot.Cache]: vendorRoots[WorkspaceRoot.Cache],
+    };
+    return await onRoots(customerRoots, async () => {
+      const { id, pins, ...resolved } = await resolveCustomer({
+        channel: EditionChannel.Develop,
+        rawDefinition,
+        catalogue,
+        catalogueContentDigest,
+        pins: split.own,
+        vendorPins: { ...split.vendor, [DEFINITION_REPOSITORY_PIN_KEY]: definitionRepositoryCommit },
+        previousSeal: customerPreviousSeal(EditionChannel.Develop, options),
+        sourceImages,
+        env,
+        // The customer's git-sourced OCI bundles, verified under the definition's own pinned policy (its data root).
+        developGitBundles: customerDevelopGitBundleVerifier({ channel: EditionChannel.Develop, cosignBinary: options['--cosign'], env }),
+      });
+      const evidenceTrustPolicy = await evidenceTrust({ kind: EditionKind.Resolved, channel: EditionChannel.Develop, consumesCatalogue: true });
+      const target = snapshotEditionTarget(EditionChannel.Develop, id, pins, { registry: options['--registry'], engineImage, sourceImages });
+      write({
+        outDir: resolve(options['--out']),
+        channel: EditionChannel.Develop,
+        distributionId: id,
+        pins,
+        workflow: options['--local'] ? LOCAL_WORKFLOW : workflowFromEnv(env),
+        evidenceTrustPolicy,
+        engineImage,
+        distributionLock: resolved.distributionLock,
+        imageLock: resolved.imageLock,
+        authorizationLock: resolved.authorizationLock,
+        chartSetLock: resolved.chartSetLock,
+      });
+      print(target);
+      return { id, pins, target, catalogueContentDigest, engineImage };
+    });
+  } finally {
+    rmSync(scratch, { recursive: true, force: true });
+  }
+}

package/edition/develop-edition.mjs

@@ -23,6 +23,23 @@
 //       declares (`freeze-sources --definition` writes it); the catalogue digest is frozen into the descriptor's
 //       provenance pins as `catalogue`. The id is the definition's. Takes --data-root, --editions-root,
 //       --sources-root, --cache-dir (no --deploy-root, no --kernel: the kernel is the catalogue's, from npm).
+//       It takes the customer edition's OWN previous seal, exactly one of --previous-lock <file> --previous-lock-sha256 <hex>
+//       (the customer edition's last images lock: sha256 of its bytes, its id the definition's) or --first-seal; it carries
+//       the generations of the customer's own composed artifacts forward (vendor rows are the catalogue's, unchanged).
+//   resolve --definition-at <owner>/<repo>,<path>,<dataRoot> --offering <owner>/<repo>,<path>,<dataRoot>
+//           --pins <file> --out <dir> --registry <root> --engine-repository <repository> --engine-signer <certificate identity>
+//           --cosign <absolute-path> --offering-previous-lock <file> --offering-previous-lock-sha256 <hex>
+//           (--previous-lock <file> --previous-lock-sha256 <hex> | --first-seal) [--source-image <source>=<registry>/<prefix>]... [--local]
+//       a CATALOGUE-FREE customer develop edition (develop-catalogue-free-resolve.mjs): the vendor offering named by
+//       --offering (its directory in the vendor data checkout) is resolved first by a child `resolve` on the vendor
+//       roots, sealed against the OFFERING's previous seal (--offering-previous-lock, as `follow` froze it, held to its
+//       sha256 and the offering's id) with the engine it finds and proves; then the definition, read from its repository at
+//       --pins "definition-repository", is resolved against the catalogue that child wrote, on its own roots, carrying the
+//       customer's own composed generations from --previous-lock (or --first-seal). --pins is the complete frozen set (the
+//       vendor pins, the definition's sources/<name>, "definition-repository"); no head is read and nothing is pushed. The
+//       edition pins those and the definition digest, no catalogue (the catalogue's content digest is in the distribution
+//       lock only), and records the vendor step's engine. catalogue.pin.json beside the definition is refused.
+//       Takes the vendor roots.
 //   engine  <id> --pins <file> --engine-repository <repository> --engine-signer <certificate identity> --cosign <absolute-path>
 //       print <repository>@sha256:<digest>: the engine xema-deploy CI published (tag sha-<12 hex>) for the
 //       snapshot's xema-deploy commit, its signature verified offline against the pinned trust root as made by
@@ -87,6 +104,22 @@
 //       part 07 passes the flag.
 //       Residual: anyone who can delete registry tags can remove newer records, and this then pins the newest remaining
 //       valid one; the guard is part 07's, deploy-latest's owner refuses a snapshot that goes backwards.
+//   follow --definition-at <owner>/<repo>,<path>,<dataRoot> --data-sha <sha> --kernel-sha <sha> --deploy-sha <upper bound>
+//          --engine-repository <registry>/<path> --registry <root> --cosign <absolute-path> (--first | --current-pins <file>) --out <file>
+//       the pins a dev deployment's follow policy selects (develop-follow.mjs), written once (wx) as the COMPLETE frozen
+//       set `resolve` reads; nothing else is read or written. The data root checkout is the definition: the data root's
+//       declared repository, clean at --data-sha, its data root and distribution directory at dataRoot and path, and the
+//       editions root that same repository; the kernel checkout is at --kernel-sha. Members: select-records' newest-commit
+//       rule over their signed build records (the same verifier), with the --current-pins as the published pins (behind or
+//       equal keeps the current pin, diverged is refused by name), pinned as freeze-graph --member-pins pins them (a member
+//       that keeps its current resolution at its develop head). Deploy root: --deploy-sha is an UPPER BOUND, the pin the
+//       newest first-parent commit of the deploy checkout at or below it whose engine <--engine-repository>:sha-<12 hex> is
+//       published (unpublished skipped and counted, none within the walk limit refused by name). Tooling roots:
+//       freeze-graph's rules, then each classified against its current pin by ancestry in its own checkout (behind,
+//       diverged or absent from the checkout is refused by type). Declared sources: their develop heads, newer-wins
+//       against the current pin by the same ancestry rule. Prints {distributionId, definition, follow: first |
+//       from-current, tooling, advanced, kept, added, dropped, deploy: {deploySha, upperBound, skipped}}: --first says so
+//       and classifies nothing. Takes the roots `resolve` takes.
 //   image-record <id> --selection <file> --pins <file> --out <file>
 //       write the edition's image build record (the file `resolve --images-from` reads) from a select-records selection:
 //       the subjects are the checked-out snapshot's first-party image subjects (enumerated as `coverage` does). A subject of
@@ -120,10 +153,12 @@ import { resolve } from 'node:path';
 import { writeCatalogue } from './catalogue.mjs';
 import { CUSTOMER_ROOTS, FIRST_SEAL_FLAG, IMAGES_FROM_FLAG, PREVIOUS_LOCK_FLAG, PREVIOUS_LOCK_SHA256_FLAG, headResolver, parseEditionVerbArgs, runCustomerVerb, writeOnce } from './customer-edition-verbs.mjs';
 import { DEFINITION_FLAG } from './customer-flags.mjs';
+import { resolveCatalogueFree } from './develop-catalogue-free-resolve.mjs';
 import { runDevelopCoverage } from './develop-coverage-run.mjs';
 import { CoverageExit } from './develop-coverage.mjs';
 import { resolveDevelopEdition } from './develop-edition-resolve.mjs';
 import { resolveDevelopEngineImage } from './develop-engine-image.mjs';
+import { runFollow } from './develop-follow.mjs';
 import { assertNoToolingOverride, freezeGraph, freezeSources } from './develop-freeze.mjs';
 import { developGraphMembers } from './develop-graph.mjs';
 import { runImageRecord } from './develop-image-record.mjs';
@@ -189,7 +224,7 @@ async function imageBuildRecordTagInput(options) {
 }
 
 async function run(argv, env) {
-  const { command, id, options, customer } = parseDevelopEditionArgs(argv);
+  const { command, id, options, customer, catalogueFree } = parseDevelopEditionArgs(argv);
   switch (command) {
     case 'target': {
       if (customer) {return runCustomerVerb({ channel: EditionChannel.Develop, command, options, env });}
@@ -198,6 +233,10 @@ async function run(argv, env) {
     }
     case 'resolve': {
       if (customer) {return runCustomerVerb({ channel: EditionChannel.Develop, command, options, env });}
+      if (catalogueFree) {
+        await resolveCatalogueFree({ options, env });
+        return;
+      }
       const pins = readStrictJsonFile(options['--pins']);
       const workflow = options['--local'] ? LOCAL_WORKFLOW : workflowFromEnv(env);
       const evidenceTrustPolicy = await descriptorEvidenceTrust({ kind: EditionKind.Resolved, channel: EditionChannel.Develop });
@@ -262,6 +301,9 @@ async function run(argv, env) {
         json: options['--json'] === true,
         env,
       });
+    case 'follow':
+      await runFollow({ options, env });
+      return;
     case 'select-records':
       await runSelectRecords({ options, env });
       return;