frontend-project-context 1.3.0 → 1.6.0

package/src/project-context/upgrade.mjs

@@ -0,0 +1,494 @@
+import { lstat, readFile } from "node:fs/promises";
+import path from "node:path";
+import { AI_ENTRY_RENDERER_VERSION, inspectAiEntry, publishAiEntry } from "./ai-entry.mjs";
+import { PERMANENT_BOUNDARIES } from "./capabilities.mjs";
+import { sha256 } from "./canonical-json.mjs";
+import { sourceStatus } from "./contract-schema.mjs";
+import { fail } from "./errors.mjs";
+import { BUILT_IN_MIGRATIONS, loadMigrationManifest } from "./migration-manifest.mjs";
+import { normalizeRelativePath, resolveExistingInside } from "./path-policy.mjs";
+import { inspectProjectInitialization, loadProject } from "./project-store.mjs";
+import { publishProjection } from "./projection-store.mjs";
+import { parseProjectionMarker, RENDERER_VERSION, renderProjection } from "./renderer.mjs";
+import { findConflicts, validateOverrides } from "./scope-compiler.mjs";
+import {
+  finalizeMigrationPlan,
+  finalizeUpgradeAssessment,
+  finalizeUpgradeResult,
+  validateMigrationPlan,
+  validateUpgradeAssessment,
+  validateUpgradeResult,
+} from "./upgrade-schema.mjs";
+
+const ARTIFACT_DIRECTORY = ".project-context/";
+const STORE_FILES = new Set([
+  ".project-context/contract.json",
+  ".project-context/sources.lock.json",
+  ".project-context/projections.lock.json",
+]);
+const HOST_ACCEPTANCE = Object.freeze([
+  "dependency-and-lockfile",
+  "independent-new-window",
+  "project-tests-or-ci",
+]);
+const REPAIRABLE_FINDINGS = new Set(["ai-entry-renderer-stale", "projection-renderer-stale"]);
+
+function snapshots(project) {
+  if (!project) return null;
+  return {
+    contract: project.contractDigest,
+    sourcesLock: project.sourcesLockDigest,
+    projectionsLock: project.projectionsLockDigest,
+  };
+}
+
+function pathFor(manifest, fromVersion) {
+  const selected = manifest.paths.find((entry) => entry.fromVersion === fromVersion);
+  if (!selected) fail("upgrade-source-version-unsupported", `unsupported upgrade source version: ${fromVersion}`, { exitCode: 2 });
+  return selected;
+}
+
+function ensureSourceVersion(manifest, fromVersion) {
+  if (!manifest.upgradeFrom.includes(fromVersion)) {
+    fail("upgrade-source-version-unsupported", `unsupported upgrade source version: ${fromVersion}`, {
+      exitCode: 2,
+      details: { supported: manifest.upgradeFrom },
+    });
+  }
+}
+
+function storeCompatibility(project, manifest) {
+  if (!project) return Object.fromEntries(Object.keys(manifest.stores).map((name) => [name, "not-applicable"]));
+  const versions = {
+    contract: project.contract.schemaVersion,
+    sourceLock: project.sourcesLock.schemaVersion,
+    projectionLock: project.projectionsLock.schemaVersion,
+    proposal: 1,
+  };
+  return Object.fromEntries(Object.entries(versions).map(([name, version]) => [
+    name,
+    manifest.stores[name].readable.includes(version) ? "compatible" : "unsupported",
+  ]));
+}
+
+function rendererCompatibility(project, manifest) {
+  if (!project) return { aiEntry: "not-applicable", projection: "not-applicable" };
+  const entries = project.projectionsLock.projections;
+  const aiEntries = entries.filter((entry) => entry.ownership === "region" && entry.target === "ai-entry");
+  const projections = entries.filter((entry) => entry.ownership !== "region");
+  const state = (selected, matrix) => {
+    if (selected.length === 0) return "compatible";
+    if (selected.some((entry) => !matrix.readable.includes(entry.rendererVersion))) return "unsupported";
+    return selected.some((entry) => entry.rendererVersion !== matrix.written) ? "republish" : "compatible";
+  };
+  return {
+    aiEntry: state(aiEntries, manifest.renderers.aiEntry),
+    projection: state(projections, manifest.renderers.projection),
+  };
+}
+
+function protocolCompatibility(manifest) {
+  return Object.fromEntries(Object.keys(manifest.protocols).sort().map((name) => {
+    const change = manifest.consumerChanges[name];
+    return [name, change?.state === "invalidate" ? "invalidate" : change?.state === "regenerate" ? "regenerate" : "compatible"];
+  }));
+}
+
+function selectedMigrationIds(project, migrationPath, manifest) {
+  if (!project) return [];
+  const available = new Set(migrationPath.migrationIds);
+  const selected = [];
+  if (
+    available.has("upgrade.republish-ai-entry.v1") &&
+    project.projectionsLock.projections.some((entry) => entry.ownership === "region" && entry.target === "ai-entry" && entry.rendererVersion !== manifest.renderers.aiEntry.written)
+  ) selected.push("upgrade.republish-ai-entry.v1");
+  if (
+    available.has("upgrade.republish-projection.v1") &&
+    project.projectionsLock.projections.some((entry) => entry.ownership !== "region" && entry.rendererVersion !== manifest.renderers.projection.written)
+  ) selected.push("upgrade.republish-projection.v1");
+  return selected.sort((left, right) => left.localeCompare(right));
+}
+
+function assessmentEntry(status) {
+  return {
+    state: status?.entry?.state ?? "absent",
+    path: status?.entry?.path ?? null,
+    rendererVersion: status?.entry?.rendererVersion ?? null,
+  };
+}
+
+async function inspectUpgradeState(root, project) {
+  const findings = [];
+  const contractSources = new Map(project.contract.sources.map((source) => [source.id, source]));
+  const lockedSources = new Map(project.sourcesLock.sources.map((entry) => [entry.id, entry.digest]));
+  for (const source of project.contract.sources) {
+    if (sourceStatus(source) === "deprecated") continue;
+    const locked = lockedSources.get(source.id);
+    if (!locked) findings.push({ code: "source-lock-missing", source: source.id });
+    else if (source.digest !== undefined && source.digest !== locked) findings.push({ code: "source-lock-mismatch", source: source.id });
+  }
+  for (const entry of project.sourcesLock.sources) {
+    const source = contractSources.get(entry.id);
+    if (!source) findings.push({ code: "source-lock-orphan", source: entry.id });
+    else if (sourceStatus(source) === "deprecated") findings.push({ code: "source-lock-deprecated", source: entry.id });
+  }
+  for (const item of project.contract.items) if (item.status === "proposed") findings.push({ code: "item-approval-pending", item: item.id });
+  findings.push(...validateOverrides(project.contract.items), ...findConflicts(project.contract.items));
+
+  const regionEntries = project.projectionsLock.projections
+    .filter((entry) => entry.ownership === "region" && entry.target === "ai-entry")
+    .sort((left, right) => left.path.localeCompare(right.path));
+  let entry = { state: "absent", path: null, rendererVersion: null };
+  if (regionEntries.length > 0) {
+    entry = await inspectAiEntry(root, project, regionEntries[0].path);
+    if (entry.state === "conflict") findings.push({ code: "ai-entry-ownership-conflict", path: entry.path });
+    else if (entry.state === "stale") findings.push({ code: "ai-entry-renderer-stale", path: entry.path });
+  }
+
+  for (const lockEntry of project.projectionsLock.projections.filter((candidate) => candidate.ownership !== "region")) {
+    let content;
+    try {
+      const candidate = path.join(root, lockEntry.path);
+      if ((await lstat(candidate)).isSymbolicLink()) throw new Error("managed target is a symlink");
+      const resolved = await resolveExistingInside(root, lockEntry.path);
+      content = await readFile(resolved.absolute, "utf8");
+    } catch (error) {
+      findings.push({ code: error?.code === "source-missing" || error?.code === "ENOENT" ? "projection-missing" : "projection-unreadable", path: lockEntry.path });
+      continue;
+    }
+    const marker = parseProjectionMarker(content);
+    if (!marker || sha256(content) !== lockEntry.contentDigest || marker.target !== lockEntry.target || marker.rendererVersion !== lockEntry.rendererVersion) {
+      findings.push({ code: "projection-ownership-conflict", path: lockEntry.path });
+      continue;
+    }
+    if (lockEntry.rendererVersion !== RENDERER_VERSION) {
+      findings.push({ code: "projection-renderer-stale", path: lockEntry.path });
+      continue;
+    }
+    if (lockEntry.contractDigest !== project.contractDigest || marker.contractDigest !== project.contractDigest) {
+      findings.push({ code: "projection-stale", path: lockEntry.path });
+      continue;
+    }
+    const expected = renderProjection(project.contract, lockEntry.paths, lockEntry.target);
+    if (expected.content !== content || expected.bundleDigest !== lockEntry.bundleDigest) findings.push({ code: "projection-diverged", path: lockEntry.path });
+  }
+  findings.sort((left, right) => left.code.localeCompare(right.code) || String(left.path ?? left.source ?? left.item ?? "").localeCompare(String(right.path ?? right.source ?? right.item ?? "")));
+  const conflict = findings.some((finding) => finding.code.includes("ownership-conflict"));
+  return {
+    health: conflict ? "conflict" : findings.length > 0 ? "attention" : "clean",
+    entry,
+    findingCodes: [...new Set(findings.map((finding) => finding.code))].sort((left, right) => left.localeCompare(right)),
+  };
+}
+
+export async function buildUpgradeAssessment(root, fromVersion, dependencies = {}) {
+  const manifest = await loadMigrationManifest(dependencies.manifest);
+  ensureSourceVersion(manifest, fromVersion);
+  const migrationPath = pathFor(manifest, fromVersion);
+  const initialization = await inspectProjectInitialization(root);
+  let project = null;
+  let status;
+  if (initialization.status === "initialized") {
+    try {
+      project = await loadProject(root);
+      status = await inspectUpgradeState(root, project);
+    } catch (error) {
+      project = null;
+      status = {
+        health: "invalid",
+        entry: { state: "absent", path: null, rendererVersion: null },
+        findingCodes: [error?.code?.startsWith?.("schema-") ? "upgrade-store-unsupported" : "project-state-invalid"],
+      };
+    }
+  } else {
+    status = {
+      health: initialization.status,
+      entry: { state: "absent", path: null, rendererVersion: null },
+      findingCodes: initialization.status === "partial" ? ["project-state-partial"] : [],
+    };
+  }
+  if (initialization.status === "initialized" && !project) {
+    status ??= { health: "invalid", entry: { state: "absent", path: null, rendererVersion: null }, findingCodes: ["project-state-invalid"] };
+  }
+  const stores = storeCompatibility(project, manifest);
+  const renderers = rendererCompatibility(project, manifest);
+  const actionable = selectedMigrationIds(project, migrationPath, manifest);
+  const unsupportedStore = Object.values(stores).includes("unsupported");
+  const unsupportedRenderer = Object.values(renderers).includes("unsupported");
+  if (unsupportedRenderer && !status.findingCodes.includes("upgrade-renderer-unsupported")) status.findingCodes.push("upgrade-renderer-unsupported");
+  const onlyRepairable = status.findingCodes.every((code) => REPAIRABLE_FINDINGS.has(code));
+  let state;
+  if (initialization.status === "uninitialized") state = "not-applicable";
+  else if (status.health === "clean") state = "core-complete";
+  else if (!unsupportedStore && !unsupportedRenderer && actionable.length > 0 && onlyRepairable) state = "ready-for-plan";
+  else state = "blocked";
+  const chosenRollback = actionable.length > 0 ? "forward-only" : migrationPath.rollbackClass;
+  return validateUpgradeAssessment(finalizeUpgradeAssessment({
+    schemaVersion: 1,
+    kind: "upgrade-assessment",
+    product: { name: "frontend-project-context" },
+    fromVersion,
+    targetVersion: manifest.package.version,
+    fromVersionEvidence: "host-asserted",
+    manifestSchemaVersion: manifest.schemaVersion,
+    manifestDigest: manifest.manifestDigest,
+    initialization: {
+      state: initialization.status === "initialized" && !project ? "invalid" : initialization.status,
+      present: [...initialization.present].sort((left, right) => left.localeCompare(right)),
+      missing: [...initialization.missing].sort((left, right) => left.localeCompare(right)),
+    },
+    health: status.health,
+    entryState: assessmentEntry(status),
+    findingCodes: [...new Set(status.findingCodes)].sort((left, right) => left.localeCompare(right)),
+    snapshots: snapshots(project),
+    compatibility: { stores, renderers, protocols: protocolCompatibility(manifest) },
+    migrationPath: actionable,
+    rollbackClass: chosenRollback,
+    requiresHumanReview: migrationPath.requiresHumanReview || chosenRollback === "forward-only",
+    state,
+    boundaries: { ...PERMANENT_BOUNDARIES },
+  }));
+}
+
+async function readArtifact(root, relativePath, kind) {
+  let normalized;
+  try {
+    normalized = normalizeRelativePath(relativePath, { label: `${kind} path` });
+  } catch (error) {
+    fail(`upgrade-${kind}-invalid`, `${kind} path must stay inside the project`, { cause: error });
+  }
+  if (!normalized.startsWith(ARTIFACT_DIRECTORY) || STORE_FILES.has(normalized) || !normalized.endsWith(".json")) {
+    fail(`upgrade-${kind}-invalid`, `${kind} must be a non-store JSON file inside .project-context/`);
+  }
+  const candidate = path.join(root, normalized);
+  try {
+    if ((await lstat(candidate)).isSymbolicLink()) fail(`upgrade-${kind}-invalid`, `${kind} cannot be a symlink`);
+    const resolved = await resolveExistingInside(root, normalized);
+    return JSON.parse(await readFile(resolved.absolute, "utf8"));
+  } catch (error) {
+    if (error?.code?.startsWith?.("upgrade-")) throw error;
+    fail(`upgrade-${kind}-invalid`, `cannot read ${kind}`, { cause: error, details: { path: normalized } });
+  }
+}
+
+async function currentTargetDigest(root, target) {
+  try {
+    const resolved = await resolveExistingInside(root, target);
+    return sha256(await readFile(resolved.absolute));
+  } catch (error) {
+    if (error?.code === "source-missing") return null;
+    throw error;
+  }
+}
+
+function actionCandidates(project, assessment) {
+  const entries = [...project.projectionsLock.projections].sort((left, right) => left.path.localeCompare(right.path));
+  const actions = [];
+  if (assessment.migrationPath.includes("upgrade.republish-ai-entry.v1")) {
+    for (const entry of entries.filter((candidate) => candidate.ownership === "region" && candidate.target === "ai-entry" && candidate.rendererVersion !== AI_ENTRY_RENDERER_VERSION)) {
+      actions.push({
+        id: `republish-ai-entry:${entry.path}`,
+        kind: "republish-ai-entry",
+        migrationId: "upgrade.republish-ai-entry.v1",
+        targets: [entry.path],
+        writes: true,
+        semanticImpact: "managed-rendering",
+      });
+    }
+  }
+  if (assessment.migrationPath.includes("upgrade.republish-projection.v1")) {
+    for (const entry of entries.filter((candidate) => candidate.ownership !== "region" && candidate.rendererVersion !== RENDERER_VERSION)) {
+      actions.push({
+        id: `republish-projection:${entry.path}`,
+        kind: "republish-projection",
+        migrationId: "upgrade.republish-projection.v1",
+        targets: [entry.path],
+        writes: true,
+        semanticImpact: "managed-rendering",
+      });
+    }
+  }
+  return actions;
+}
+
+async function validateAssessmentCurrent(root, assessment, manifest, dependencies = {}) {
+  if (assessment.manifestDigest !== manifest.manifestDigest) fail("upgrade-assessment-stale", "assessment manifest digest is stale", { exitCode: 1 });
+  const current = await buildUpgradeAssessment(root, assessment.fromVersion, dependencies);
+  if (current.assessmentDigest !== assessment.assessmentDigest) {
+    fail("upgrade-assessment-stale", "assessment no longer matches current Project Context bytes", {
+      exitCode: 1,
+      details: { expected: assessment.assessmentDigest, actual: current.assessmentDigest },
+    });
+  }
+}
+
+export async function buildMigrationPlan(root, assessmentInput, dependencies = {}) {
+  const assessment = validateUpgradeAssessment(assessmentInput);
+  const manifest = await loadMigrationManifest(dependencies.manifest);
+  await validateAssessmentCurrent(root, assessment, manifest, dependencies);
+  if (assessment.state === "not-applicable" || assessment.state === "blocked") {
+    fail("upgrade-project-state-blocked", `upgrade assessment is ${assessment.state}`, { exitCode: 1, details: { findingCodes: assessment.findingCodes } });
+  }
+  const project = await loadProject(root);
+  const candidates = actionCandidates(project, assessment);
+  const nextAction = candidates[0] ?? {
+    id: "verify-core-migration-complete",
+    kind: "verify-complete",
+    migrationId: null,
+    targets: [],
+    writes: false,
+    semanticImpact: "none",
+  };
+  const targetDigests = [];
+  for (const target of nextAction.targets) targetDigests.push({ path: target, beforeDigest: await currentTargetDigest(root, target) });
+  const runtime = nextAction.migrationId ? manifest.builtInMigrations.find((entry) => entry.id === nextAction.migrationId) : null;
+  if (nextAction.migrationId && (!runtime || BUILT_IN_MIGRATIONS[nextAction.migrationId] !== nextAction.kind)) {
+    fail("upgrade-migration-unsupported", `migration is not compiled into this runtime: ${nextAction.migrationId}`, { exitCode: 1 });
+  }
+  const remainingMigrationIds = [...new Set(candidates.slice(1).map((entry) => entry.migrationId))].sort((left, right) => left.localeCompare(right));
+  const migrationPath = pathFor(manifest, assessment.fromVersion);
+  const rollbackClass = runtime?.rollbackClass ?? assessment.rollbackClass;
+  return validateMigrationPlan(finalizeMigrationPlan({
+    schemaVersion: 1,
+    kind: "target-upgrade-plan",
+    fromVersion: assessment.fromVersion,
+    targetVersion: assessment.targetVersion,
+    manifestDigest: manifest.manifestDigest,
+    assessmentDigest: assessment.assessmentDigest,
+    snapshots: assessment.snapshots,
+    targetDigests,
+    nextAction,
+    remainingMigrationIds,
+    acceptance: { core: migrationPath.acceptance, hostRequired: [...HOST_ACCEPTANCE] },
+    rollback: {
+      class: rollbackClass,
+      reverseMigrationId: runtime?.reverseMigrationId ?? null,
+      externalRestoreRequired: nextAction.writes && runtime?.reverseMigrationId === null,
+    },
+    requiresHumanReview: migrationPath.requiresHumanReview || nextAction.writes && runtime?.reverseMigrationId === null,
+    authority: "human-explicit-write-required",
+  }));
+}
+
+export async function buildMigrationPlanFile(root, assessmentPath, dependencies = {}) {
+  return buildMigrationPlan(root, await readArtifact(root, assessmentPath, "assessment"), dependencies);
+}
+
+async function validatePlanCurrent(root, plan, manifest, dependencies = {}) {
+  if (plan.manifestDigest !== manifest.manifestDigest) fail("upgrade-plan-stale", "plan manifest digest is stale", { exitCode: 1 });
+  const current = await buildUpgradeAssessment(root, plan.fromVersion, dependencies);
+  if (current.assessmentDigest !== plan.assessmentDigest) fail("upgrade-plan-stale", "plan assessment baseline is stale", { exitCode: 1 });
+  const currentSnapshots = current.snapshots;
+  if (JSON.stringify(currentSnapshots) !== JSON.stringify(plan.snapshots)) fail("upgrade-plan-stale", "plan store snapshots are stale", { exitCode: 1 });
+  for (const target of plan.targetDigests) {
+    const actual = await currentTargetDigest(root, target.path);
+    if (actual !== target.beforeDigest) fail("upgrade-plan-stale", `plan target changed: ${target.path}`, { exitCode: 1, details: { path: target.path } });
+  }
+  const expectedPlan = await buildMigrationPlan(root, current, dependencies);
+  if (expectedPlan.planDigest !== plan.planDigest) fail("upgrade-plan-invalid", "plan is not the current compiler-selected single work unit");
+  return current;
+}
+
+async function targetStates(root, targets, before) {
+  const values = [];
+  for (const target of targets) values.push({ path: target, beforeDigest: before.get(target) ?? null, afterDigest: await currentTargetDigest(root, target) });
+  return values;
+}
+
+async function afterSnapshots(root) {
+  try {
+    return snapshots(await loadProject(root));
+  } catch {
+    return null;
+  }
+}
+
+function resultBundle(plan, manifest, options) {
+  return validateUpgradeResult(finalizeUpgradeResult({
+    schemaVersion: 1,
+    kind: "upgrade-result-bundle",
+    product: { name: "frontend-project-context" },
+    fromVersion: plan.fromVersion,
+    targetVersion: plan.targetVersion,
+    manifestDigest: manifest.manifestDigest,
+    planDigest: plan.planDigest,
+    mode: options.mode,
+    action: plan.nextAction,
+    written: options.written,
+    targets: options.targets,
+    snapshots: { before: plan.snapshots, after: options.afterSnapshots },
+    actionResult: options.actionResult,
+    findingCodes: options.findingCodes,
+    coreMigration: options.coreMigration,
+    hostAcceptance: [...HOST_ACCEPTANCE],
+    overallUpgrade: "host-validation-required",
+  }));
+}
+
+export async function applyMigrationPlan(root, planInput, options = {}, dependencies = {}) {
+  const plan = validateMigrationPlan(planInput);
+  const manifest = await loadMigrationManifest(dependencies.manifest);
+  const assessment = await validatePlanCurrent(root, plan, manifest, dependencies);
+  const action = plan.nextAction;
+  const before = new Map(plan.targetDigests.map((entry) => [entry.path, entry.beforeDigest]));
+  if (action.kind === "verify-complete") {
+    const result = resultBundle(plan, manifest, {
+      mode: options.write ? "write" : "preview",
+      written: false,
+      targets: [],
+      afterSnapshots: assessment.snapshots,
+      actionResult: "verified",
+      findingCodes: [],
+      coreMigration: options.write ? "complete" : "previewed",
+    });
+    return { result, exitCode: 0 };
+  }
+  if (!action.migrationId || BUILT_IN_MIGRATIONS[action.migrationId] !== action.kind) {
+    fail("upgrade-migration-unsupported", `migration is not compiled into this runtime: ${action.migrationId ?? "missing"}`, { exitCode: 1 });
+  }
+  const project = await loadProject(root);
+  let operation;
+  try {
+    if (action.kind === "republish-ai-entry") {
+      operation = await publishAiEntry(root, project, { output: action.targets[0], write: options.write }, dependencies.aiEntry);
+    } else if (action.kind === "republish-projection") {
+      const entry = project.projectionsLock.projections.find((candidate) => candidate.path === action.targets[0]);
+      if (!entry || entry.ownership === "region") fail("upgrade-plan-stale", "projection target no longer exists", { exitCode: 1 });
+      operation = await publishProjection(root, project, { target: entry.target, output: entry.path, paths: entry.paths, write: options.write }, dependencies.projection);
+    } else {
+      fail("upgrade-migration-unsupported", `unsupported migration action: ${action.kind}`, { exitCode: 1 });
+    }
+  } catch (error) {
+    if (["ai-entry-ownership-conflict", "managed-file-ownership-conflict", "ai-entry-path-conflict"].includes(error?.code)) {
+      fail("upgrade-ownership-conflict", error.message, { exitCode: 1, cause: error, details: error.details });
+    }
+    if (["ai-entry-state-changed", "projection-state-changed", "project-state-changed"].includes(error?.code)) {
+      fail("upgrade-plan-stale", error.message, { exitCode: 1, cause: error, details: error.details });
+    }
+    const result = resultBundle(plan, manifest, {
+      mode: options.write ? "write" : "preview",
+      written: false,
+      targets: await targetStates(root, action.targets, before),
+      afterSnapshots: await afterSnapshots(root),
+      actionResult: `failed:${error?.code ?? "internal-error"}`,
+      findingCodes: ["upgrade-write-failed"],
+      coreMigration: "blocked",
+    });
+    return { result, exitCode: 2 };
+  }
+  const nextAssessment = options.write ? await buildUpgradeAssessment(root, plan.fromVersion, dependencies) : assessment;
+  const result = resultBundle(plan, manifest, {
+    mode: options.write ? "write" : "preview",
+    written: Boolean(options.write && operation.written),
+    targets: await targetStates(root, action.targets, before),
+    afterSnapshots: await afterSnapshots(root),
+    actionResult: operation.action,
+    findingCodes: options.write ? nextAssessment.findingCodes : [],
+    coreMigration: options.write ? nextAssessment.state === "core-complete" ? "complete" : "applied" : "previewed",
+  });
+  return { result, exitCode: 0 };
+}
+
+export async function applyMigrationPlanFile(root, planPath, options = {}, dependencies = {}) {
+  return applyMigrationPlan(root, await readArtifact(root, planPath, "plan"), options, dependencies);
+}