@microsoft/power-apps-native-host 0.3.0 → 0.3.3

package/scripts/upgrade-authoring.js

@@ -1,19 +1,27 @@
 '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 { HOST_PACKAGE, TEMPLATE_VERSION_PATH, assertSafeFilePath, hashContent, isCustomerOwnedPath, 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 GITIGNORE_PATH = '.gitignore';
+const GITIGNORE_START = '# POWER APPS MANAGED START - DO NOT REMOVE OR RENAME THE COMMENT';
+const GITIGNORE_END = '# POWER APPS MANAGED END - DO NOT REMOVE OR RENAME THE COMMENT';
+const MANAGED_PACKAGE_FIELDS = ['main'];
+const PROFILE_PATH = 'packages/power-apps-native-host/compatibility/current.json';
+const TEMPLATE_BASELINE_TAG_PREFIX = 'standalone-template-migration-baseline-v';
+const LEGACY_TEMPLATE_BASELINE_TAG_PATTERN = /^template-migration-baseline-v\d+$/;
+const RELEASE_HOST_VERSION = '__RELEASE_HOST_VERSION__';
+const NATIVE_RUNTIME_FINGERPRINT_SCRIPT = 'scripts/repository/native-runtime-fingerprint.js';
+const NATIVE_RUNTIME_PLATFORMS = ['android', 'ios'];
 const CUSTOMER_SECTIONS = [
   {
     name: 'customer app settings',
@@ -43,7 +51,7 @@ function git(repositoryRoot, args, allowFailure = false) {
 }
 
 function resolveVersionTag(repositoryRoot, tag) {
-  if (!tag) throw new Error('change/check requires --from-tag <version-tag> or MIGRATION_BASE_TAG');
+  if (!tag) throw new Error('build requires --from-tag <version-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`);
@@ -55,6 +63,26 @@ function resolveVersionTag(repositoryRoot, tag) {
   return { tag, commit };
 }
 
+function templateBaselineTag(templateVersion) {
+  return `${TEMPLATE_BASELINE_TAG_PREFIX}${templateVersion}`;
+}
+
+function inferBuildBaseTag(repositoryRoot) {
+  const profile = readJson(path.join(repositoryRoot, PROFILE_PATH));
+  if (!Number.isInteger(profile.targetTemplateVersion)) throw new Error('Current compatibility profile has an invalid targetTemplateVersion');
+  const currentTag = templateBaselineTag(profile.targetTemplateVersion);
+  if (git(repositoryRoot, ['show-ref', '--verify', '--quiet', `refs/tags/${currentTag}`], true) !== null) return currentTag;
+  const legacyTags = git(repositoryRoot, ['tag', '--merged', 'HEAD', '--list', 'template-migration-baseline-v*', '--sort=-version:refname'])
+    .trim().split('\n').filter(Boolean);
+  const legacyTag = legacyTags.find(tag => {
+    if (!LEGACY_TEMPLATE_BASELINE_TAG_PATTERN.test(tag)) return false;
+    const base = resolveVersionTag(repositoryRoot, tag);
+    return readTemplateState(repositoryRoot, base.commit)?.templateVersion === profile.targetTemplateVersion;
+  });
+  if (legacyTag) return legacyTag;
+  throw new Error(`Could not infer template migration baseline. Expected ${currentTag}.`);
+}
+
 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])
@@ -65,93 +93,12 @@ function getTemplateChanges(repositoryRoot, fromTag) {
   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) };
+      return { path: filePath.slice(`${TEMPLATE_PATH}/`.length) };
     }),
   };
 }
 
