Harden template import preflights

Match existing template sites when solution updates add framework suffixes to PAC site names.

Add a tenant-alignment preflight so PAC CLI, Azure CLI, and the Dataverse token must point to the same tenant before template import.

Copilot-Session: a9952624-0a25-4d6e-ae67-537c962a8a60

Author: priyanshu92

plugins/power-pages/scripts/diff-pages-list.js

@@ -12,13 +12,18 @@ const { diffPagesListVerbose } = require('./lib/pages-list-diff');
 // than a thrown exception so the skill can surface the problem and stop before
 // activation.
 function parseArgs(argv) {
-  const args = {};
+  const args = { expectedSiteNames: [] };
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
     if (arg === '--before') args.before = argv[++i];
     else if (arg === '--after') args.after = argv[++i];
-    else if (arg === '--expectedSiteName') args.expectedSiteName = argv[++i];
+    else if (arg === '--expectedSiteName') {
+      const value = argv[++i];
+      args.expectedSiteName = value;
+      args.expectedSiteNames.push(value);
+    }
   }
+  if (!args.expectedSiteNames.length) delete args.expectedSiteNames;
   return args;
 }
 

plugins/power-pages/scripts/lib/cli-tenant-alignment.js

@@ -0,0 +1,98 @@
+'use strict';
+
+const { execFileSync } = require('child_process');
+const { getAuthToken } = require('./validation-helpers');
+
+const GUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+function normalizeGuid(value) {
+  const text = String(value || '').trim();
+  return GUID_RE.test(text) ? text.toLowerCase() : null;
+}
+
+function parsePacTenantId(output) {
+  // PAC auth banners are label/value text and vary slightly by version, e.g.:
+  //   Tenant ID:    72f988bf-86f1-41af-91ab-2d7cd011db47
+  //   Tenant:       72f988bf-86f1-41af-91ab-2d7cd011db47
+  // Values can have extra spaces, so parse only known tenant labels and require
+  // a GUID-shaped value before trusting it.
+  const match = String(output || '').match(/^\s*(?:Tenant ID|Tenant)\s*:\s*([0-9a-f-]{36})\s*$/im);
+  return match ? normalizeGuid(match[1]) : null;
+}
+
+function decodeJwtPayload(token) {
+  const parts = String(token || '').split('.');
+  if (parts.length < 2) return null;
+  try {
+    return JSON.parse(Buffer.from(parts[1], 'base64url').toString('utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function tenantIdFromToken(token) {
+  const payload = decodeJwtPayload(token);
+  return normalizeGuid(payload && payload.tid);
+}
+
+function getPacTenantId(execFile = execFileSync) {
+  try {
+    return parsePacTenantId(execFile('pac', ['auth', 'who'], { encoding: 'utf8', timeout: 15000 }));
+  } catch {
+    return null;
+  }
+}
+
+function getAzAccountTenantId(execFile = execFileSync) {
+  try {
+    return normalizeGuid(execFile('az', ['account', 'show', '--query', 'tenantId', '-o', 'tsv'], { encoding: 'utf8', timeout: 15000 }));
+  } catch {
+    return null;
+  }
+}
+
+function validateCliTenantAlignment({ envUrl, token, pacTenantId, azTenantId, tokenTenantId } = {}, deps = {}) {
+  const execFile = deps.execFile || execFileSync;
+  const getToken = deps.getAuthToken || getAuthToken;
+  const pacTenant = normalizeGuid(pacTenantId) || getPacTenantId(execFile);
+  const azTenant = normalizeGuid(azTenantId) || getAzAccountTenantId(execFile);
+  const bearerToken = token || (envUrl ? getToken(envUrl) : null);
+  const tokenTenant = normalizeGuid(tokenTenantId) || tenantIdFromToken(bearerToken);
+
+  const missing = [];
+  if (!pacTenant) missing.push('pacTenantId');
+  if (!azTenant) missing.push('azTenantId');
+  if (!tokenTenant) missing.push('tokenTenantId');
+  if (missing.length) {
+    return {
+      ok: false,
+      error: `Could not determine ${missing.join(', ')}. Run pac auth who and az login, then retry.`,
+      pacTenantId: pacTenant,
+      azTenantId: azTenant,
+      tokenTenantId: tokenTenant,
+    };
+  }
+
+  const mismatches = [];
+  if (pacTenant !== azTenant) mismatches.push('pac-vs-az');
+  if (pacTenant !== tokenTenant) mismatches.push('pac-vs-token');
+  if (azTenant !== tokenTenant) mismatches.push('az-vs-token');
+
+  return {
+    ok: mismatches.length === 0,
+    pacTenantId: pacTenant,
+    azTenantId: azTenant,
+    tokenTenantId: tokenTenant,
+    mismatches,
+    error: mismatches.length
+      ? 'PAC CLI and Azure CLI are authenticated to different tenants. Switch PAC auth or Azure CLI tenant before importing.'
+      : null,
+  };
+}
+
+module.exports = {
+  decodeJwtPayload,
+  parsePacTenantId,
+  tenantIdFromToken,
+  validateCliTenantAlignment,
+};

plugins/power-pages/scripts/lib/pages-list-diff.js

@@ -17,6 +17,32 @@ function normalizeComparableName(value) {
   return normalizeName(String(value || '')).toLowerCase();
 }
 
+function comparableNameAliases(value) {
+  const normalized = normalizeComparableName(value);
+  if (!normalized) return [];
+  const aliases = new Set([normalized]);
+  // Template family names can omit the SPA framework while the imported site row
+  // includes it, e.g. `311 Portal` in solution metadata but `311 Portal React`
+  // in `pac pages list -v`. Strip only known trailing framework tokens so the
+  // fallback does not turn into arbitrary fuzzy matching across unrelated sites.
+  const withoutFramework = normalized.replace(/\s+(react|vue|angular|astro)\s*$/i, '').trim();
+  if (withoutFramework) aliases.add(withoutFramework);
+  return [...aliases];
+}
+
+function siteNameMatchesExpected(siteName, expectedSiteName) {
+  const siteAliases = comparableNameAliases(siteName);
+  const expectedAliases = new Set(comparableNameAliases(expectedSiteName));
+  return siteAliases.some((alias) => expectedAliases.has(alias));
+}
+
+function expectedSiteNamesFromOptions(options = {}) {
+  const names = [];
+  if (options.expectedSiteName) names.push(options.expectedSiteName);
+  if (Array.isArray(options.expectedSiteNames)) names.push(...options.expectedSiteNames);
+  return names.filter((name) => normalizeComparableName(name));
+}
+
 function parsePagesListVerbose(output) {
   // `pac pages list -v` is a human table whose exact columns vary by CLI
   // version/cloud. The stable token we need is the Website Record ID GUID.
@@ -63,9 +89,9 @@ function diffPagesListVerbose(beforeOutput, afterOutput, options = {}) {
     };
   }
   if (added.length === 0) {
-    const expectedSiteName = normalizeComparableName(options.expectedSiteName);
-    if (expectedSiteName) {
-      const existing = after.filter((row) => normalizeComparableName(row.siteName) === expectedSiteName);
+    const expectedSiteNames = expectedSiteNamesFromOptions(options);
+    if (expectedSiteNames.length) {
+      const existing = after.filter((row) => expectedSiteNames.some((expectedSiteName) => siteNameMatchesExpected(row.siteName, expectedSiteName)));
       if (existing.length === 1) {
         return {
           status: 'existing',

plugins/power-pages/scripts/tests/cli-tenant-alignment.test.js

@@ -0,0 +1,83 @@
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+
+const {
+  parsePacTenantId,
+  tenantIdFromToken,
+  validateCliTenantAlignment,
+} = require('../lib/cli-tenant-alignment');
+const { parseArgs, run } = require('../validate-cli-tenant-alignment');
+
+const TENANT_A = '72f988bf-86f1-41af-91ab-2d7cd011db47';
+const TENANT_B = '11111111-2222-3333-4444-555555555555';
+
+function fakeJwt(tenantId) {
+  return [
+    Buffer.from(JSON.stringify({ alg: 'none' })).toString('base64url'),
+    Buffer.from(JSON.stringify({ tid: tenantId })).toString('base64url'),
+    '',
+  ].join('.');
+}
+
+function fakeExecFile({ pacTenant = TENANT_A, azTenant = TENANT_A } = {}) {
+  return (command, args) => {
+    if (command === 'pac' && args.join(' ') === 'auth who') {
+      return `Connected as user@contoso.com\nTenant ID:    ${pacTenant}\n`;
+    }
+    if (command === 'az' && args.join(' ') === 'account show --query tenantId -o tsv') {
+      return `${azTenant}\n`;
+    }
+    throw new Error(`unexpected command: ${command} ${args.join(' ')}`);
+  };
+}
+
+test('parsePacTenantId extracts Tenant ID from PAC auth output', () => {
+  assert.equal(parsePacTenantId(`User: u\nTenant ID:    ${TENANT_A}\n`), TENANT_A);
+  assert.equal(parsePacTenantId(`Tenant: ${TENANT_A}`), TENANT_A);
+  assert.equal(parsePacTenantId('Tenant ID: not-a-guid'), null);
+});
+
+test('tenantIdFromToken extracts tid from an Azure CLI access token', () => {
+  assert.equal(tenantIdFromToken(fakeJwt(TENANT_A)), TENANT_A);
+  assert.equal(tenantIdFromToken('not.jwt'), null);
+});
+
+test('validateCliTenantAlignment succeeds when PAC, Azure account, and token tenants match', () => {
+  assert.deepEqual(validateCliTenantAlignment({
+    envUrl: 'https://org.crm.dynamics.com',
+    token: fakeJwt(TENANT_A),
+  }, {
+    execFile: fakeExecFile(),
+  }), {
+    ok: true,
+    pacTenantId: TENANT_A,
+    azTenantId: TENANT_A,
+    tokenTenantId: TENANT_A,
+    mismatches: [],
+    error: null,
+  });
+});
+
+test('validateCliTenantAlignment blocks when PAC and Azure tenants differ', () => {
+  const result = validateCliTenantAlignment({
+    envUrl: 'https://org.crm.dynamics.com',
+    token: fakeJwt(TENANT_A),
+  }, {
+    execFile: fakeExecFile({ pacTenant: TENANT_B, azTenant: TENANT_A }),
+  });
+
+  assert.equal(result.ok, false);
+  assert.deepEqual(result.mismatches, ['pac-vs-az', 'pac-vs-token']);
+  assert.match(result.error, /different tenants/i);
+});
+
+test('run requires either an environment URL or token and passes CLI args through', () => {
+  assert.deepEqual(parseArgs(['--envUrl', 'https://org.crm.dynamics.com', '--token', 't']), {
+    envUrl: 'https://org.crm.dynamics.com',
+    token: 't',
+  });
+  assert.equal(run([]).ok, false);
+  assert.equal(run(['--token', fakeJwt(TENANT_A)], { execFile: fakeExecFile() }).ok, true);
+});

plugins/power-pages/scripts/tests/pages-list-diff.test.js

@@ -81,6 +81,28 @@ test('diffPagesListVerbose can match an existing template site when import creat
   });
 });
 
+test('diffPagesListVerbose can match an existing template site by normalized aliases when import updates the solution', () => {
+  const before = `311 Portal React      ${ID1}      Inactive`;
+  const after = before;
+
+  assert.deepEqual(diffPagesListVerbose(before, after, { expectedSiteName: '311 Portal' }), {
+    status: 'existing',
+    siteName: '311 Portal React',
+    websiteRecordId: ID1,
+    state: 'Inactive',
+    inactive: true,
+    added: [],
+    warning: 'No new site appeared in pac pages list; matched an existing site by expected template site name.',
+  });
+});
+
+test('diffPagesListVerbose can match an existing template site using alternate expected names', () => {
+  const before = `311 Portal React      ${ID1}      Inactive`;
+  const after = before;
+
+  assert.equal(diffPagesListVerbose(before, after, { expectedSiteNames: ['Supplier Portal', '311 Portal'] }).status, 'existing');
+});
+
 test('diffPagesListVerbose reports ambiguous existing template site matches', () => {
   const before = `Template Site      ${ID1}      Inactive\nTemplate Site      ${ID2}      Inactive`;
   const after = before;
@@ -106,5 +128,20 @@ test('parseArgs reads before and after snapshot file paths', () => {
     before: '/tmp/before.txt',
     after: '/tmp/after.txt',
     expectedSiteName: 'Template Site',
+    expectedSiteNames: ['Template Site'],
+  });
+});
+
+test('parseArgs keeps repeated expected site names as fallback aliases', () => {
+  assert.deepEqual(parseArgs([
+    '--before', '/tmp/before.txt',
+    '--after', '/tmp/after.txt',
+    '--expectedSiteName', '311 Portal',
+    '--expectedSiteName', '311 Portal React',
+  ]), {
+    before: '/tmp/before.txt',
+    after: '/tmp/after.txt',
+    expectedSiteName: '311 Portal React',
+    expectedSiteNames: ['311 Portal', '311 Portal React'],
   });
 });

plugins/power-pages/scripts/validate-cli-tenant-alignment.js

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+'use strict';
+
+const { validateCliTenantAlignment } = require('./lib/cli-tenant-alignment');
+const { formatJsonResult } = require('./lib/template-cli-args');
+
+function parseArgs(argv) {
+  const args = {};
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--envUrl') args.envUrl = argv[++i];
+    else if (arg === '--token') args.token = argv[++i];
+  }
+  return args;
+}
+
+function run(argv = process.argv.slice(2), deps = {}) {
+  const args = parseArgs(argv);
+  if (!args.envUrl && !args.token) {
+    return { ok: false, error: 'Usage: validate-cli-tenant-alignment.js --envUrl <url> [--token <bearer-token>]' };
+  }
+  return validateCliTenantAlignment(args, deps);
+}
+
+if (require.main === module) {
+  process.stdout.write(formatJsonResult(run()));
+}
+
+module.exports = { parseArgs, run };