@sun-asterisk/sungen 3.2.31 → 3.2.33

package/dist/orchestrator/templates/specs-url-assert.ts

@@ -46,6 +46,16 @@ export interface UrlExpectation {
   declared?: string;
   /** The test-data key behind `declared`, so a failure can name what an author must go fix. */
   dataRef?: string;
+  /**
+   * The page selector declared `query: any` — the query string is not part of this page's identity,
+   * so SILENCE from the step stops meaning "there must be no query" (#748).
+   *
+   * Emitted only for a page whose entry says so. The default stays strict: a bare page means a bare
+   * page, which is the #464 assertion and the reason a filter regression cannot read as green.
+   * It is the no-`dataRef` branch alone that this relaxes — a step that declares `with {{v}}` still
+   * asserts every param it names, on this page as on any other.
+   */
+  ignoreQuery?: boolean;
 }
 
 /**
@@ -113,8 +123,14 @@ function locationMatches(pathname: RegExp, hostname: RegExp | undefined, u: URL)
  *                      tracking/UTM param the test never cared about cannot turn it red.
  *                      A declared fragment is asserted too; a declared value carrying no query
  *                      at all constrains the path only (the compiler warns: SG-W014).
+ *
+ * `query: any` on the page's selector entry overrides the FIRST rule only (#748): silence then
+ * means "the query is not mine to judge" instead of "there must be none". It is the escape hatch
+ * for a page whose query is generated at run time — `/admins/detail?id=<the row just clicked>` —
+ * which the strict rule makes unassertable and `with {{v}}` cannot express, since that asserts a
+ * literal. The second rule is untouched: declare params and they are still all checked.
  */
