@sun-asterisk/sungen 3.2.24 → 3.2.25

package/src/harness/run-manifest.ts

@@ -0,0 +1,254 @@
+/**
+ * Run-manifest — which scenarios does a QA edit actually oblige us to re-run?
+ *
+ * The problem it serves: the JSON reporter writes ONE file per target, named only for the unit +
+ * platform + env, so a subset re-run overwrites the full run's results. `sungen results merge`
+ * restores the lost half, but only if the caller knew to back the file up first — and only after
+ * the caller decided WHICH cases to run. This module answers the second question deterministically
+ * so `run-test --change-only` is a computation, not a guess.
+ *
+ * Sibling of `manifest.ts`, deliberately not an extension of it: that one hashes spec.md sections
+ * to decide what to REGENERATE, this one hashes the compiled inputs to decide what to RE-RUN. Same
+ * conventions (deterministic hashing, `.sungen/` storage, a plan object), different question.
+ *
+ * The bias is fixed and one-directional: when an edit cannot be attributed to specific scenarios,
+ * EVERY scenario is selected. Over-running costs minutes; under-running reports a scenario green
+ * that never re-ran after the change that broke it, which is the failure this whole family of
+ * guards exists to prevent.
+ *
+ * Storage: `.sungen/run-manifest/<slug>.json`.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { createHash } from 'crypto';
+import yaml from 'yaml';
+import { featureFilesFor, reportSlug } from './unit-paths';
+import { readTextFile } from './read-text';
+import { GherkinParser } from '../generators/gherkin-parser';
+
+const sha = (s: string): string => createHash('sha256').update(s).digest('hex').slice(0, 16);
+
+/** Mirrors SelectorResolver.generateKey — a `[Ref]` becomes this before the YAML lookup. */
+const refToKey = (label: string): string => label.normalize('NFC').toLowerCase().trim().replace(/\s+/g, ' ');
+
+export interface RunManifest {
+  unit: string;
+  recordedAt: string;
+  /** scenario title → hash of its whole block (tags + steps) */
+  scenarios: Record<string, string>;
+  /** selectors.yaml key → hash of that entry */
+  selectorKeys: Record<string, string>;
+  /** test-data key → hash of that value */
+  dataKeys: Record<string, string>;
+  /** scenario title → the selector keys and data keys its steps touch */
+  deps: Record<string, { selectors: string[]; data: string[] }>;
+  /** hash of the Background block: a change there reaches every scenario */
+  background: string;
+  /**
+   * PROJECT-level inputs, `qa/<file>` → hash. These reach every scenario of every unit — app.yaml
+   * carries widget recipes and the behaviour profile, datasources.yaml the db/api endpoints,
+   * capabilities.yaml which drivers even load. Per-key attribution is not possible (a recipe change
+   * can alter any step's compilation), so a move here widens to the whole unit. They were the last
+   * known under-selection hole: edit app.yaml and the selection used to report "nothing changed".
+   */
+  globals: Record<string, string>;
+}
+
+export interface ChangeSelection {
+  unit: string;
+  /** scenario titles to re-run, in feature order */
+  scenarios: string[];
+  /** why each was selected — one short clause per title, for the operator */
+  reasons: Record<string, string>;
+  /** true when the whole unit was selected because the change could not be attributed */
+  all: boolean;
+  summary: { total: number; selected: number; firstRun: boolean };
+}
+
+const manifestPath = (cwd: string, unit: string): string =>
+  path.join(cwd, '.sungen', 'run-manifest', `${reportSlug(unit)}.json`);
+
+/** Flatten a YAML mapping to `key → hash(value)`; a non-mapping file yields one whole-file entry. */
+function hashTopLevel(file: string): Record<string, string> {
+  if (!fs.existsSync(file)) return {};
+  const text = readTextFile(file);
+  let doc: unknown;
+  try {
+    doc = yaml.parse(text);
+  } catch {
+    // Unparseable: attribute nothing, and let the caller widen to the whole unit rather than
+    // silently treating a broken file as "no change".
+    return { __unparseable__: sha(text) };
+  }
+  // An empty or comment-only file parses to null. That is an EMPTY mapping — nothing to attribute
+  // and nothing to widen on — not an unrecognised shape. (A test-data file holding only a comment
+  // made the first probe widen to all 18 scenarios.)
+  if (doc === null || doc === undefined) return {};
+  if (typeof doc !== 'object' || Array.isArray(doc)) return { __whole__: sha(text) };
+  const out: Record<string, string> = {};
+  for (const [k, v] of Object.entries(doc as Record<string, unknown>)) {
+    out[refToKey(k)] = sha(JSON.stringify(v ?? null));
+  }
+  return out;
+}
+
+/** Read the unit's compiled inputs and fingerprint them. */
+export function buildRunManifest(cwd: string, unitDir: string, unit: string): RunManifest {
+  const parser = new GherkinParser();
+  const scenarios: Record<string, string> = {};
+  const deps: RunManifest['deps'] = {};
+  const bgParts: string[] = [];
+
+  for (const file of featureFilesFor(unitDir, unit)) {
+    const parsed = parser.parseFeatureFile(file);
+    if (parsed.background?.steps?.length) {
+      bgParts.push(parsed.background.steps.map((s) => `${s.keyword} ${s.text}`).join('\n'));
+    }
+    for (const sc of parsed.scenarios) {
+      const block = [...(sc.tags || []), ...sc.steps.map((s) => `${s.keyword} ${s.text}`)].join('\n');
+      scenarios[sc.name] = sha(block);
+      const sel = new Set<string>();
+      const dat = new Set<string>();
+      for (const st of sc.steps) {
+        if (st.selectorRef) sel.add(refToKey(st.selectorRef));
+        if (st.parentRef) sel.add(refToKey(st.parentRef));
+        if (st.childRef) sel.add(refToKey(st.childRef));
+        if (st.dataRef) dat.add(refToKey(st.dataRef));
+      }
+      deps[sc.name] = { selectors: [...sel].sort(), data: [...dat].sort() };
+    }
+  }
+
+  const selDir = path.join(unitDir, 'selectors');
+  const dataDir = path.join(unitDir, 'test-data');
+  const collect = (dir: string): Record<string, string> => {
+    if (!fs.existsSync(dir)) return {};
+    const merged: Record<string, string> = {};
+    for (const f of fs.readdirSync(dir).filter((n) => /\.ya?ml$/.test(n)).sort()) {
+      Object.assign(merged, hashTopLevel(path.join(dir, f)));
+    }
+    return merged;
+  };
+
+  // Project-level config lives beside the units, not inside them.
+  const qaDir = path.join(cwd, 'qa');
+  const globals: Record<string, string> = {};
+  for (const name of ['app.yaml', 'datasources.yaml', 'capabilities.yaml']) {
+    const f = path.join(qaDir, name);
+    if (fs.existsSync(f)) globals[`qa/${name}`] = sha(readTextFile(f));
+  }
+
+  return {
+    unit,
+    recordedAt: new Date().toISOString(),
+    scenarios,
+    selectorKeys: collect(selDir),
+    dataKeys: collect(dataDir),
+    deps,
+    background: sha(bgParts.join('\n---\n')),
+    globals,
+  };
+}
+
+export function readRunManifest(cwd: string, unit: string): RunManifest | null {
+  const p = manifestPath(cwd, unit);
+  // Absent baseline is the FIRST-RUN case, not an error — selectChanged widens to the whole unit.
+  if (!fs.existsSync(p)) return null;
+  try { return JSON.parse(readTextFile(p)) as RunManifest; } catch { return null; }
+}
+
+export function writeRunManifest(cwd: string, unit: string, m: RunManifest): string {
+  const p = manifestPath(cwd, unit);
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  fs.writeFileSync(p, JSON.stringify(m, null, 2));
+  return p;
+}
+
+/** Keys whose hash differs, was added, or disappeared. */
+function movedKeys(before: Record<string, string>, after: Record<string, string>): Set<string> {
+  const moved = new Set<string>();
+  for (const k of new Set([...Object.keys(before), ...Object.keys(after)])) {
+    if (before[k] !== after[k]) moved.add(k);
+  }
+  return moved;
+}
+
+/**
+ * Which scenarios must re-run, given the recorded manifest and the current inputs.
+ *
+ * A selector key matches a step's `[Ref]` either exactly or as one of the resolver's suffixed
+ * forms (`key--button`, `key--3`), because that is how the lookup itself resolves.
+ */
+export function selectChanged(
+  before: RunManifest | null,
+  after: RunManifest,
+  /**
+   * Run-affecting files an outside source (git) reports as changed. Passed in rather than read here
+   * so this function stays pure and testable; the CLI gathers the evidence. Non-empty + an
+   * otherwise-empty selection means something changed that per-key hashing cannot see (a rename, a
+   * new file shape) — unattributable, so it widens like the other unattributable cases.
+   */
+  externalChanged: string[] = []
+): ChangeSelection {
+  const titles = Object.keys(after.scenarios);
+  const selectAll = (reason: string): ChangeSelection => ({
+    unit: after.unit,
+    scenarios: titles,
+    reasons: Object.fromEntries(titles.map((t) => [t, reason])),
+    all: true,
+    summary: { total: titles.length, selected: titles.length, firstRun: !before },
+  });
+
+  if (!before) return selectAll('no previous run recorded');
+  const movedGlobals = movedKeys(before.globals || {}, after.globals || {});
+  if (movedGlobals.size) {
+    return selectAll(`project config changed (${[...movedGlobals].join(', ')}) — it reaches every scenario`);
+  }
+  if (before.background !== after.background) return selectAll('the Background changed — it runs before every scenario');
+  if (after.selectorKeys.__unparseable__ || after.dataKeys.__unparseable__) {
+    return selectAll('a selectors/test-data file could not be parsed, so the edit cannot be attributed');
+  }
+  if (after.selectorKeys.__whole__ || after.dataKeys.__whole__) {
+    const movedWhole = movedKeys(before.selectorKeys, after.selectorKeys).size
+      || movedKeys(before.dataKeys, after.dataKeys).size;
+    if (movedWhole) return selectAll('a selectors/test-data file is not a key mapping, so the edit cannot be attributed');
+  }
+
+  const movedSel = movedKeys(before.selectorKeys, after.selectorKeys);
+  const movedDat = movedKeys(before.dataKeys, after.dataKeys);
+  const touches = (key: string, dep: string): boolean => key === dep || key.startsWith(`${dep}--`);
+
+  const reasons: Record<string, string> = {};
+  for (const title of titles) {
+    if (before.scenarios[title] !== after.scenarios[title]) {
+      reasons[title] = before.scenarios[title] ? 'its steps or tags changed' : 'new scenario';
+      continue;
+    }
+    const dep = after.deps[title] || { selectors: [], data: [] };
+    const sel = [...movedSel].filter((k) => dep.selectors.some((d) => touches(k, d)));
+    if (sel.length) { reasons[title] = `selector changed: ${sel.slice(0, 3).join(', ')}`; continue; }
+    const dat = [...movedDat].filter((k) => dep.data.some((d) => touches(k, d)));
+    if (dat.length) { reasons[title] = `test-data changed: ${dat.slice(0, 3).join(', ')}`; continue; }
+  }
+
+  let selected = titles.filter((t) => reasons[t]);
+
+  // Git cross-check. Per-key hashing is blind to structural moves — a renamed selectors file, a new
+  // file shape, an encoding change — because the keys simply appear or vanish. When an outside
+  // source reports run-affecting files changed and we attributed NOTHING, that is the same
+  // unattributable case as an unparseable YAML, so it widens rather than reporting "all current".
+  if (!selected.length && externalChanged.length) {
+    return selectAll(
+      `git reports ${externalChanged.length} run-affecting file(s) changed (${externalChanged.slice(0, 3).join(', ')}) `
+      + 'that per-key hashing could not attribute'
+    );
+  }
+
+  return {
+    unit: after.unit,
+    scenarios: selected,
+    reasons,
+    all: false,
+    summary: { total: titles.length, selected: selected.length, firstRun: false },
+  };
+}