-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) {
@@ -176,10 +123,9 @@ function fileMode(repositoryRoot, commit, relativePath) {
 
 async function runAuthoringCommand(command, startPath, options) {
   const repositoryRoot = findRepositoryRoot(startPath);
-  if (command === 'change') return createMigrationChange(repositoryRoot, options);
-  if (command === 'check') return checkMigrationChanges(repositoryRoot, options);
+  if (command !== 'build') throw new Error(`Unsupported template authoring command: ${command}`);
   return withAuthoringLock(repositoryRoot, () => {
-    recoverAuthoringJournal(repositoryRoot);
+    if (recoverAuthoringJournal(repositoryRoot) === 'committed') return null;
     return buildMigrationStep(repositoryRoot, options);
   });
 }
@@ -200,28 +146,40 @@ async function withAuthoringLock(repositoryRoot, action) {
 
 function recoverAuthoringJournal(repositoryRoot) {
   const journalPath = path.join(repositoryRoot, AUTHORING_JOURNAL_PATH);
-  if (!fs.existsSync(journalPath)) return;
+  if (!fs.existsSync(journalPath)) return null;
   const journal = readJson(journalPath);
   validateAuthoringJournal(repositoryRoot, journal);
   if (journal.status !== 'committed') {
     writeFileAtomic.sync(journal.profilePath, Buffer.from(journal.originalProfile, 'base64'));
+    if (journal.appJsonPath && journal.originalAppJson) writeFileAtomic.sync(journal.appJsonPath, Buffer.from(journal.originalAppJson, '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.');
   }
+  for (const filePath of [journal.profilePath, journal.appJsonPath, ...journal.outputPaths].filter(Boolean)) {
+    removeTemporarySiblings(filePath);
+  }
   fs.rmSync(journalPath, { force: true });
+  return journal.status;
+}
+
+function removeTemporarySiblings(filePath) {
+  const directory = path.dirname(filePath);
+  const temporaryPrefix = `${path.basename(filePath)}.tmp-`;
+  for (const name of fs.readdirSync(directory)) {
+    if (name.startsWith(temporaryPrefix)) fs.rmSync(path.join(directory, name), { 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 appJsonPath = path.join(repositoryRoot, TEMPLATE_PATH, TEMPLATE_VERSION_PATH);
   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');
+  if (journal.appJsonPath !== undefined || journal.originalAppJson !== undefined) {
+    if (path.resolve(journal.appJsonPath || '') !== appJsonPath || !isCanonicalBase64(journal.originalAppJson)) throw new Error('Migration build journal has invalid app.json backup data');
+  }
+  if (!Array.isArray(journal.outputPaths)) 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))) {
@@ -230,14 +188,6 @@ function validateAuthoringJournal(repositoryRoot, journal) {
     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) {
@@ -253,13 +203,76 @@ function isCanonicalBase64(value) {
 
 function updateProfileFromTemplate(profile, repositoryRoot) {
   const templatePackage = readJson(path.join(repositoryRoot, TEMPLATE_PATH, 'package.json'));
+  validateDevPlayerDependencies(repositoryRoot, templatePackage);
+  updateProfileFromPackage(profile, templatePackage);
+}
+
+function nextNativeRuntime(current, fingerprint) {
+  return {
+    version: current.version + (fingerprint === current.fingerprint ? 0 : 1),
+    fingerprint,
+  };
+}
+
+function updateNativeRuntime(profile, repositoryRoot) {
+  const previous = JSON.parse(JSON.stringify(profile.nativeRuntime));
+  for (const platform of NATIVE_RUNTIME_PLATFORMS) {
+    const current = profile.nativeRuntime[platform];
+    if (!Number.isInteger(current?.version) || current.version < 1 || !/^[a-f0-9]{64}$/.test(current.fingerprint || '')) {
+      throw new Error(`Current compatibility profile has invalid nativeRuntime.${platform}`);
+    }
+    const result = childProcess.spawnSync(
+      process.execPath,
+      [path.join(repositoryRoot, NATIVE_RUNTIME_FINGERPRINT_SCRIPT), platform, path.join(repositoryRoot, TEMPLATE_PATH)],
+      { cwd: repositoryRoot, encoding: 'utf8' },
+    );
+    if (result.error) throw result.error;
+    if (result.status !== 0) {
+      throw new Error(`Could not fingerprint the ${platform} native runtime: ${String(result.stderr || '').trim()}`);
+    }
+    const fingerprint = String(result.stdout || '').trim();
+    if (!/^[a-f0-9]{64}$/.test(fingerprint)) throw new Error(`Invalid ${platform} native runtime fingerprint`);
+    profile.nativeRuntime[platform] = nextNativeRuntime(current, fingerprint);
+  }
+  return previous;
+}
+
+function updateProfileFromPackage(profile, templatePackage) {
   const dependencies = { ...templatePackage.dependencies };
-  profile.expoVersion = dependencies.expo;
+  const expoVersion = dependencies.expo;
+  const expoMajorMatch = typeof expoVersion === 'string' && expoVersion.match(/^(?:[~^])?(\d+)\./);
+  if (!expoMajorMatch) throw new Error('Standalone template package.json must define a supported Expo version');
+  profile.expoSdk = Number(expoMajorMatch[1]);
+  profile.expoVersion = expoVersion;
   delete dependencies.expo;
   delete dependencies[HOST_PACKAGE];
   profile.managedDependencies = dependencies;
   profile.managedDevDependencies = { ...templatePackage.devDependencies };
   profile.managedOverrides = { ...templatePackage.overrides };
+  profile.managedScripts = { ...templatePackage.scripts };
+  profile.managedFields = Object.fromEntries(MANAGED_PACKAGE_FIELDS
+    .filter(name => templatePackage[name] !== undefined)
+    .map(name => [name, templatePackage[name]]));
+}
+
+function validateDevPlayerDependencies(repositoryRoot, templatePackage) {
+  const devPlayerPackagePath = path.join(repositoryRoot, 'apps/dev-player/package.json');
+  if (!fs.existsSync(devPlayerPackagePath)) {
+    throw new Error('Dev Player package.json is missing; cannot validate standalone template dependencies');
+  }
+
+  const devPlayerPackage = readJson(devPlayerPackagePath);
+  const missingDependencies = Object.keys(templatePackage.dependencies || {})
+    .filter(name => !Object.hasOwn(devPlayerPackage.dependencies || {}, name));
+  const missingDevDependencies = Object.keys(templatePackage.devDependencies || {})
+    .filter(name => !Object.hasOwn(devPlayerPackage.devDependencies || {}, name));
+  const missing = [
+    ...missingDependencies.map(name => `dependencies.${name}`),
+    ...missingDevDependencies.map(name => `devDependencies.${name}`),
+  ].sort();
+  if (missing.length > 0) {
+    throw new Error(`Dev Player package.json is missing standalone template dependencies: ${missing.join(', ')}`);
+  }
 }
 
 function packageTransitions(baseValues = {}, targetValues = {}) {
@@ -272,23 +285,48 @@ function packageTransitions(baseValues = {}, targetValues = {}) {
     }]));
 }
 
-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 buildPackageTransitions(basePackage, targetPackage) {
+  return {
+    fields: packageTransitions(
+      Object.fromEntries(MANAGED_PACKAGE_FIELDS.filter(name => basePackage[name] !== undefined).map(name => [name, basePackage[name]])),
+      Object.fromEntries(MANAGED_PACKAGE_FIELDS.filter(name => targetPackage[name] !== undefined).map(name => [name, targetPackage[name]])),
+    ),
+    scripts: packageTransitions(basePackage.scripts, targetPackage.scripts),
+    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),
+  };
 }
 
 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 fields = packageTransitions(
+    Object.fromEntries(['extends', 'include', 'exclude'].filter(name => base[name] !== undefined).map(name => [name, base[name]])),
+    Object.fromEntries(['extends', 'include', 'exclude'].filter(name => target[name] !== undefined).map(name => [name, target[name]])),
+  );
+  const baseCompilerOptions = { ...base.compilerOptions };
+  const targetCompilerOptions = { ...target.compilerOptions };
+  delete baseCompilerOptions.paths;
+  delete targetCompilerOptions.paths;
+  const compilerOptions = packageTransitions(baseCompilerOptions, targetCompilerOptions);
   const paths = packageTransitions(base.compilerOptions?.paths, target.compilerOptions?.paths);
-  return Object.keys(paths).length ? { paths } : null;
+  const transitions = {};
+  if (Object.keys(fields).length) transitions.fields = fields;
+  if (Object.keys(compilerOptions).length) transitions.compilerOptions = compilerOptions;
+  if (Object.keys(paths).length) transitions.paths = paths;
+  return Object.keys(transitions).length ? transitions : null;
+}
+
+function readManagedGitignoreBlock(relativePath, content, required) {
+  if (content === null) return null;
+  const source = content.toString('utf8');
+  const start = source.indexOf(GITIGNORE_START);
+  const end = source.indexOf(GITIGNORE_END);
+  if (start === -1 && end === -1 && !required) return null;
+  if (start === -1 || end < start) throw new Error(`Template file ${relativePath} has invalid Power Apps managed markers`);
+  return source.slice(start + GITIGNORE_START.length, end).replace(/^\r?\n|\r?\n$/g, '');
 }
 
 function assertPatchableMode(relativePath, mode) {
@@ -297,22 +335,78 @@ function assertPatchableMode(relativePath, mode) {
   }
 }
 
+function readTemplateState(repositoryRoot, commit) {
+  const content = commit
+    ? readGitFile(repositoryRoot, commit, TEMPLATE_VERSION_PATH)
+    : fs.readFileSync(path.join(repositoryRoot, TEMPLATE_PATH, TEMPLATE_VERSION_PATH));
+  return content ? JSON.parse(content.toString('utf8')).expo?.extra?.powerappsNative : null;
+}
+
+function buildTemplateVersionContent(repositoryRoot, templateVersion, nativeRuntime) {
+  const appJsonPath = path.join(repositoryRoot, TEMPLATE_PATH, TEMPLATE_VERSION_PATH);
+  const appConfig = readJson(appJsonPath);
+  appConfig.expo ||= {};
+  appConfig.expo.extra ||= {};
+  appConfig.expo.extra.powerappsNative ||= { schemaVersion: 1 };
+  appConfig.expo.extra.powerappsNative.schemaVersion ||= 1;
+  appConfig.expo.extra.powerappsNative.templateVersion = templateVersion;
+  appConfig.expo.extra.powerappsNative.nativeRuntimeVersions = Object.fromEntries(
+    NATIVE_RUNTIME_PLATFORMS.map(platform => [platform, nativeRuntime[platform].version]),
+  );
+  return `${JSON.stringify(appConfig, null, 2)}\n`;
+}
+
 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 fromTag = options.fromTag || inferBuildBaseTag(repositoryRoot);
+  const templateChanges = getTemplateChanges(repositoryRoot, fromTag);
+  const base = { tag: templateChanges.baseTag, commit: templateChanges.baseCommit };
+  const isLegacyBootstrap = !options.fromTag && LEGACY_TEMPLATE_BASELINE_TAG_PATTERN.test(fromTag);
+  const migrationFiles = isLegacyBootstrap
+    ? templateChanges.files.filter(file => !isCustomerOwnedPath(file.path))
+    : templateChanges.files;
+  assertNoCustomerOwnedChanges(migrationFiles);
+  if (!migrationFiles.length) {
+    if (options.skipIfNoChanges) {
+      console.log(`No standalone template changes found since ${base.tag}.`);
+      return null;
+    }
+    throw new Error('No template changes were found');
+  }
+
+  const appJsonPath = path.join(repositoryRoot, TEMPLATE_PATH, TEMPLATE_VERSION_PATH);
+  const originalAppJson = fs.readFileSync(appJsonPath);
+  const baseState = readTemplateState(repositoryRoot, base.commit);
+  if (!Number.isInteger(baseState?.templateVersion)) {
+    throw new Error(`Version tag ${base.tag} does not contain ${TEMPLATE_VERSION_PATH} expo.extra.powerappsNative.templateVersion`);
+  }
+  const currentState = readTemplateState(repositoryRoot, null);
+  if (currentState?.templateVersion !== baseState.templateVersion) {
+    throw new Error(`Template version must not be advanced before release build (${TEMPLATE_VERSION_PATH} is ${currentState?.templateVersion ?? 'missing'}, expected ${baseState.templateVersion})`);
+  }
+  if (migrationFiles.some(file => file.path === TEMPLATE_VERSION_PATH)) {
+    throw new Error(`${TEMPLATE_VERSION_PATH} changes are limited to the release-owned templateVersion bump; add a structured migration handler before changing other fields`);
+  }
+  const expectedTargetVersion = baseState.templateVersion + 1;
+  const migrationId = options.id || `template-v${expectedTargetVersion}`;
+  const migrationMessage = options.message || `Release standalone template v${expectedTargetVersion}`;
+  if (!/^[a-z0-9][a-z0-9._-]*$/i.test(migrationId)) throw new Error('--id may contain only letters, numbers, dots, underscores, and hyphens');
+  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}`);
+  }
+  const previousNativeRuntime = updateNativeRuntime(profile, repositoryRoot);
+  updateProfileFromTemplate(profile, repositoryRoot);
+  profile.targetTemplateVersion = expectedTargetVersion;
+  const targetAppJson = buildTemplateVersionContent(repositoryRoot, expectedTargetVersion, profile.nativeRuntime);
+
+  const paths = migrationFiles.map(file => file.path).sort();
   const patches = [];
   const patchFiles = {};
   let tsconfigTransitions = null;
+  let gitignoreTransition = null;
   for (const relativePath of paths) {
-    const baseContent = readGitFile(repositoryRoot, baseCommits[0], relativePath);
+    const baseContent = readGitFile(repositoryRoot, base.commit, 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`);
@@ -323,11 +417,18 @@ function buildMigrationStep(repositoryRoot, options) {
       tsconfigTransitions = buildTsconfigTransitions(relativePath, baseContent, targetContent);
       continue;
     }
+    if (relativePath === GITIGNORE_PATH) {
+      gitignoreTransition = {
+        from: readManagedGitignoreBlock(relativePath, baseContent, false),
+        to: readManagedGitignoreBlock(relativePath, targetContent, true),
+      };
+      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 fromMode = fileMode(repositoryRoot, base.commit, relativePath);
     const toMode = fileMode(repositoryRoot, null, relativePath);
     assertPatchableMode(relativePath, fromMode);
     assertPatchableMode(relativePath, toMode);
@@ -342,60 +443,48 @@ function buildMigrationStep(repositoryRoot, options) {
       targetContent === null ? '/dev/null' : relativePath,
       baseContent?.toString('utf8') || '',
       targetContent?.toString('utf8') || '',
-      baseTags[0],
-      options.id,
+      base.tag,
+      migrationId,
       { context: 3 },
     ));
   }
 
