@microsoft/power-apps-native-host 0.2.22 → 0.2.25

package/scripts/upgrade-authoring.js

@@ -0,0 +1,535 @@
+'use strict';
+
+const childProcess = require('child_process');
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+const { setLockProvider, withLock } = require('@ster5/global-mutex');
+const { createTwoFilesPatch, parsePatch } = require('diff');
+const writeFileAtomic = require('write-file-atomic');
+const { HOST_PACKAGE, TEMPLATE_VERSION_PATH, assertSafeFilePath, hashContent, isCustomerOwnedPath, isHashOrNull, readJson } = require('./upgrade/runtime');
+
+const AUTHORING_LOCK_PATH = 'packages/power-apps-native-host/compatibility/.migration-build.lock';
+const AUTHORING_JOURNAL_PATH = 'packages/power-apps-native-host/compatibility/.migration-build-journal.json';
+const TEMPLATE_PATH = 'templates/expo-app-standalone';
+const MIGRATION_CHANGE_PATH = 'migration-change';
+const TSCONFIG_PATH = 'tsconfig.json';
+const CUSTOMER_SECTIONS = [
+  {
+    name: 'customer app settings',
+    start: '// CUSTOMER APP SETTINGS START - DO NOT REMOVE OR RENAME THE COMMENT',
+    end: '// CUSTOMER APP SETTINGS END - DO NOT REMOVE OR RENAME THE COMMENT',
+  },
+  {
+    name: 'customer customization',
+    start: '// CUSTOMIZATION START - DO NOT REMOVE OR RENAME THE COMMENT',
+    end: '// CUSTOMIZATION END - DO NOT REMOVE OR RENAME THE COMMENT',
+  },
+];
+
+setLockProvider('native');
+
+function findRepositoryRoot(startPath) {
+  const result = childProcess.spawnSync('git', ['rev-parse', '--show-toplevel'], { cwd: startPath, encoding: 'utf8' });
+  if (result.status !== 0) throw new Error('Migration authoring commands must run inside a Git repository');
+  return result.stdout.trim();
+}
+
+function git(repositoryRoot, args, allowFailure = false) {
+  const result = childProcess.spawnSync('git', args, { cwd: repositoryRoot, encoding: 'utf8' });
+  if (result.error) throw result.error;
+  if (result.status !== 0 && !allowFailure) throw new Error(`git ${args.join(' ')} failed: ${result.stderr.trim()}`);
+  return result.status === 0 ? result.stdout : null;
+}
+
+function resolveVersionTag(repositoryRoot, tag) {
+  if (!tag) throw new Error('change/check requires --from-tag <version-tag> or MIGRATION_BASE_TAG');
+  const tagRef = `refs/tags/${tag}`;
+  if (git(repositoryRoot, ['show-ref', '--verify', '--quiet', tagRef], true) === null) {
+    throw new Error(`${tag} is not a local Git tag; fetch tags or provide a valid --from-tag`);
+  }
+  const commit = git(repositoryRoot, ['rev-parse', `${tagRef}^{commit}`]).trim();
+  if (git(repositoryRoot, ['merge-base', '--is-ancestor', commit, 'HEAD'], true) === null) {
+    throw new Error(`Version tag ${tag} is not an ancestor of HEAD`);
+  }
+  return { tag, commit };
+}
+
+function getTemplateChanges(repositoryRoot, fromTag) {
+  const base = resolveVersionTag(repositoryRoot, fromTag);
+  const tracked = git(repositoryRoot, ['diff', '--no-renames', '--name-only', '--diff-filter=ACDMT', base.commit, '--', TEMPLATE_PATH])
+    .trim().split('\n').filter(Boolean);
+  const untracked = git(repositoryRoot, ['ls-files', '--others', '--exclude-standard', '--', TEMPLATE_PATH])
+    .trim().split('\n').filter(Boolean);
+  const paths = [...new Set([...tracked, ...untracked])].sort();
+  return {
+    baseTag: base.tag,
+    baseCommit: base.commit,
+    headCommit: git(repositoryRoot, ['rev-parse', 'HEAD']).trim(),
+    files: paths.map(filePath => {
+      const absolutePath = path.join(repositoryRoot, filePath);
+      const content = fs.existsSync(absolutePath) ? fs.readFileSync(absolutePath) : null;
+      return { path: filePath.slice(`${TEMPLATE_PATH}/`.length), targetHash: hashContent(content) };
+    }),
+  };
+}
+
+function readMigrationChanges(repositoryRoot) {
+  const directory = path.join(repositoryRoot, MIGRATION_CHANGE_PATH);
+  if (!fs.existsSync(directory)) return [];
+  return fs.readdirSync(directory)
+    .filter(name => name.endsWith('.json'))
+    .sort()
+    .map(name => validateMigrationChange(name, readJson(path.join(directory, name))));
+}
+
+function validateMigrationChange(name, record) {
+  if (record.schemaVersion !== 1 || record.type !== 'template-migration' || typeof record.baseTag !== 'string' || typeof record.baseCommit !== 'string') {
+    throw new Error(`Migration changelog ${name} has an invalid schema`);
+  }
+  if (!Array.isArray(record.files)) throw new Error(`Migration changelog ${name} has an invalid files list`);
+  const seen = new Set();
+  for (const file of record.files) {
+    if (!file || !isSafeTemplatePath(file.path) || !isHashOrNull(file.targetHash)) throw new Error(`Migration changelog ${name} contains invalid file metadata`);
+    if (seen.has(file.path)) throw new Error(`Migration changelog ${name} contains duplicate path ${file.path}`);
+    seen.add(file.path);
+  }
+  return { name, ...record };
+}
+
+function isSafeTemplatePath(relativePath) {
+  return typeof relativePath === 'string'
+    && relativePath.length > 0
+    && !relativePath.includes('\\')
+    && !path.posix.isAbsolute(relativePath)
+    && path.posix.normalize(relativePath) === relativePath
+    && !relativePath.split('/').includes('..');
+}
+
+function createMigrationChange(repositoryRoot, options) {
+  if (!options.message) throw new Error('change requires --message');
+  if (!options.fromTag) throw new Error('change requires --from-tag <version-tag> or MIGRATION_BASE_TAG');
+  const templateChanges = getTemplateChanges(repositoryRoot, options.fromTag);
+  assertNoCustomerOwnedChanges(templateChanges.files);
+  if (!templateChanges.files.length) throw new Error('No template changes were found');
+  const record = {
+    schemaVersion: 1,
+    type: 'template-migration',
+    comment: options.message,
+    createdAt: new Date().toISOString(),
+    ...templateChanges,
+  };
+  const slug = options.message.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').slice(0, 40) || 'template-change';
+  const relativePath = path.join(MIGRATION_CHANGE_PATH, `${slug}-${crypto.randomUUID().slice(0, 8)}.json`);
+  console.log(`${options.dryRun ? '[dry-run] ' : ''}Create ${relativePath}`);
+  if (!options.dryRun) {
+    fs.mkdirSync(path.dirname(path.join(repositoryRoot, relativePath)), { recursive: true });
+    fs.writeFileSync(path.join(repositoryRoot, relativePath), `${JSON.stringify(record, null, 2)}\n`);
+  }
+  return record;
+}
+
+function checkMigrationChanges(repositoryRoot, options) {
+  const records = readMigrationChanges(repositoryRoot);
+  const recordedTags = [...new Set(records.map(record => record.baseTag).filter(Boolean))];
+  const changes = getTemplateChanges(repositoryRoot, options.fromTag || (recordedTags.length === 1 ? recordedTags[0] : null));
+  assertNoCustomerOwnedChanges(changes.files);
+  const covered = new Set(records.flatMap(record => record.files || []).map(file => `${file.path}:${file.targetHash}`));
+  const current = new Set(changes.files.map(file => `${file.path}:${file.targetHash}`));
+  if (!changes.files.length) {
+    if (covered.size) throw new Error('Migration changelogs contain stale template changes but the template matches the version tag');
+    console.log('No template changes require a migration changelog.');
+    return;
+  }
+  const wrongBase = records.filter(record => record.baseTag !== changes.baseTag || record.baseCommit !== changes.baseCommit);
+  if (wrongBase.length) throw new Error(`Migration changelogs must all use version tag ${changes.baseTag}; regenerate: ${wrongBase.map(record => record.name).join(', ')}`);
+  const missing = changes.files.filter(file => !covered.has(`${file.path}:${file.targetHash}`));
+  const stale = [...covered].filter(file => !current.has(file));
+  if (missing.length) {
+    throw new Error(`Template changes require an up-to-date migration changelog:\n${missing.map(file => `  - ${file.path}`).join('\n')}\nRun upgrade-template change --from-tag ${changes.baseTag} --message "description"`);
+  }
+  if (stale.length) throw new Error(`Migration changelogs contain stale template changes:\n${stale.map(file => `  - ${file.split(':')[0]}`).join('\n')}`);
+  console.log(`${changes.files.length} template change(s) are covered by migration changelogs.`);
+}
+
+function assertNoCustomerOwnedChanges(files) {
+  const protectedFiles = files.filter(file => isCustomerOwnedPath(file.path));
+  if (protectedFiles.length) {
+    throw new Error(`Template migrations cannot modify customer-owned paths:\n${protectedFiles.map(file => `  - ${file.path}`).join('\n')}\nMove shared behavior into the native host package or document the change as manual guidance.`);
+  }
+}
+
+function readGitFile(repositoryRoot, commit, relativeTemplatePath) {
+  const result = childProcess.spawnSync('git', ['show', `${commit}:${TEMPLATE_PATH}/${relativeTemplatePath}`], { cwd: repositoryRoot, encoding: null });
+  if (result.error) throw result.error;
+  return result.status === 0 ? result.stdout : null;
+}
+
+function fileMode(repositoryRoot, commit, relativePath) {
+  if (commit) {
+    const output = git(repositoryRoot, ['ls-tree', commit, `${TEMPLATE_PATH}/${relativePath}`], true);
+    return output?.trim().split(/\s+/)[0] || null;
+  }
+  const absolutePath = path.join(repositoryRoot, TEMPLATE_PATH, relativePath);
+  return fs.existsSync(absolutePath) ? (fs.statSync(absolutePath).mode & 0o777).toString(8).padStart(6, '0') : null;
+}
+
+async function runAuthoringCommand(command, startPath, options) {
+  const repositoryRoot = findRepositoryRoot(startPath);
+  if (command === 'change') return createMigrationChange(repositoryRoot, options);
+  if (command === 'check') return checkMigrationChanges(repositoryRoot, options);
+  return withAuthoringLock(repositoryRoot, () => {
+    recoverAuthoringJournal(repositoryRoot);
+    return buildMigrationStep(repositoryRoot, options);
+  });
+}
+
+async function withAuthoringLock(repositoryRoot, action) {
+  const lockPath = path.join(repositoryRoot, AUTHORING_LOCK_PATH);
+  const compatibilityDirectory = path.dirname(lockPath);
+  fs.mkdirSync(compatibilityDirectory, { recursive: true });
+  try {
+    return await withLock({ fileToLock: lockPath, stale: 30000, retries: 0 }, action);
+  } catch (error) {
+    if (/already being held/i.test(error.message)) throw new Error('Another migration build is running');
+    throw error;
+  } finally {
+    fs.rmSync(lockPath, { force: true });
+  }
+}
+
+function recoverAuthoringJournal(repositoryRoot) {
+  const journalPath = path.join(repositoryRoot, AUTHORING_JOURNAL_PATH);
+  if (!fs.existsSync(journalPath)) return;
+  const journal = readJson(journalPath);
+  validateAuthoringJournal(repositoryRoot, journal);
+  if (journal.status !== 'committed') {
+    writeFileAtomic.sync(journal.profilePath, Buffer.from(journal.originalProfile, 'base64'));
+    for (const outputPath of journal.outputPaths) fs.rmSync(outputPath, { force: true });
+    for (const record of journal.records) {
+      fs.mkdirSync(path.dirname(record.path), { recursive: true });
+      writeFileAtomic.sync(record.path, Buffer.from(record.content, 'base64'));
+    }
+    console.warn('[upgrade-template] Recovered an interrupted migration build.');
+  }
+  fs.rmSync(journalPath, { force: true });
+}
+
+function validateAuthoringJournal(repositoryRoot, journal) {
+  if (journal.schemaVersion !== 1 || !['preparing', 'committed'].includes(journal.status)) throw new Error('Migration build journal has an unsupported schema');
+  const profilePath = path.join(repositoryRoot, 'packages/power-apps-native-host/compatibility/current.json');
+  const migrationDirectory = path.join(repositoryRoot, 'packages/power-apps-native-host/compatibility/migrations');
+  const changeDirectory = path.join(repositoryRoot, MIGRATION_CHANGE_PATH);
+  if (path.resolve(journal.profilePath || '') !== profilePath || !isCanonicalBase64(journal.originalProfile)) throw new Error('Migration build journal has invalid profile backup data');
+  if (!Array.isArray(journal.outputPaths) || !Array.isArray(journal.records)) throw new Error('Migration build journal has invalid file entries');
+  const outputPaths = new Set();
+  for (const outputPath of journal.outputPaths) {
+    if (!isPathWithin(migrationDirectory, outputPath) || !/\.(?:json|patch)$/.test(outputPath) || outputPaths.has(path.resolve(outputPath))) {
+      throw new Error('Migration build journal has an unsafe output path');
+    }
+    assertSafeFilePath(repositoryRoot, path.resolve(outputPath));
+    outputPaths.add(path.resolve(outputPath));
+  }
+  const recordPaths = new Set();
+  for (const record of journal.records) {
+    if (!record || !isPathWithin(changeDirectory, record.path) || !record.path.endsWith('.json') || !isCanonicalBase64(record.content) || recordPaths.has(path.resolve(record.path))) {
+      throw new Error('Migration build journal has invalid changelog backup data');
+    }
+    assertSafeFilePath(repositoryRoot, path.resolve(record.path));
+    recordPaths.add(path.resolve(record.path));
+  }
+}
+
+function isPathWithin(directory, filePath) {
+  if (typeof filePath !== 'string') return false;
+  const root = path.resolve(directory);
+  const target = path.resolve(filePath);
+  return target.startsWith(`${root}${path.sep}`);
+}
+
+function isCanonicalBase64(value) {
+  return typeof value === 'string' && value.length % 4 === 0 && /^[A-Za-z0-9+/]*={0,2}$/.test(value) && Buffer.from(value, 'base64').toString('base64') === value;
+}
+
+function updateProfileFromTemplate(profile, repositoryRoot) {
+  const templatePackage = readJson(path.join(repositoryRoot, TEMPLATE_PATH, 'package.json'));
+  const dependencies = { ...templatePackage.dependencies };
+  profile.expoVersion = dependencies.expo;
+  delete dependencies.expo;
+  delete dependencies[HOST_PACKAGE];
+  profile.managedDependencies = dependencies;
+  profile.managedDevDependencies = { ...templatePackage.devDependencies };
+  profile.managedOverrides = { ...templatePackage.overrides };
+}
+
+function packageTransitions(baseValues = {}, targetValues = {}) {
+  const names = [...new Set([...Object.keys(baseValues), ...Object.keys(targetValues)])].sort();
+  return Object.fromEntries(names
+    .filter(name => JSON.stringify(baseValues[name]) !== JSON.stringify(targetValues[name]))
+    .map(name => [name, {
+      from: baseValues[name] ?? null,
+      to: targetValues[name] ?? null,
+    }]));
+}
+
+function tsconfigWithoutManagedPaths(tsconfig) {
+  const clone = JSON.parse(JSON.stringify(tsconfig || {}));
+  if (clone.compilerOptions?.paths) {
+    delete clone.compilerOptions.paths;
+    if (Object.keys(clone.compilerOptions).length === 0) delete clone.compilerOptions;
+  }
+  return clone;
+}
+
+function buildTsconfigTransitions(relativePath, baseContent, targetContent) {
+  const base = baseContent ? JSON.parse(baseContent.toString('utf8')) : {};
+  const target = targetContent ? JSON.parse(targetContent.toString('utf8')) : {};
+  if (JSON.stringify(tsconfigWithoutManagedPaths(base)) !== JSON.stringify(tsconfigWithoutManagedPaths(target))) {
+    throw new Error(`Template change ${relativePath} modifies unsupported tsconfig fields; add a structured upgrade handler before building this migration`);
+  }
+  const paths = packageTransitions(base.compilerOptions?.paths, target.compilerOptions?.paths);
+  return Object.keys(paths).length ? { paths } : null;
+}
+
+function assertPatchableMode(relativePath, mode) {
+  if (mode && !['100644', '100755', '000644', '000755'].includes(mode)) {
+    throw new Error(`Template file mode ${mode} for ${relativePath} is not supported`);
+  }
+}
+
+function buildMigrationStep(repositoryRoot, options) {
+  if (!options.id) throw new Error('build requires --id');
+  if (!/^[a-z0-9][a-z0-9._-]*$/i.test(options.id)) throw new Error('--id may contain only letters, numbers, dots, underscores, and hyphens');
+  const records = readMigrationChanges(repositoryRoot);
+  if (!records.length) throw new Error('No pending migration changelogs were found');
+  const baseTags = [...new Set(records.map(record => record.baseTag))];
+  const baseCommits = [...new Set(records.map(record => record.baseCommit))];
+  if (baseTags.length !== 1 || baseCommits.length !== 1 || !baseTags[0]) throw new Error('All pending migration changelogs must use the same version tag');
+  checkMigrationChanges(repositoryRoot, { fromTag: baseTags[0] });
+
+  const paths = [...new Set(records.flatMap(record => (record.files || []).map(file => file.path)))].sort();
+  const patches = [];
+  const patchFiles = {};
+  let tsconfigTransitions = null;
+  for (const relativePath of paths) {
+    const baseContent = readGitFile(repositoryRoot, baseCommits[0], relativePath);
+    const targetPath = path.join(repositoryRoot, TEMPLATE_PATH, relativePath);
+    if (fs.existsSync(targetPath) && fs.lstatSync(targetPath).isSymbolicLink()) {
+      throw new Error(`Symbolic link template change ${relativePath} is not supported`);
+    }
+    const targetContent = fs.existsSync(targetPath) ? fs.readFileSync(targetPath) : null;
+    assertCustomerSectionUnchanged(relativePath, baseContent, targetContent);
+    if (relativePath === TSCONFIG_PATH) {
+      tsconfigTransitions = buildTsconfigTransitions(relativePath, baseContent, targetContent);
+      continue;
+    }
+    if ([TEMPLATE_VERSION_PATH, 'package.json', 'package-lock.json'].includes(relativePath)) continue;
+    if (!isPatchableText(baseContent) || !isPatchableText(targetContent)) {
+      throw new Error(`Binary template change ${relativePath} cannot be represented by a unified migration patch`);
+    }
+    const fromMode = fileMode(repositoryRoot, baseCommits[0], relativePath);
+    const toMode = fileMode(repositoryRoot, null, relativePath);
+    assertPatchableMode(relativePath, fromMode);
+    assertPatchableMode(relativePath, toMode);
+    patchFiles[relativePath] = {
+      fromHash: hashContent(baseContent),
+      toHash: hashContent(targetContent),
+      fromMode,
+      toMode,
+    };
+    patches.push(createTwoFilesPatch(
+      baseContent === null ? '/dev/null' : relativePath,
+      targetContent === null ? '/dev/null' : relativePath,
+      baseContent?.toString('utf8') || '',
+      targetContent?.toString('utf8') || '',
+      baseTags[0],
+      options.id,
+      { context: 3 },
+    ));
+  }
+
+  const baseStateContent = readGitFile(repositoryRoot, baseCommits[0], TEMPLATE_VERSION_PATH);
+  if (!baseStateContent && !options.fromVersion) {
+    throw new Error(`Version tag ${baseTags[0]} does not contain ${TEMPLATE_VERSION_PATH}; rerun build with --from-version <version>`);
+  }
+  const baseState = baseStateContent
+    ? JSON.parse(baseStateContent.toString('utf8'))
+    : { schemaVersion: 1, templateVersion: options.fromVersion };
+  const targetState = readJson(path.join(repositoryRoot, TEMPLATE_PATH, TEMPLATE_VERSION_PATH));
+  if (targetState.templateVersion !== baseState.templateVersion + 1) {
+    throw new Error(`Migration must advance exactly one template version (${baseState.templateVersion} -> ${baseState.templateVersion + 1})`);
+  }
+
+  const basePackageContent = readGitFile(repositoryRoot, baseCommits[0], 'package.json');
+  if (!basePackageContent) throw new Error(`Version tag ${baseTags[0]} does not contain template package.json`);
+  const basePackage = JSON.parse(basePackageContent.toString('utf8'));
+  const targetPackage = readJson(path.join(repositoryRoot, TEMPLATE_PATH, 'package.json'));
+  const profilePath = path.join(repositoryRoot, 'packages/power-apps-native-host/compatibility/current.json');
+  const profile = readJson(profilePath);
+  if (profile.targetTemplateVersion !== undefined && profile.targetTemplateVersion !== baseState.templateVersion) {
+    throw new Error(`Current profile targets template ${profile.targetTemplateVersion}, but migration starts at ${baseState.templateVersion}`);
+  }
+  updateProfileFromTemplate(profile, repositoryRoot);
+  profile.targetTemplateVersion = targetState.templateVersion;
+  const step = {
+    schemaVersion: 1,
+    id: options.id,
+    fromTag: baseTags[0],
+    fromCommit: baseCommits[0],
+    fromTemplateVersion: baseState.templateVersion,
+    toTemplateVersion: targetState.templateVersion,
+    comments: records.map(record => record.comment),
+    patchFile: `${options.id}.patch`,
+    patchFiles,
+    packageTransitions: {
+      dependencies: Object.fromEntries(Object.entries(packageTransitions(basePackage.dependencies, targetPackage.dependencies))
+        .filter(([name]) => name !== HOST_PACKAGE && name !== 'expo')),
+      devDependencies: packageTransitions(basePackage.devDependencies, targetPackage.devDependencies),
+      overrides: packageTransitions(basePackage.overrides, targetPackage.overrides),
+    },
+    ...(tsconfigTransitions ? { tsconfigTransitions } : {}),
+    targetProfile: {
+      id: profile.id,
+      hostVersion: readJson(path.join(repositoryRoot, 'packages/power-apps-native-host/package.json')).version,
+      expoSdk: profile.expoSdk,
+      expoVersion: profile.expoVersion,
+      expoDoctorVersion: profile.expoDoctorVersion,
+      managedDependencies: profile.managedDependencies,
+      managedDevDependencies: profile.managedDevDependencies,
+      managedOverrides: profile.managedOverrides,
+    },
+  };
+  if (!step.targetProfile.expoDoctorVersion) throw new Error('Current compatibility profile must define expoDoctorVersion');
+  profile.migrations ||= [];
+  const existingEdges = profile.migrations.map(migrationId => {
+    const metadataPath = path.join(repositoryRoot, `packages/power-apps-native-host/compatibility/migrations/${migrationId}.json`);
+    if (!fs.existsSync(metadataPath)) throw new Error(`Existing migration metadata is missing: ${migrationId}`);
+    return readJson(metadataPath);
+  });
+  validateMigrationEdges([...existingEdges, step], targetState.templateVersion);
+  if (!profile.migrations.includes(options.id)) profile.migrations.push(options.id);
+
+  const migrationDirectory = path.join(repositoryRoot, 'packages/power-apps-native-host/compatibility/migrations');
+  const migrationPath = path.join(migrationDirectory, `${options.id}.json`);
+  const patchPath = path.join(migrationDirectory, step.patchFile);
+  if (fs.existsSync(migrationPath) || fs.existsSync(patchPath)) throw new Error(`Migration ${options.id} already exists`);
+  console.log(`${options.dryRun ? '[dry-run] ' : ''}Build migration ${options.id} from ${records.length} changelog(s)`);
+  if (!options.dryRun) {
+    fs.mkdirSync(migrationDirectory, { recursive: true });
+    const temporarySuffix = `.tmp-${process.pid}-${Date.now()}`;
+    const temporaryMigrationPath = `${migrationPath}${temporarySuffix}`;
+    const temporaryPatchPath = `${patchPath}${temporarySuffix}`;
+    const temporaryProfilePath = `${profilePath}${temporarySuffix}`;
+    const originalProfile = fs.readFileSync(profilePath);
+    const recordContents = new Map(records.map(record => {
+      const recordPath = path.join(repositoryRoot, MIGRATION_CHANGE_PATH, record.name);
+      return [recordPath, fs.readFileSync(recordPath)];
+    }));
+    const journalPath = path.join(repositoryRoot, AUTHORING_JOURNAL_PATH);
+    const journal = {
+      schemaVersion: 1,
+      status: 'preparing',
+      profilePath,
+      originalProfile: originalProfile.toString('base64'),
+      outputPaths: [migrationPath, patchPath],
+      records: [...recordContents].map(([recordPath, content]) => ({
+        path: recordPath,
+        content: content.toString('base64'),
+      })),
+    };
+    writeFileAtomic.sync(journalPath, `${JSON.stringify(journal, null, 2)}\n`, { mode: 0o600 });
+    try {
+      fs.writeFileSync(temporaryMigrationPath, `${JSON.stringify(step, null, 2)}\n`);
+      fs.writeFileSync(temporaryPatchPath, patches.join('\n'), 'utf8');
+      fs.writeFileSync(temporaryProfilePath, `${JSON.stringify(profile, null, 2)}\n`);
+      readJson(temporaryMigrationPath);
+      readJson(temporaryProfilePath);
+      parsePatch(fs.readFileSync(temporaryPatchPath, 'utf8'));
+      fs.renameSync(temporaryPatchPath, patchPath);
+      fs.renameSync(temporaryMigrationPath, migrationPath);
+      fs.renameSync(temporaryProfilePath, profilePath);
+      for (const recordPath of recordContents.keys()) fs.unlinkSync(recordPath);
+      journal.status = 'committed';
+      writeFileAtomic.sync(journalPath, `${JSON.stringify(journal, null, 2)}\n`, { mode: 0o600 });
+      fs.rmSync(journalPath, { force: true });
+    } catch (error) {
+      fs.writeFileSync(profilePath, originalProfile);
+      fs.rmSync(migrationPath, { force: true });
+      fs.rmSync(patchPath, { force: true });
+      for (const temporaryPath of [temporaryMigrationPath, temporaryPatchPath, temporaryProfilePath]) {
+        fs.rmSync(temporaryPath, { force: true });
+      }
+      for (const [recordPath, content] of recordContents) {
+        fs.mkdirSync(path.dirname(recordPath), { recursive: true });
+        fs.writeFileSync(recordPath, content);
+      }
+      fs.rmSync(journalPath, { force: true });
+      throw error;
+    }
+  }
+  return step;
+}
+
+function assertCustomerSectionUnchanged(relativePath, baseContent, targetContent) {
+  for (const section of CUSTOMER_SECTIONS) {
+    const baseSection = readCustomerSection(relativePath, baseContent, section);
+    if (baseSection === null) continue;
+    const targetSection = readCustomerSection(relativePath, targetContent, section);
+    if (targetSection !== baseSection) {
+      throw new Error(`Template change modifies the ${section.name} section in ${relativePath}`);
+    }
+  }
+}
+
+function readCustomerSection(relativePath, content, section) {
+  if (content === null) return null;
+  const source = content.toString('utf8');
+  const start = source.indexOf(section.start);
+  const end = source.indexOf(section.end);
+  if (start === -1 && end === -1) return null;
+  if (start === -1 || end < start || source.indexOf(section.start, start + 1) !== -1 || source.indexOf(section.end, end + 1) !== -1) {
+    throw new Error(`Template file ${relativePath} has invalid ${section.name} markers`);
+  }
+  return source.slice(start, end + section.end.length);
+}
+
+function isPatchableText(content) {
+  if (content === null) return true;
+  try {
+    new TextDecoder('utf-8', { fatal: true }).decode(content);
+  } catch {
+    return false;
+  }
+  let controlCharacters = 0;
+  for (const byte of content) {
+    if (byte < 32 && byte !== 9 && byte !== 10 && byte !== 13) controlCharacters += 1;
+  }
+  return controlCharacters === 0;
+}
+
+function validateMigrationEdges(migrations, targetVersion) {
+  const fromVersions = new Set();
+  for (const migration of migrations) {
+    if (!Number.isInteger(migration.fromTemplateVersion) || migration.fromTemplateVersion < 1) {
+      throw new Error(`Migration ${migration.id} has an invalid source template version`);
+    }
+    if (migration.toTemplateVersion !== migration.fromTemplateVersion + 1) {
+      throw new Error(`Migration ${migration.id} is not an adjacent template edge`);
+    }
+    if (fromVersions.has(migration.fromTemplateVersion)) {
+      throw new Error(`Multiple migrations start at template version ${migration.fromTemplateVersion}`);
+    }
+    fromVersions.add(migration.fromTemplateVersion);
+  }
+  if (migrations.length) {
+    const firstVersion = Math.min(...fromVersions);
+    for (let version = firstVersion; version < targetVersion; version += 1) {
+      if (!fromVersions.has(version)) throw new Error(`Migration graph is missing template version ${version} -> ${version + 1}`);
+    }
+    if (Math.max(...migrations.map(migration => migration.toTemplateVersion)) !== targetVersion) {
+      throw new Error(`Migration graph does not reach target template version ${targetVersion}`);
+    }
+  }
+}
+
+module.exports = { getTemplateChanges, runAuthoringCommand };