package/src/harness/viewpoint-ledger.ts

@@ -170,19 +170,39 @@ export function viewpointLedger(viewpointPath: string, scenarios: ScenarioInfo[]
  * The language has no reload/back step at all (#593), so the honest outcome is a `@manual`
  * deferral naming the gesture — not a silent swap.
  */
-const BROWSER_GESTURES: Array<{ gesture: string; re: RegExp; appSubstitute: RegExp }> = [
+const BROWSER_GESTURES: Array<{ gesture: string; re: RegExp; appSubstitute: RegExp; platform?: string }> = [
   { gesture: 'browser back', re: /\bbrowser(?:'s)?[ -]?(?:back|history)\b|\bhistory[ -]back\b/i,
-    appSubstitute: /\bclick \[[^\]]*back[^\]]*\]/i },
+    appSubstitute: /\bclick \[[^\]]*back[^\]]*\]/i, platform: 'web' },
   { gesture: 'browser reload/refresh', re: /\b(?:page |browser )?(?:reload|refresh)(?:ing|ed|es)?\b/i,
-    appSubstitute: /\bis on \[[^\]]+\] page\b/i },
+    appSubstitute: /\bis on \[[^\]]+\] page\b/i, platform: 'web' },
   { gesture: 'closing and reopening the tab', re: /\bclos(?:e|ing) (?:and reopen\w*\s*)?the tab\b|\breopen\w* the tab\b/i,
-    appSubstitute: /\bis on \[[^\]]+\] page\b/i },
+    appSubstitute: /\bis on \[[^\]]+\] page\b/i, platform: 'web' },
+
+  // The same class on mobile, where the vocabulary is different but the trap is identical: an
+  // in-app control is not the OS gesture. Android's hardware/system back does not run the
+  // screen's own handler unless the app wires it, and backgrounding can destroy an Activity that
+  // an in-app navigation never touches — so a defect that only appears on the OS path lives
+  // exactly in the substitution (#626). The check was web-only, so mobile flows were silent about
+  // the very risk it exists to catch.
+  { gesture: 'the OS/hardware back gesture', platform: 'mobile',
+    re: /\b(?:hardware|system|os|device|android|physical)[ -]?back\b|\bback (?:gesture|button|swipe)\b|\bswipe[ -]back\b/i,
+    appSubstitute: /\b(?:tap|click) \[[^\]]*back[^\]]*\]/i },
+  { gesture: 'backgrounding and resuming the app', platform: 'mobile',
+    re: /\b(?:background(?:ing|ed)?|foreground(?:ing|ed)?|app switcher|recent apps|minimi[sz]|resum(?:e|ing)|kill(?:ed|ing)? the app|force[ -]stop|process death)\b/i,
+    appSubstitute: /\b(?:tap|click) \[[^\]]+\]|is on \[[^\]]+\] screen\b/i },
+  { gesture: 'rotating the device', platform: 'mobile',
+    re: /\b(?:rotat(?:e|ing|ion)|landscape|portrait|orientation change)\b/i,
+    appSubstitute: /\bis on \[[^\]]+\] screen\b/i },
 ];
 
 export function browserGestureSubstitutions(
-  viewpointPath: string, scenarios: ScenarioInfo[],
+  viewpointPath: string, scenarios: ScenarioInfo[], platform?: string,
 ): Array<{ gesture: string; item: string }> {
   const out: Array<{ gesture: string; item: string }> = [];
+  // A gesture only applies where its platform does: "reload" means nothing on a native app, and
+  // "backgrounding" means nothing in a browser tab. An unknown platform checks everything, which
+  // is how the web-only set behaved before.
+  const applies = (g: { platform?: string }): boolean => !platform || !g.platform || g.platform === platform;
   // Judged PER SCENARIO, not over the whole file: a @manual scenario elsewhere that merely
   // mentions the gesture in passing (explaining a tooling limit) silenced the check for an
   // item that an automated scenario had quietly substituted.
@@ -190,6 +210,7 @@ export function browserGestureSubstitutions(
   const automated = scenarios.filter((s) => !s.manual).map((s) => s.haystack);
   for (const item of parseViewpointItems(viewpointPath)) {
     for (const g of BROWSER_GESTURES) {
+      if (!applies(g)) continue;
       if (!g.re.test(item.text)) continue;
       // A @manual scenario whose own subject IS the gesture is the honest answer.
       if (deferred.some((h) => g.re.test(h))) break;

package/src/index.ts

@@ -20,6 +20,7 @@ export type { ResolvedAppProfile } from './generators/test-generator/app-profile
 export type { MappedStep } from './generators/test-generator/step-mapper';
 export type { ParsedStep } from './generators/gherkin-parser';
 export { getPathCode, inferPath, resolvePathVariables } from './generators/test-generator/utils/path-inference';
+export { formatToRegexSource, formatToRegexLiteral, hasFormatToken } from './generators/test-generator/utils/format-pattern';
 export { LIST_MEMBER_ROLES } from './generators/test-generator/utils/selector-resolver';
 
 // --- Precondition-annotation override grammar (shared by the @query / @api driver codegen) ---

package/src/orchestrator/lockstep-version.ts

@@ -0,0 +1,46 @@
+import { spawnSync } from 'child_process';
+
+/**
+ * Lockstep version resolution for the sungen package family.
+ *
+ * Core (`@sun-asterisk/sungen`) and every capability driver (`@sungen/driver-*`) are published
+ * together, so a project must hold ONE version line across all of them: a driver built against
+ * core 3.2.24 loading against core 3.2.20 is a silent-breakage class we refuse to ship. Both
+ * `sungen capability add` (first install) and `sungen update` (project sync) resolve the target
+ * version through here so they can never disagree.
+ */
+
+/** The running CLI's (core) version — family packages install in lockstep with it (not `@latest`). */
+export function coreVersion(): string {
+  try { return require('../../package.json').version || 'latest'; } catch { return 'latest'; }
+}
+
+/**
+ * Resolve the version to install for a family package, given the running `core` version.
+ *
+ * Lockstep wants the EXACT `core` version. But the beta channel publishes `<core>-beta.N` before a
+ * stable `<core>` ever exists — so a released core (e.g. 3.2.10) asking for `@3.2.10` hits ETARGET
+ * out-of-the-box when npm only has `3.2.10-beta.2` (`sungen capability add` then fails for a fresh
+ * user). Fall back on the SAME version line: prefer exact `core`, else the highest `core-beta.N`,
+ * else the `beta` dist-tag as a last resort. Keeps the driver's pinned core-dep on the same line.
+ */
+export function resolveDriverVersion(pkg: string, core: string): string {
+  if (core === 'latest') return 'beta';
+  try {
+    const out = spawnSync('npm', ['view', pkg, 'versions', '--json'], { encoding: 'utf-8', shell: true });
+    if (out.status !== 0 || !out.stdout) return core; // can't query → let the exact install try/fail
+    let versions: string[] = [];
+    const parsed = JSON.parse(out.stdout);
+    versions = Array.isArray(parsed) ? parsed : [parsed];
+    if (versions.includes(core)) return core; // exact exists → lockstep
+    const prefix = `${core}-beta.`;
+    const betas = versions
+      .filter((v) => typeof v === 'string' && v.startsWith(prefix))
+      .map((v) => parseInt(v.slice(prefix.length), 10))
+      .filter((n) => Number.isInteger(n));
+    if (betas.length) return `${core}-beta.${Math.max(...betas)}`; // highest same-line prerelease
+    return 'beta'; // nothing on this line → newest beta dist-tag
+  } catch {
+    return core;
+  }
+}

package/src/orchestrator/project-deps-sync.ts

@@ -0,0 +1,175 @@
+import { spawnSync } from 'child_process';
+import * as fs from 'fs';
+import * as path from 'path';
+import { resolveDriverVersion } from './lockstep-version';
+
+/**
+ * Project-local sync of the sungen package family after a global `sungen update`.
+ *
+ * `sungen update` used to run `npm install -g @sun-asterisk/sungen@<channel>` and stop there. That
+ * left every PROJECT-local copy behind, and a project always has them: `sungen capability add <x>`
+ * installs `@sungen/driver-<x>` as a devDependency pinned to the core version of the day, and each
+ * driver declares `@sun-asterisk/sungen` as a dependency — so a local core lands in the project's
+ * node_modules too, along with the `sungen` bin link. The lockfile then pins all of it. Result after
+ * an update: global 3.2.24, project still 3.2.20, and `npx sungen` inside the project silently
+ * running the OLD compiler — with drivers built against a core that is no longer the one loading
+ * them.
+ *
+ * So the update also reconciles the project: every family package declared (or physically present)
+ * in the project is reinstalled on the running core's version line.
+ */
+
+/** Family = core + every capability driver. These MUST share one version line in a project. */
+const CORE_PKG = '@sun-asterisk/sungen';
+const isFamily = (name: string): boolean => name === CORE_PKG || name.startsWith('@sungen/driver-');
+
+/** Declared specs pointing at a checkout, not the registry — a workspace/dogfood link we must not clobber. */
+const isLocalSpec = (spec: string): boolean =>
+  /^(file:|link:|workspace:|portal:|\.{1,2}\/|\/)/.test(spec) || spec.startsWith('git+') || spec.startsWith('github:');
+
+export interface FamilyPkg {
+  pkg: string;
+  /** Range in package.json dependencies/devDependencies, or null when only present transitively. */
+  declared: string | null;
+  /** Version actually resolved in the project tree, or null when absent. `link` = symlinked. */
+  installed: string | null;
+}
+
+export interface DepSyncPlan {
+  /** `npm install -D` specs to run. Empty when nothing needs to change. */
+  specs: string[];
+  /** Family packages found in the project, for reporting. */
+  found: FamilyPkg[];
+  /** Packages deliberately left alone, with the reason. */
+  skipped: Array<{ pkg: string; why: string }>;
+  /** Set when there is no project to sync at all (no package.json / no family packages). */
+  noop?: string;
+}
+
+/** Read a package.json, returning null when missing or malformed. */
+function readJson(file: string): Record<string, any> | null {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+/** Version of `pkg` as installed in the project tree, or null. Symlinked (workspace) → `link`. */
+function installedVersion(cwd: string, pkg: string): string | null {
+  const dir = path.join(cwd, 'node_modules', ...pkg.split('/'));
+  try {
+    if (fs.lstatSync(dir).isSymbolicLink()) return 'link';
+  } catch {
+    return null;
+  }
+  return readJson(path.join(dir, 'package.json'))?.version ?? null;
+}
+
+/**
+ * Decide what the project needs so its family packages sit on `core`'s version line.
+ *
+ * Pure apart from reading the project tree and (for stale packages) asking npm which versions exist
+ * on that line — no installs, so `--dry-run` and the tests can plan without side effects.
+ */
+export function planProjectDepSync(
+  cwd: string,
+  core: string,
+  resolve: (pkg: string, core: string) => string = resolveDriverVersion,
+): DepSyncPlan {
+  const pkgJson = readJson(path.join(cwd, 'package.json'));
+  if (!pkgJson) {
+    return { specs: [], found: [], skipped: [], noop: 'no package.json here — nothing project-local to sync' };
+  }
+
+  const declaredAll: Record<string, string> = { ...pkgJson.dependencies, ...pkgJson.devDependencies };
+  const names = new Set(Object.keys(declaredAll).filter(isFamily));
+
+  // A transitively-installed core (pulled in by a driver) is the copy that owns the project's `sungen`
+  // bin link, so it must be reconciled even though nothing declares it.
+  if (!names.has(CORE_PKG) && installedVersion(cwd, CORE_PKG)) names.add(CORE_PKG);
+
+  if (!names.size) {
+    return {
+      specs: [],
+      found: [],
+      skipped: [],
+      noop: 'no sungen packages installed in this project — the global update is all that was needed',
+    };
+  }
+
+  const found: FamilyPkg[] = [...names].sort().map((pkg) => ({
+    pkg,
+    declared: declaredAll[pkg] ?? null,
+    installed: installedVersion(cwd, pkg),
+  }));
+
+  const specs: string[] = [];
+  const skipped: Array<{ pkg: string; why: string }> = [];
+
+  for (const entry of found) {
+    if (entry.declared && isLocalSpec(entry.declared)) {
+      skipped.push({ pkg: entry.pkg, why: `declared as ${entry.declared} (local checkout, not the registry)` });
+      continue;
+    }
+    if (entry.installed === 'link') {
+      skipped.push({ pkg: entry.pkg, why: 'symlinked (workspace or npm link)' });
+      continue;
+    }
+    if (entry.installed === core) continue; // already on the running core's exact version
+    specs.push(`${entry.pkg}@${resolve(entry.pkg, core)}`);
+  }
+
+  return { specs, found, skipped };
+}
+
+/**
+ * Reconcile the project's sungen family packages with the running core version.
+ *
+ * Runs ONE `npm install -D` for every stale package so the lockfile is rewritten in a single
+ * resolution pass. Best-effort by design: a failure here (offline, private registry, no write
+ * permission) must not fail `sungen update` — the global install already succeeded, and the user
+ * gets the exact command to finish the job by hand.
+ *
+ * @returns true when the project ended up in sync (or needed nothing), false when the install failed
+ */
+export function syncProjectSungenDeps(cwd: string, core: string, dryRun: boolean): boolean {
+  const plan = planProjectDepSync(cwd, core);
+
+  console.log('🔗 Syncing project-local sungen packages...');
+  if (plan.noop) {
+    console.log(`   – ${plan.noop}\n`);
+    return true;
+  }
+  for (const s of plan.skipped) console.log(`   – skipped  ${s.pkg} — ${s.why}`);
+
+  if (!plan.specs.length) {
+    console.log(`   ✓ already on ${core}: ${plan.found.map((f) => f.pkg).join(', ')}\n`);
+    return true;
+  }
+
+  for (const f of plan.found) {
+    if (!plan.specs.some((s) => s.startsWith(`${f.pkg}@`))) continue;
+    const wasTransitive = f.declared ? '' : '  (was transitive — pinning explicitly)';
+    console.log(`   • ${f.pkg}  ${f.installed ?? '(not installed)'} → ${core}${wasTransitive}`);
+  }
+
+  const cmd = `npm install -D ${plan.specs.join(' ')}`;
+  if (dryRun) {
+    console.log(`   [dry-run] would run: ${cmd}\n`);
+    return true;
+  }
+
+  console.log(`   📦 ${cmd}`);
+  const r = spawnSync('npm', ['install', '-D', ...plan.specs], { cwd, stdio: 'inherit', shell: true });
+  if (r.status !== 0) {
+    console.warn(
+      `⚠️  Project-local sync failed — the GLOBAL sungen is now ${core}, but this project still holds\n` +
+      '   older copies, so `npx sungen` here would keep running the old compiler. Finish manually:\n' +
+      `       ${cmd}\n`,
+    );
+    return false;
+  }
+  console.log(`   ✓ project-local packages on ${core}\n`);
+  return true;
+}

package/src/orchestrator/project-initializer.ts

@@ -656,9 +656,12 @@ export class ProjectInitializer {
 
     // Mobile-only drops @playwright/test (no web runner needed). `ajv`/`ajv-formats` back the API
     // Driver's `expect {{name.body}} matches schema [Ref]` (loaded lazily; harmless if unused).
+    // fast-xml-parser: the API driver's XML request/response support lazy-requires it
+    // from the generated specs/api.ts — installed up front so an `encoding: xml`
+    // catalog entry works without a mid-suite MODULE_NOT_FOUND.
     const requiredDeps = this.mobileOnly
-      ? ['@types/node', 'yaml', 'ajv', 'ajv-formats']
-      : ['@playwright/test', '@types/node', 'yaml', 'ajv', 'ajv-formats'];
+      ? ['@types/node', 'yaml', 'ajv', 'ajv-formats', 'fast-xml-parser']
+      : ['@playwright/test', '@types/node', 'yaml', 'ajv', 'ajv-formats', 'fast-xml-parser'];
 
     let missingDeps: string[] = requiredDeps;
     try {