-  const baseStateContent = readGitFile(repositoryRoot, baseCommits[0], TEMPLATE_VERSION_PATH);
-  const recordedBaseState = baseStateContent ? JSON.parse(baseStateContent.toString('utf8')).expo?.extra?.powerappsNative : null;
-  if (!recordedBaseState && !options.fromVersion) {
-    throw new Error(`Version tag ${baseTags[0]} does not contain ${TEMPLATE_VERSION_PATH} expo.extra.powerappsNative; rerun build with --from-version <version>`);
-  }
-  const baseState = recordedBaseState || { schemaVersion: 1, templateVersion: options.fromVersion };
-  const targetState = readJson(path.join(repositoryRoot, TEMPLATE_PATH, TEMPLATE_VERSION_PATH)).expo?.extra?.powerappsNative;
-  if (targetState.templateVersion !== baseState.templateVersion + 1) {
-    throw new Error(`Migration must advance exactly one template version (${baseState.templateVersion} -> ${baseState.templateVersion + 1})`);
-  }
+  const targetState = JSON.parse(targetAppJson).expo?.extra?.powerappsNative;
+  if (targetState.templateVersion !== expectedTargetVersion) throw new Error(`Migration must advance exactly one template version (${baseState.templateVersion} -> ${expectedTargetVersion})`);
 