-export function urlMatches({ pathname, hostname, declared, dataRef }: UrlExpectation): (u: URL) => boolean {
+export function urlMatches({ pathname, hostname, declared, dataRef, ignoreQuery }: UrlExpectation): (u: URL) => boolean {
   return (u: URL): boolean => {
     if (!locationMatches(pathname, hostname, u)) return false;
 
@@ -123,7 +139,13 @@ export function urlMatches({ pathname, hostname, declared, dataRef }: UrlExpecta
     // undefined, and they mean opposite things: the first is a real assertion (a bare page must be
     // bare), the second is broken test-data. Only the generator knows which, and it says so by
     // emitting `dataRef` exactly when the step carried a `with {{v}}`.
-    if (!dataRef) return u.search === '';
+    // `query: any` on the page entry (#748): the query is not part of this page's identity, so
+    // silence from the step is not an assertion about it. Without this there is NO way to express
+    // "this path, whatever the query" — `with {{v}}` asserts a LITERAL value, and a detail page
+    // keyed by `?id=<the row just clicked>` has no literal to declare. Checked before the bare-page
+    // rule, never instead of the declared-value rule below: a step that names params still asserts
+    // them here exactly as anywhere else.
+    if (!dataRef) return ignoreQuery ? true : u.search === '';
 
     // Silence is the whole bug class this assertion exists to kill, so an unusable declared value
     // is an ERROR, not a quiet verdict. Returning false would read as "the app is wrong"; these

package/dist/orchestrator/templates/wdio.conf.ts

@@ -48,6 +48,14 @@ function evidenceSlug(s: string): string {
     .slice(0, 80) || 'unnamed';
 }
 
+/**
+ * True only in the launcher process. `@wdio/runner` re-parses this very config inside EVERY worker
+ * it spawns, so anything logged at module scope prints once per spec unless it is gated. WDIO's own
+ * "am I a worker" test is this env var (`@wdio/local-runner` sets it when spawning; `@wdio/utils`
+ * reads it) — reuse it rather than inventing a second signal.
+ */
+const IS_LAUNCHER = !process.env.WDIO_WORKER_ID;
+
 /**
  * Auto-select MOBILE specs and classify each by its target OS (dual-target routing).
  *
@@ -82,7 +90,12 @@ function classifyMobileSpecs(root: string): Array<{ file: string; platform: stri
     .filter((full) => {
       try {
         return fs.readFileSync(full, 'utf-8').includes('@wdio/globals');
-      } catch {
+      } catch (e) {
+        // A spec listed by readdir that cannot be read cannot be classified, so it is excluded.
+        // Excluding it SILENTLY is the fault: WDIO only fails the run when the spec list is
+        // EMPTY ("No specs found to run"), so dropping one spec out of ten leaves a green suite
+        // containing a test that never executed. Name it, and let the count below show the shortfall.
+        if (IS_LAUNCHER) console.warn(`[sungen] could not read ${full} — EXCLUDED from this run: ${(e as Error).message}`);
         return false;
       }
     })
@@ -98,6 +111,16 @@ const androidSpecs = specEntries.filter((e) => e.platform !== 'ios').map((e) =>
 const iosSpecs = specEntries.filter((e) => e.platform !== 'android').map((e) => e.file);
 const mobileSpecs = specEntries.map((e) => e.file); // union — top-level fallback
 
+// What DISCOVERY found — a mobile suite is only trustworthy if you can see how many specs it
+// resolved: WDIO fails loudly on an EMPTY list but says nothing when the list is merely short,
+// which is exactly what a dropped spec looks like.
+//
+// Two things this number is not. It is not an error on 0: WDIO already exits 1 there
+// ("No specs found to run"), and a `--shard` that legitimately receives none must still return 0.
+// And under `--shard` it is the PRE-SHARD total, because ConfigParser slices `specs` down to the
+// shard's portion only after this file has finished evaluating.
+if (IS_LAUNCHER) console.log(`[sungen] specs: ${specEntries.length} mobile spec(s) — android ${androidSpecs.length}, ios ${iosSpecs.length}`);
+
 // App under test — env overrides the init-configured defaults.
 const APP_PACKAGE = process.env.APP_PACKAGE || '__APP_PACKAGE__';
 const APP_ACTIVITY = process.env.APP_ACTIVITY || '__APP_ACTIVITY__';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sun-asterisk/sungen",
-  "version": "3.2.31",
+  "version": "3.2.33",
   "description": "Deterministic E2E Test Compiler - Gherkin + Selectors → Playwright tests",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -40,8 +40,8 @@
     "@babel/types": "^7.28.5",
     "@cucumber/gherkin": "^37.0.0",
     "@cucumber/messages": "^31.0.0",
-    "@sungen/driver-data-factory": "3.2.31",
-    "@sungen/driver-ui": "3.2.31",
+    "@sungen/driver-data-factory": "3.2.33",
+    "@sungen/driver-ui": "3.2.33",
     "chalk": "^5.6.2",
     "commander": "^14.0.2",
     "dotenv": "^17.2.3",

package/src/cli/commands/audit.ts

@@ -7,8 +7,11 @@ import { acceptViewpointBaseline } from '../../harness/viewpoint-baseline';
 import { findUnitDir } from '../resolve-unit';
 
 
-function bar(ratio: number, width = 20): string {
-  const n = Math.round(ratio * width);
+export function bar(ratio: number, width = 20): string {
+  // A display helper must not be able to take the CLI down whatever the model hands it: an
+  // out-of-range ratio made `String.repeat` throw `Invalid count value: -5`, which killed the
+  // run mid-scorecard so the gate, the findings and the next-step hint never printed (#762).
+  const n = Math.max(0, Math.min(width, Math.round((Number.isFinite(ratio) ? ratio : 0) * width)));
   return '█'.repeat(n) + '░'.repeat(width - n);
 }
 
@@ -47,6 +50,11 @@ function render(r: AuditReport): void {
   L(`  ① Viewpoint Gate — page-type: ${r.gate.pageType ?? 'unknown'} — themes ${r.gate.themesCovered}/${r.gate.themesTotal} covered`);
   if (r.gate.gaps.length) for (const g of r.gate.gaps) L(`      ✗ ${g.status === 'shallow' ? 'SHALLOW' : 'MISSING'}: ${g.theme}`);
   else L('      ✓ all critical themes covered (with data assertions)');
+  // Name the scenario behind each covered theme (#776). A bare count gives a reviewer nothing to
+  // check, so a keyword matching something absurd stays invisible; the evidence line makes it
+  // obvious. Second line of defence — it holds even if the matcher is wrong again.
+  for (const c of r.gate.coveredBy ?? [])
+    L(`      ✓ ${c.theme} ← [${c.keyword}] ${c.by.length > 88 ? `${c.by.slice(0, 88)}…` : c.by}`);
   L('');
   if (r.flowQuality?.hasContract) {
     const fq = r.flowQuality;
@@ -109,7 +117,8 @@ function render(r: AuditReport): void {
     L(`  ⑦ Spec coverage — FR ${r.spec.frCovered}/${r.spec.frTotal} covered  [${r.spec.verdict.toUpperCase()}]`);
     for (const g of r.spec.triggerGaps) L(`      ✗ TRIGGER-UNCOVERED: "${g.constraint}"${g.code ? ` (${g.code})` : ''} mandated on [${g.required.join(', ')}], only tested on [${g.found.join(', ') || 'none'}] → missing ${g.missing.join(', ')}`);
     for (const u of r.spec.uncoveredMust.slice(0, 6)) L(`      ✗ SPEC-UNCOVERED: ${u.id} (MUST) — "${u.text}"`);
-    if (!r.spec.triggerGaps.length && !r.spec.uncoveredMust.length) L('      ✓ every MUST FR + per-constraint trigger covered');
+    for (const c of r.spec.clauseGaps.slice(0, 6)) L(`      ✗ SPEC-CLAUSE-UNCOVERED: ${c.id} (${c.polarity === 'negate' ? 'MUST NOT' : 'MUST'}) — "${c.text}"`);
+    if (!r.spec.triggerGaps.length && !r.spec.uncoveredMust.length && !r.spec.clauseGaps.length) L('      ✓ every MUST FR + per-constraint trigger covered');
     L('');
   }
   if (r.ledger.hasViewpoint && r.ledger.total > 0) {

package/src/cli/commands/capability.ts

@@ -4,33 +4,46 @@ import { createRequire } from 'module';
 import * as fs from 'fs';
 import * as path from 'path';
 import {
-  readCapabilities, writeCapabilities, loadDriverCatalog, driverMeta,
+  readCapabilities, writeCapabilities, loadDriverCatalog, driverMeta, capabilitiesPath,
+  type CapabilityProfile,
 } from '../../harness/capability';
 import { buildPlan, MANUAL_REASONS } from '../../harness/capability-plan';
 import { adapterRegistry } from '../../generators/test-generator/adapters';
 import { emitMobileRuntime, installMobileDriver } from '../../orchestrator/mobile-runtime-scaffolder';
+import { emitAppiumEnvironment, runAppiumEnvironmentSetup } from '../../orchestrator/appium-environment-setup';
 import { coreVersion, resolveDriverVersion } from '../../orchestrator/lockstep-version';
 import { findUnitDir, resolveUnit } from '../resolve-unit';
+import { readTextFile } from '../../harness/read-text';
 
 /**
- * Add `test:mobile` to the project's package.json scripts (if absent).
- * Idempotent — skips if the script is already set.
- * Returns true if the script was added, false if already present or no package.json.
+ * Add `test:mobile` to the project's package.json scripts (if absent). Idempotent.
+ *
+ * Four outcomes, not two. The old boolean collapsed "already present", "no package.json" and
+ * "could not parse it" into a single `false`, and the caller rendered that as
+ * `– skipped  package.json scripts[test:mobile] (already exists)` — which, on a malformed
+ * package.json, states the exact opposite of the truth: the script is absent, the command promised
+ * it, and the next thing the user sees is `npm error Missing script: "test:mobile"`.
  */
-function addMobileScript(cwd: string): boolean {
+type MobileScriptOutcome =
+  | { state: 'added' }
+  | { state: 'already-present' }
+  | { state: 'no-package-json' }
+  | { state: 'unreadable'; error: string };
+
+function addMobileScript(cwd: string): MobileScriptOutcome {
   const pkgPath = path.join(cwd, 'package.json');
-  if (!fs.existsSync(pkgPath)) return false;
+  if (!fs.existsSync(pkgPath)) return { state: 'no-package-json' };
   let pkg: Record<string, any>;
   try {
-    pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
-  } catch {
-    return false;
+    pkg = JSON.parse(readTextFile(pkgPath));   // BOM-tolerant: npm reads such a file fine, so must we
+  } catch (e) {
+    return { state: 'unreadable', error: (e as Error).message.split('\n')[0] };
   }
   if (!pkg.scripts || typeof pkg.scripts !== 'object') pkg.scripts = {};
-  if (pkg.scripts['test:mobile']) return false;
+  if (pkg.scripts['test:mobile']) return { state: 'already-present' };
   pkg.scripts['test:mobile'] = 'wdio run wdio.conf.ts';
   fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n', 'utf-8');
-  return true;
+  return { state: 'added' };
 }
 
 /**
@@ -157,7 +170,8 @@ export function registerCapabilityCommand(program: Command): void {
     .description('Enable a driver: install its package (if external) + record it in qa/capabilities.yaml')
     .option('--skip-install', 'Only record in the profile; do not run npm install')
     .option('--force', 'Switch the project platform even if a different one is already set (sungen is one platform per project)')
-    .action((driver: string, o: { skipInstall?: boolean; force?: boolean }) => {
+    .option('--skip-env-setup', 'Mobile: emit appium-environment/ but do not run it now — re-run later: ./appium-environment/setup.sh (Windows: setup.ps1)')
+    .action((driver: string, o: { skipInstall?: boolean; force?: boolean; skipEnvSetup?: boolean }) => {
       try {
         const cwd = process.cwd();
         const meta = driverMeta(driver);
@@ -219,9 +233,13 @@ export function registerCapabilityCommand(program: Command): void {
         }
 
         const profile = readCapabilities(cwd);
+        assertProfileWritable(profile, cwd);
         const enabled = Array.from(new Set([...profile.enabled, driver]));
         const platform = meta.kind === 'platform' ? driver : profile.platform;
-        writeCapabilities(cwd, { platform, enabled });
+        // Carry `verification` through. It is the recorded TEST TYPE, not a derived value: dropping
+        // it here silently re-derives the scope from `enabled`, handing an E2E-only project the
+        // @api/@query verification it had explicitly narrowed away.
+        writeCapabilities(cwd, { platform, enabled, verification: profile.verification });
         console.log(`✓ capability "${driver}" enabled${meta.kind === 'platform' ? ` (platform=${driver})` : ''}.`);
 
         // Emit the mobile runtime harness when the mobile platform driver is added.
@@ -234,14 +252,23 @@ export function registerCapabilityCommand(program: Command): void {
           for (const f of result.skipped) console.log(`  – skipped  ${f} (already exists)`);
 
           // Add test:mobile script to package.json (idempotent)
-          if (addMobileScript(cwd)) {
-            console.log('  ✓ created  package.json scripts[test:mobile]');
-          } else {
-            console.log('  – skipped  package.json scripts[test:mobile] (already exists)');
-          }
+          const script = addMobileScript(cwd);
+          if (script.state === 'added') console.log('  ✓ created  package.json scripts[test:mobile]');
+          else if (script.state === 'already-present') console.log('  – skipped  package.json scripts[test:mobile] (already exists)');
+          else if (script.state === 'no-package-json') console.log('  ✗ NOT added  package.json scripts[test:mobile] — no package.json here; run `npm init -y` first, then add: "test:mobile": "wdio run wdio.conf.ts"');
+          else console.log(`  ✗ NOT added  package.json scripts[test:mobile] — package.json is not valid JSON (${script.error}); fix it, then add: "test:mobile": "wdio run wdio.conf.ts"`);
+
+          // appium-environment/ provisioning bundle (idempotent per file) — emitted before the driver
+          // install, run after it so its Appium step finds the project-local CLI.
+          const env = emitAppiumEnvironment(cwd);
+          if (env.created.length > 0) console.log(`  ✓ created  appium-environment/ (${env.created.length} files)`);
+          else console.log('  – skipped  appium-environment/ (already exists)');
 
           // Best-effort driver install — non-fatal so capability add still succeeds offline.
           installMobileDriver(cwd);
+
+          // --skip-install means "record only" — then provisioning the machine is not wanted either.
+          runAppiumEnvironmentSetup(cwd, { skip: !!(o.skipEnvSetup || o.skipInstall) });
         }
 
         console.log('');
@@ -251,6 +278,22 @@ export function registerCapabilityCommand(program: Command): void {
       }
     });
 
+/**
+ * Every path that WRITES qa/capabilities.yaml first reads it, edits one field, and writes the whole
+ * file back. That round-trip is only safe when the read succeeded: an unreadable profile reads as
+ * "no platform, no drivers", so the write-back would replace the user's declaration with just the
+ * one driver being added — and `remove` would replace it with nothing at all. Refuse instead.
+ */
+function assertProfileWritable(profile: CapabilityProfile, cwd: string): void {
+  if (profile.source !== 'unreadable') return;
+  console.error(
+    `✗ ${path.relative(cwd, capabilitiesPath(cwd))} exists but could not be parsed.\n` +
+    `  Refusing to rewrite it: this command replaces the whole file, so it would discard the\n` +
+    `  platform, drivers and verification scope you declared. Fix the YAML and re-run.`,
+  );
+  process.exit(1);
+}
+
   // ── remove ─────────────────────────────────────────────────────────────
   cap
     .command('remove <driver>')
@@ -260,9 +303,10 @@ export function registerCapabilityCommand(program: Command): void {
       try {
         const cwd = process.cwd();
         const profile = readCapabilities(cwd);
+        assertProfileWritable(profile, cwd);
         const enabled = profile.enabled.filter((d) => d !== driver);
         const platform = profile.platform === driver ? undefined : profile.platform;
-        writeCapabilities(cwd, { platform, enabled });
+        writeCapabilities(cwd, { platform, enabled, verification: profile.verification });
         const meta = driverMeta(driver);
         if (o.uninstall && meta && !adapterRegistry.hasAdapter(meta.adapter || meta.id)) {
           spawnSync('npm', ['uninstall', meta.package], { stdio: 'inherit', shell: true });

package/src/cli/commands/delivery.ts

@@ -26,7 +26,7 @@ import { loadApiCatalog } from '../../exporters/api-catalog-loader';
 import { resolveApiEnvironment } from '../../exporters/api-environment';
 import { resolveWebBaseUrl } from '../../exporters/env-qa';
 import { resolvePlatformAppId } from '../../exporters/mobile-app-id';
-import { scanTestDataSecrets } from '../../harness/secret-scan';
+import { scanTestDataSecrets, formatSecretScan, type SecretScanResult } from '../../harness/secret-scan';
 import { EnvironmentInfo, PreflightCheck, ScreenSummary, TestCaseRow, ApiCatalogEntry } from '../../exporters/types';
 import { mapFilePath } from '../../exporters/matrix/map-loader';
 import {
@@ -39,7 +39,9 @@ import {
   hasReview,
 } from '../../exporters/matrix/export';
 import { MatrixFinding } from '../../exporters/matrix/types';
+import { ManualCarryReport } from '../../exporters/matrix/carry-manual-results';
 import { formatTestOutcome, resultTotals } from '../../exporters/matrix/result-totals';
+import { readCapabilities } from '../../harness/capability';
 
 const COLOR = {
   reset: '\x1b[0m',
@@ -375,14 +377,11 @@ function getEnvironment(cwd: string): EnvironmentInfo {
  * emits one csv+xlsx per OS and skips the (empty/misleading) base aggregate.
  */
 function isMobileProject(cwd: string): boolean {
-  try {
-    const p = path.join(cwd, 'qa', 'capabilities.yaml');
-    if (!fs.existsSync(p)) return false;
-    const parsed = parseYaml(fs.readFileSync(p, 'utf-8')) as { platform?: string } | null;
-    return parsed?.platform === 'mobile';
-  } catch {
-    return false;
-  }
+  // Reads through `readCapabilities` rather than re-parsing the file: the third copy of this parse
+  // was the third place a malformed capabilities.yaml quietly read as "web". The shared reader
+  // reports the breakage once per process; here it still degrades to web, which is the safe
+  // direction (per-OS delivery is skipped, nothing is deleted).
+  return readCapabilities(cwd).platform === 'mobile';
 }
 
 /**
@@ -736,11 +735,20 @@ async function exportMatrixTarget(
     return null;
   }
 
-  const { csvPath, xlsxPath } = await writeMatrixDeliverables(paths, model, opts.format ?? 'xlsx');
+  let deliverables: Awaited<ReturnType<typeof writeMatrixDeliverables>>;
+  try {
+    deliverables = await writeMatrixDeliverables(paths, model, opts.format ?? 'xlsx');
+  } catch (e) {
+    // The existing workbook could not be read, so writing would destroy its Manual results.
+    log(`  ${COLOR.red}not written:${COLOR.reset} ${(e as Error).message}`);
+    return null;
+  }
+  const { csvPath, xlsxPath, manualCarry } = deliverables;
   const passed = model.items.reduce((a, i) => a + i.resultCounts.passed, 0);
   const failed = model.items.reduce((a, i) => a + i.resultCounts.failed, 0);
   const written = [xlsxPath, csvPath].filter((p): p is string => !!p).map((p) => path.relative(cwd, p));
   for (const rel of written) log(`  ${COLOR.green}→ ${rel}${COLOR.reset}`);
+  if (manualCarry) printManualCarry(manualCarry);
   return {
     label: paths.label,
     items: model.manifest.itemCount,
@@ -751,6 +759,23 @@ async function exportMatrixTarget(
   };
 }
 
+/** What happened to the tester's hand-entered Manual results on this write (#756). */
+function printManualCarry(r: ManualCarryReport): void {
+  const kept = r.carried + r.unchecked;
+  if (kept + r.reset.length + r.notPlaced.length + r.duplicates.length === 0) return;
+  const list = (refs: string[]) => `${refs.slice(0, 4).join(', ')}${refs.length > 4 ? ', …' : ''}`;
+  log(`  Manual results: ${kept} kept${r.unchecked > 0 ? ` (${r.unchecked} without a drift check — the file predates the fingerprint stamp)` : ''}`);
+  if (r.reset.length > 0) {
+    log(`  ${COLOR.yellow}reset to Pending${COLOR.reset} — procedure changed since the result was recorded (${r.reset.length}): ${list(r.reset)}; the previous result is kept in Note`);
+  }
+  if (r.notPlaced.length > 0) {
+    log(`  ${COLOR.yellow}not carried${COLOR.reset} — no matching manual case in the feature any more (${r.notPlaced.length}): ${list(r.notPlaced.map((n) => `${n.ref} was ${n.result}`))}`);
+  }
+  if (r.duplicates.length > 0) {
+    log(`  ${COLOR.yellow}not carried${COLOR.reset} — a second row for the same case; only the first was kept (${r.duplicates.length}): ${list(r.duplicates.map((n) => `${n.ref} was ${n.result}`))}`);
+  }
+}
+
 /**
  * One place that accounts for every target the run did NOT write, so a sweep is
  * never silently partial: scaffolds skipped by preflight and units whose gates /
@@ -934,12 +959,9 @@ export function registerDeliveryCommand(program: Command): void {
         // Deliverables are COMMITTED files; delivery is the last stop before a
         // hardcoded credential lands in one. Same scan `generate` runs.
         const scanDirs = [...new Set(toExport.map((t) => qaDir(cwd, t)))];
-        const secretHits = scanDirs.flatMap((d) => scanTestDataSecrets(d));
-        if (secretHits.length) {
-          log(`\n⚠️  Possible secret(s) in committed test-data (review — do NOT commit real credentials):`);
-          for (const h of secretHits.slice(0, 10)) log(`   ${h.file}:${h.line} — ${h.reason}`);
-          log(`   Move real secrets to an env overlay / CI secret; keep test-data placeholders only.\n`);
-        }
+        const secretScan = scanDirs.map((d) => scanTestDataSecrets(d))
+          .reduce<SecretScanResult>((a, r) => ({ hits: [...a.hits, ...r.hits], unscanned: [...a.unscanned, ...r.unscanned] }), { hits: [], unscanned: [] });
+        for (const line of formatSecretScan(secretScan)) log(line);
 
         // 3. Export
         const legacy = options.legacy || options.full;

package/src/cli/commands/generate.ts

@@ -3,7 +3,7 @@ import * as path from 'path';
 import * as fs from 'fs';
 import { CodeGenerator } from '../../generators/test-generator/code-generator';
 import { adapterRegistry } from '../../generators/test-generator/adapters';
-import { scanTestDataSecrets } from '../../harness/secret-scan';
+import { scanTestDataSecrets, formatSecretScan, type SecretScanResult } from '../../harness/secret-scan';
 import { capabilityRegistry } from '../../capabilities/registry';
 import { discoverAndRegisterCapabilities } from '../../capabilities/discover';
 import { readCapabilities, writeCapabilities, driverMeta, loadDriverCatalog } from '../../harness/capability';
@@ -160,6 +160,17 @@ export function registerGenerateCommand(program: Command): void {
           const cap = readCapabilities(cwd);
           if (cap.platform) {
             platform = cap.platform;
+          } else if (cap.source === 'unreadable') {
+            // The file EXISTS and we failed to parse it. Scaffolding the web default here would
+            // overwrite whatever the user declared — a mobile project's platform, drivers and
+            // verification scope, gone, while the notice claimed the file was missing. Refuse:
+            // the one thing we know is that we do not know what this project is.
+            throw new Error(
+              `qa/capabilities.yaml exists but could not be parsed — fix the YAML and re-run.\n` +
+              `   Refusing to scaffold a default over it: that would discard the platform, drivers ` +
+              `and verification scope it declares.\n` +
+              `   To compile without reading it, pass --framework <web|mobile|…>.`,
+            );
           } else {
             platform = 'web';
             writeCapabilities(cwd, { platform: 'web', enabled: ['web'] });
@@ -225,12 +236,9 @@ export function registerGenerateCommand(program: Command): void {
             if (fs.existsSync(d)) for (const n of fs.readdirSync(d)) scanDirs.push(path.join(d, n));
           }
         }
-        const secretHits = scanDirs.flatMap((d) => scanTestDataSecrets(d));
-        if (secretHits.length) {
-          console.log(`\n⚠️  Possible secret(s) in committed test-data (review — do NOT commit real credentials):`);
-          for (const h of secretHits.slice(0, 10)) console.log(`   ${h.file}:${h.line} — ${h.reason}`);
-          console.log(`   Move real secrets to an env overlay / CI secret; keep test-data placeholders only.`);
-        }
+        const secretScan = scanDirs.map((d) => scanTestDataSecrets(d))
+          .reduce<SecretScanResult>((a, r) => ({ hits: [...a.hits, ...r.hits], unscanned: [...a.unscanned, ...r.unscanned] }), { hits: [], unscanned: [] });
+        for (const line of formatSecretScan(secretScan)) console.log(line);
 
         // Advisory harness sensors (e.g. @cases/@query lint) — run via the Capability SPI,
         // never block generation. Each capability registers its own; the kernel just runs them.

package/src/cli/commands/init.ts

@@ -13,6 +13,7 @@ export function registerInitCommand(program: Command): void {
     .option('--ios-bundle-id <id>', 'iOS bundle id for mobile (e.g. com.example.app.dev) — default app when MOBILE_PLATFORM=ios|both. Used with --mobile')
     .option('--ios-device <name>', "iOS Simulator device name for mobile (default: 'iPhone 16'). Used with --mobile")
     .option('--ios-version <ver>', "iOS Simulator platform version for mobile (default: '18.0'). Used with --mobile")
+    .option('--skip-env-setup', 'Mobile: emit appium-environment/ (JDK, Android SDK, Xcode CLT, env vars, Appium drivers) but do not run it now — re-run later: ./appium-environment/setup.sh (Windows: setup.ps1). Used with --mobile')
     .option(
       '--assistant <name>',
       'AI assistant to install for: claude | copilot | codex | all (repeatable). Default: claude',
@@ -30,6 +31,7 @@ export function registerInitCommand(program: Command): void {
       iosBundleId?: string;
       iosDevice?: string;
       iosVersion?: string;
+      skipEnvSetup?: boolean;
       assistant?: string[];
       force?: boolean;
     }) => {
@@ -55,6 +57,7 @@ export function registerInitCommand(program: Command): void {
           iosBundleId: options.iosBundleId,
           iosDevice: options.iosDevice,
           iosVersion: options.iosVersion,
+          skipEnvSetup: options.skipEnvSetup,
         });
         await initializer.initialize(projectName);
       } catch (error) {

package/src/cli/commands/results-merge.ts

@@ -13,6 +13,7 @@ import { detectReportRoot, sanitizeReportPaths } from '../../exporters/report-pa
 import { registerResultsSanitizeCommand } from './results-sanitize';
 import { resolveResultsPath } from '../../exporters/playwright-report-parser';
 import { parseSpecFile } from '../../exporters/spec-parser';
+import { writeFileAtomic } from '../../harness/write-atomic';
 
 interface MergeCliOptions {
   out?: string;
@@ -125,14 +126,7 @@ export function runResultsMerge(baseArg: string | undefined, newArg: string | un
   // that file is the single source of execution truth for delivery/dashboard.
   // (Same-dir rename = same device; concurrent merges are last-rename-wins.)
   const outFile = opts.out ?? baseFile;
-  const tmp = `${outFile}.tmp-${process.pid}`;
-  try {
-    fs.writeFileSync(tmp, JSON.stringify(merged, null, 2));
-    fs.renameSync(tmp, outFile);
-  } catch (err) {
-    try { fs.rmSync(tmp, { force: true }); } catch { /* best-effort cleanup */ }
-    throw err;
-  }
+  writeFileAtomic(outFile, JSON.stringify(merged, null, 2));
 
   console.log(`✓ merged ${path.basename(newFile)} into ${path.relative(cwd, outFile)} — ${replaced.length} updated, ${added.length} added, ${kept.length} kept`);
   return outFile;

package/src/cli/commands/results-sanitize.ts

@@ -16,6 +16,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import fg from 'fast-glob';
 import { detectReportRoot, sanitizeReportPaths } from '../../exporters/report-path-sanitizer';
+import { writeFileAtomic } from '../../harness/write-atomic';
 
 /** Where a project keeps the JSON files that carry paths. */
 export const DEFAULT_REPORT_GLOBS = [
@@ -50,15 +51,7 @@ export function runResultsSanitize(files: string[] | undefined, cwd: string = pr
     const root = detectReportRoot(doc) ?? nearestProjectRoot(path.dirname(file)) ?? cwd;
     const { doc: clean, rewritten } = sanitizeReportPaths(doc, { root });
     if (rewritten > 0) {
-      // Atomic write, same as `results merge`: a crash mid-write must never leave a truncated report.
-      const tmp = `${file}.tmp-${process.pid}`;
-      try {
-        fs.writeFileSync(tmp, JSON.stringify(clean, null, 2) + (raw.endsWith('\n') ? '\n' : ''));
-        fs.renameSync(tmp, file);
-      } catch (err) {
-        try { fs.rmSync(tmp, { force: true }); } catch { /* best-effort cleanup */ }
-        throw err;
-      }
+      writeFileAtomic(file, JSON.stringify(clean, null, 2) + (raw.endsWith('\n') ? '\n' : ''));
     }
     out.push({ file: path.relative(cwd, file), rewritten });
   }

package/src/cli/commands/setup-mobile-env.ts

@@ -0,0 +1,64 @@
+import { Command } from 'commander';
+
+/**
+ * `sungen setup-mobile-env` — provision this machine for Appium, in a project that already exists.
+ *
+ * `sungen init --mobile` runs the same bundle, but only the person who created the project ever runs
+ * init. The second QA clones a ready-made repo and had no command to reach for: `capability add
+ * mobile` re-records a capability that is already recorded, and knowing to run
+ * `./appium-environment/setup.sh` by hand assumes they know the folder exists. This is that command.
+ *
+ * Emits `appium-environment/` when it is missing — a project initialised before the bundle shipped,
+ * or one where the folder was deleted — then runs it. Both halves are idempotent, so running it on a
+ * fully provisioned machine reports a wall of skips and changes nothing.
+ */
+export function registerSetupMobileEnvCommand(program: Command): void {
+  program
+    .command('setup-mobile-env')
+    .description('Install the Appium environment on THIS machine (JDK, Android SDK, env vars, Xcode CLT, Appium drivers) for an existing mobile project — idempotent, safe to re-run')
+    .option('--check', 'Report what is missing and install nothing')
+    .option('--skip-android', 'Skip the JDK / Android SDK / uiautomator2 steps')
+    .option('--skip-ios', 'Skip the Xcode CLT / applesimutils / xcuitest steps (macOS only)')
+    .option('--no-profile', 'Do not write ANDROID_HOME / JAVA_HOME / PATH to your shell profile')
+    .option('--emit-only', 'Write appium-environment/ into the project but do not run it')
+    .action((o: { check?: boolean; skipAndroid?: boolean; skipIos?: boolean; profile?: boolean; emitOnly?: boolean }) => {
+      try {
+        const cwd = process.cwd();
+        const {
+          emitAppiumEnvironment,
+          runAppiumEnvironmentSetup,
+          appiumEnvironmentRerunCommand,
+        } = require('../../orchestrator/appium-environment-setup');
+
+        // Idempotent per file, so an edited script (a bumped cmdline-tools build, a local hint)
+        // survives. A project that already has the folder just sees the skip line.
+        const emitted = emitAppiumEnvironment(cwd);
+        if (emitted.created.length > 0) {
+          console.log(`✓ created  appium-environment/ (${emitted.created.length} files)`);
+        } else {
+          console.log('– skipped  appium-environment/ (already present)');
+        }
+
+        if (o.emitOnly) {
+          console.log(`\nRun it when you are ready: ${appiumEnvironmentRerunCommand()}`);
+          return;
+        }
+
+        // commander maps `--no-profile` to `profile: false`, so the flag is absent when profile is
+        // anything but an explicit false.
+        const flags: string[] = [];
+        if (o.check) flags.push('--check');
+        if (o.skipAndroid) flags.push('--skip-android');
+        if (o.skipIos) flags.push('--skip-ios');
+        if (o.profile === false) flags.push('--no-profile');
+
+        const outcome = runAppiumEnvironmentSetup(cwd, { flags });
+        // The bundle already printed its own per-step report and summary; exit non-zero so CI and a
+        // `&&` chain can act on a machine that is not ready.
+        if (outcome === 'failed') process.exitCode = 1;
+      } catch (error) {
+        console.error('❌ setup-mobile-env failed:', error);
+        process.exit(1);
+      }
+    });
+}

package/src/cli/index.ts

@@ -9,6 +9,7 @@ import { registerInitCommand } from './commands/init';
 import { registerAddCommand } from './commands/add';
 import { registerGenerateCommand } from './commands/generate';
 import { registerMakeauthCommand } from './commands/makeauth';
+import { registerSetupMobileEnvCommand } from './commands/setup-mobile-env';
 import { registerUpdateCommand } from './commands/update';
 import { registerDeliveryCommand } from './commands/delivery';
 import { registerFigmaCommand } from './commands/figma';
@@ -61,6 +62,7 @@ async function main() {
   registerAddCommand(program);
   registerGenerateCommand(program);
   registerMakeauthCommand(program);
+registerSetupMobileEnvCommand(program);
   registerUpdateCommand(program);
   registerDeliveryCommand(program);
   registerFigmaCommand(program);

package/src/dashboard/snapshot-builder.ts

@@ -29,6 +29,7 @@ import { resolvePlatformAppId } from '../exporters/mobile-app-id';
 import { discoverLocaleVariants, LocaleVariant } from '../exporters/locale-variants';
 import { getPackageVersion } from '../exporters/package-info';
 import { ApiCatalogEntry, EnvironmentInfo } from '../exporters/types';
+import { readCapabilities } from '../harness/capability';
 import {
   AggregateSummary,
   DashboardSnapshot,
@@ -98,14 +99,11 @@ export function buildDashboardSnapshot(options: BuildSnapshotOptions): Dashboard
  * Mirrors `isMobileProject` in src/cli/commands/delivery.ts.
  */
 function isMobileProject(cwd: string): boolean {
-  try {
-    const p = path.join(cwd, 'qa', 'capabilities.yaml');
-    if (!fs.existsSync(p)) return false;
-    const parsed = parseYaml(fs.readFileSync(p, 'utf-8')) as { platform?: string } | null;
-    return parsed?.platform === 'mobile';
-  } catch {
-    return false;
-  }
+  // Reads through `readCapabilities` rather than re-parsing the file: the third copy of this parse
+  // was the third place a malformed capabilities.yaml quietly read as "web". The shared reader
+  // reports the breakage once per process; here it still degrades to web, which is the safe
+  // direction (per-OS delivery is skipped, nothing is deleted).
+  return readCapabilities(cwd).platform === 'mobile';
 }
 
 function buildOneScreen(