-  const basePackageContent = readGitFile(repositoryRoot, baseCommits[0], 'package.json');
-  if (!basePackageContent) throw new Error(`Version tag ${baseTags[0]} does not contain template package.json`);
+  const basePackageContent = readGitFile(repositoryRoot, base.commit, 'package.json');
+  if (!basePackageContent) throw new Error(`Version tag ${base.tag} 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],
+    id: migrationId,
+    fromTag: base.tag,
+    fromCommit: base.commit,
     fromTemplateVersion: baseState.templateVersion,
     toTemplateVersion: targetState.templateVersion,
-    comments: records.map(record => record.comment),
-    patchFile: `${options.id}.patch`,
+    comments: [migrationMessage],
+    patchFile: `${migrationId}.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),
+    packageTransitions: buildPackageTransitions(basePackage, targetPackage),
+    nativeRuntimeTransition: {
+      from: previousNativeRuntime,
+      to: profile.nativeRuntime,
     },
     ...(tsconfigTransitions ? { tsconfigTransitions } : {}),
+    ...(gitignoreTransition ? { gitignoreTransition } : {}),
     targetProfile: {
       id: profile.id,
-      hostVersion: readJson(path.join(repositoryRoot, 'packages/power-apps-native-host/package.json')).version,
+      hostVersion: RELEASE_HOST_VERSION,
       expoSdk: profile.expoSdk,
       expoVersion: profile.expoVersion,
       expoDoctorVersion: profile.expoDoctorVersion,
       managedDependencies: profile.managedDependencies,
       managedDevDependencies: profile.managedDevDependencies,
       managedOverrides: profile.managedOverrides,
+      managedScripts: profile.managedScripts,
+      managedFields: profile.managedFields,
+      nativeRuntime: profile.nativeRuntime,
     },
   };
   if (!step.targetProfile.expoDoctorVersion) throw new Error('Current compatibility profile must define expoDoctorVersion');
@@ -406,62 +495,56 @@ function buildMigrationStep(repositoryRoot, options) {
     return readJson(metadataPath);
   });
   validateMigrationEdges([...existingEdges, step], targetState.templateVersion);
-  if (!profile.migrations.includes(options.id)) profile.migrations.push(options.id);
+  if (!profile.migrations.includes(migrationId)) profile.migrations.push(migrationId);
 
   const migrationDirectory = path.join(repositoryRoot, 'packages/power-apps-native-host/compatibility/migrations');
-  const migrationPath = path.join(migrationDirectory, `${options.id}.json`);
+  const migrationPath = path.join(migrationDirectory, `${migrationId}.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 (fs.existsSync(migrationPath) || fs.existsSync(patchPath)) throw new Error(`Migration ${migrationId} already exists`);
+  console.log(`${options.dryRun ? '[dry-run] ' : ''}Build migration ${migrationId} from ${base.tag}`);
   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 temporaryAppJsonPath = `${appJsonPath}${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'),
+      appJsonPath,
+      originalAppJson: originalAppJson.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`);
+      fs.writeFileSync(temporaryAppJsonPath, targetAppJson, 'utf8');
       readJson(temporaryMigrationPath);
       readJson(temporaryProfilePath);
+      readJson(temporaryAppJsonPath);
       parsePatch(fs.readFileSync(temporaryPatchPath, 'utf8'));
       fs.renameSync(temporaryPatchPath, patchPath);
       fs.renameSync(temporaryMigrationPath, migrationPath);
+      fs.renameSync(temporaryAppJsonPath, appJsonPath);
       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.writeFileSync(appJsonPath, originalAppJson);
       fs.rmSync(migrationPath, { force: true });
       fs.rmSync(patchPath, { force: true });
-      for (const temporaryPath of [temporaryMigrationPath, temporaryPatchPath, temporaryProfilePath]) {
+      for (const temporaryPath of [temporaryMigrationPath, temporaryPatchPath, temporaryProfilePath, temporaryAppJsonPath]) {
         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;
     }
@@ -522,13 +605,25 @@ function validateMigrationEdges(migrations, targetVersion) {
   }
   if (migrations.length) {
     const firstVersion = Math.min(...fromVersions);
+    if (firstVersion !== 1) throw new Error('Migration graph must start at template version 1');
     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}`);
     }
+  } else if (targetVersion > 1) {
+    throw new Error(`Migration graph does not reach target template version ${targetVersion}`);
   }
 }
 
-module.exports = { getTemplateChanges, runAuthoringCommand };
+module.exports = {
+  RELEASE_HOST_VERSION,
+  buildPackageTransitions,
+  buildTsconfigTransitions,
+  getTemplateChanges,
+  nextNativeRuntime,
+  runAuthoringCommand,
+  updateProfileFromPackage,
+  validateDevPlayerDependencies,
+};