@auraindustry/aurajs 0.1.3 → 0.1.5

package/src/cli.mjs

@@ -28,15 +28,24 @@ import {
   MAKE_SUPPORTED_KINDS_HELP_TEXT,
   MAKE_USAGE,
   PREFAB_ROLE_OPTION_LIST,
+  VENDOR_USAGE,
   cmdCheck,
   cmdCreate,
   cmdExplain,
   cmdFrom,
   cmdInit,
   cmdMake,
+  cmdVendor,
 } from './commands/project-authoring.mjs';
+import { PACKS_USAGE, cmdPacks } from './commands/packs.mjs';
 import { packageAssets } from './asset-pack.mjs';
-import { writeBuildManifest, writeWebBuildArtifacts } from './build-contract.mjs';
+import {
+  buildRuntimeConfig,
+  readProjectCapabilityDeclaration,
+  writeBuildManifest,
+  writeCanonicalJsonFile,
+  writeWebBuildArtifacts,
+} from './build-contract.mjs';
 import { discoverProjectIconPath, SUPPORTED_BUILD_ICON_EXTENSIONS } from './icon-discovery.mjs';
 import { runPublishCommand } from './publish-command.mjs';
 import { runExternalAssetsCommand } from './self-hosted-assets.mjs';
@@ -55,6 +64,10 @@ import {
 } from './headless-action.mjs';
 import { loadConfig, ConfigError } from './config.mjs';
 import { ensureHostBinaryAvailable, HostBinaryResolutionError } from './host-binary.mjs';
+import { buildAndroidArtifacts, stageAndroidProject } from './mobile/android/build.mjs';
+import { produceAndroidHostArtifact } from './mobile/android/host-artifact.mjs';
+import { buildIosArtifacts, stageIosProject } from './mobile/ios/build.mjs';
+import { produceIosHostArtifact } from './mobile/ios/host-artifact.mjs';
 import { runConformanceCommand } from './conformance-runner.mjs';
 import { buildRuntimeInspectorSnapshotReport } from './conformance.mjs';
 import {
@@ -113,6 +126,16 @@ import {
   writeSessionRegistry,
 } from './session-client.mjs';
 import { GAME_ACTION_REQUEST_SCHEMA_VERSION } from './game-action-runtime.mjs';
+import {
+  captureHeadlessEvidenceBundle,
+  EvidenceBundleError,
+  serializeEvidenceManifest,
+} from './evidence-bundle.mjs';
+import {
+  ReplayError,
+  runHeadlessReplay,
+  serializeReplayReport,
+} from './replay-runtime.mjs';
 
 // ---------------------------------------------------------------------------
 // Version
@@ -192,6 +215,35 @@ const COMMANDS = {
       '    - This is an authoring command on `aura`, not a generated game-wrapper verb.',
     ],
   },
+  vendor: {
+    description: 'Vendor supported helper files into the current AuraJS project',
+    usage: VENDOR_USAGE,
+    details: [
+      '  Notes:',
+      '    - `aura vendor helpers` seeds the packaged starter helper copies into src/starter-utils/.',
+      '    - Re-run with `--force` to overwrite local helper files and resync them to the packaged version.',
+      '    - Use `--json` when you want machine-readable created/overwritten/skipped file lists.',
+    ],
+  },
+  packs: {
+    description: 'List and register optional AuraJS packs and bundles',
+    usage: PACKS_USAGE,
+    details: [
+      '  Subcommands:',
+      '    list [--json]                           List known optional packs and bundles',
+      '    show <id> [--json]                     Show one pack or bundle entry',
+      '    add <id> [--source package|workspace] [--install]     Register one pack or bundle in the current AuraJS project',
+      '    vendor <id> [--source auto|workspace|installed|github] [--ref <git-ref>] [--force]     Copy pack payloads into the project',
+      '',
+      '  Notes:',
+      '    - `aura packs add` writes optional package dependencies plus aura.packs.json metadata.',
+      '    - `--workspace` uses local file: specs that point at pack packages in the AuraJS source checkout.',
+      '    - `aura packs vendor` is the editable-content lane: it copies pack payloads into project-local folders such as content/, docs/, or assets/.',
+      '    - `--source github` on vendor fetches the pack archive from its registered GitHub repo/ref and vendors from that payload.',
+      '    - `--install` runs `npm install` after package.json and aura.packs.json are updated.',
+      '    - Bundles expand to their member packs so AI/project introspection can see the concrete installed lanes.',
+    ],
+  },
   explain: {
     description: 'Explain how the current AuraJS project is wired',
     usage: 'aura explain [--json]',
@@ -233,15 +285,17 @@ const COMMANDS = {
   },
   build: {
     description: 'Build release artifacts (native or web)',
-    usage: 'aura build [--target <windows|mac|linux|all|web|gb|gbc|gba>] [--asset-mode <embed|sibling>]',
+    usage: 'aura build [--target <windows|mac|linux|all|web|android|ios|mobile|gb|gbc|gba>] [--asset-mode <embed|sibling>]',
     details: [
       '  Options:',
-      '    --target <windows|mac|linux|all|web|gb|gbc|gba>  Build target',
+      '    --target <windows|mac|linux|all|web|android|ios|mobile|gb|gbc|gba>  Build target',
       '    --asset-mode <embed|sibling>      Package assets in pak or sibling assets/',
       '',
       '  Notes:',
       '    - `--target web` emits browser artifacts under `build/web` for the current browser-backed subset.',
       '    - Native targets are current host only in v1.',
+      '    - `--target android|ios|mobile` produces host artifacts, stages mobile package roots, and runs Gradle/Xcode export when prerequisites are present; otherwise manifests stay reason-coded and staged.',
+      '    - Mobile targets require `--asset-mode embed` in v1.',
       '    - `--target all` keeps current host output; use CI matrix for all platforms.',
       '    - Browser runtime truth today: current 2D/input/assets/storage path is supported; `aura.state` and `aura.net` remain reason-coded unsupported.',
       '    - `--target gb|gbc|gba` routes through the Aura Retro lane under `src/cli/src/retro` and writes cartridge-oriented artifacts under `build/<target>`.',
@@ -280,10 +334,14 @@ const COMMANDS = {
   },
   publish: {
     description: 'Publish the current game package through npm',
-    usage: 'aura publish [--dry-run] [npm publish options]',
+    usage: 'aura publish [--dry-run] [--name <package>] [--version <semver>] [--yes] [npm publish options]',
     details: [
       '  Notes:',
       '    - `aura publish` is the canonical npm-first publish lane for game projects.',
+      '    - Interactive terminals can keep or update package.json name/version before publish.',
+      '    - `--name <package>` sets the package name before validation and publish.',
+      '    - `--version <semver>` sets the package version before validation and publish.',
+      '    - `--yes` skips the prompt and uses current package metadata.',
       '    - Scoped package names default to `--access public` unless explicitly overridden.',
       '    - npm publish lifecycle recursion is skipped cleanly instead of re-entering the command.',
       '    - For oversized payloads, generate self-hosted metadata with `aura external-assets generate` after you upload assets to your own HTTPS host.',
@@ -315,6 +373,49 @@ const COMMANDS = {
   },
   clean: { description: 'Delete build artifacts', usage: 'aura clean' },
   test: { description: 'Run game logic in headless mode', usage: 'aura test [file] [--width N] [--height N] [--frames N]' },
+  evidence: {
+    description: 'Capture one headless evidence bundle for the current authored project',
+    usage: 'aura evidence [file] [--replay <replay.json>] [--frames N] [--width N] [--height N] [--out-dir <path>] [--output <path|->]',
+    details: [
+      '  Options:',
+      '    --replay <replay.json>        Execute one deterministic replay before capture and include replay artifacts',
+      '    --frames <N>                  Number of lifecycle frames to execute before capture (or after replay when --replay is set)',
+      '    --width <N>                   Override headless viewport width',
+      '    --height <N>                  Override headless viewport height',
+      '    --out-dir <path>              Directory for manifest.json, summary.json, state.json, inspect.json, perf.json, and optional replay artifacts',
+      '    --output <path|->             Write the manifest JSON to file (or "-" for stdout)',
+      '    --compact                     Compact manifest JSON output (single line)',
+      '    --pretty                      Pretty manifest JSON output (default)',
+      '    --file <path>                 Override entry file (default: build.entry from config)',
+      '',
+      '  Notes:',
+      '    - This is headless-first and currently captures one combined evidence bundle per run.',
+      '    - The bundle writes manifest.json, summary.json, state.json, inspect.json, and perf.json under --out-dir.',
+      '    - When --replay is set, the bundle also writes replay.json and replay-report.json.',
+    ],
+  },
+  replay: {
+    description: 'Run one deterministic headless replay against the current authored project',
+    usage: 'aura replay run <replay.json> [--output <path|->] [--state-output <path|->] [--file <path>] [--width N] [--height N] [--compact]',
+    details: [
+      '  Subcommands:',
+      '    run <replay.json>             Execute one headless replay payload with deterministic input injection',
+      '',
+      '  Options:',
+      '    run:',
+      '      --output <path|->             Write replay report JSON to file (or "-" for stdout)',
+      '      --state-output <path|->       Write final canonical state payload to file (or "-" for stdout)',
+      '      --file <path>                 Override entry file (default: build.entry from config)',
+      '      --width <N>                   Override headless viewport width',
+      '      --height <N>                  Override headless viewport height',
+      '      --compact                     Compact JSON output (single line)',
+      '      --pretty                      Pretty JSON output (default)',
+      '',
+      '  Notes:',
+      '    - Replay is headless-first today and uses deterministic input injection plus optional fingerprint checkpoints.',
+      '    - Use `expectFingerprint` checkpoints inside the replay payload to stop on divergence.',
+    ],
+  },
   conformance: { description: 'Run API conformance suites in headless mode', usage: 'aura conformance [--mode shim|native|both] [--json]' },
   state: {
     description: 'Export, diff, and patch canonical game-state snapshots',
@@ -518,7 +619,16 @@ if (HAS_AURAPM_PREVIEW) {
   };
 }
 
-const SUPPORTED_BUILD_TARGETS = new Set(['windows', 'mac', 'linux', 'all', 'web', ...SUPPORTED_RETRO_BUILD_TARGETS]);
+const SUPPORTED_MOBILE_BUILD_TARGETS = new Set(['android', 'ios', 'mobile']);
+const SUPPORTED_BUILD_TARGETS = new Set([
+  'windows',
+  'mac',
+  'linux',
+  'all',
+  'web',
+  ...SUPPORTED_MOBILE_BUILD_TARGETS,
+  ...SUPPORTED_RETRO_BUILD_TARGETS,
+]);
 const SUPPORTED_STATE_EXPORT_MODES = new Set(['headless', 'native', 'shim']);
 const STATE_MUTATION_AUDIT_SCHEMA_VERSION = 'aurajs.state-mutation-audit.v1';
 const WEB_DEV_REFRESH_SIGNAL_SCHEMA = 'aurajs.web-dev-refresh.v1';
@@ -557,6 +667,7 @@ function printHelp() {
     '    create       Scaffold a new game project',
     '    from         Convert a supported foreign project into a new AuraJS project',
     '    make         Generate authored project files from templates',
+    '    vendor       Vendor supported helper files into the current project',
     '    explain      Explain how the current project is wired',
     '    check        Validate authored project wiring',
     '    play         Start the game with a live dev session',
@@ -636,6 +747,10 @@ function currentPlatformTarget() {
   return 'linux';
 }
 
+function isMobileBuildTarget(target) {
+  return SUPPORTED_MOBILE_BUILD_TARGETS.has(target);
+}
+
 function parseAssetMode(args) {
   for (let i = 0; i < args.length; i += 1) {
     if (args[i] === '--asset-mode' && args[i + 1]) {
@@ -772,6 +887,260 @@ function parseStateExportArgs(args) {
   return parsed;
 }
 
+function parseEvidenceArgs(args) {
+  const parsed = {
+    file: null,
+    replayPath: null,
+    frames: 1,
+    width: null,
+    height: null,
+    outDir: resolve(process.cwd(), '.aura/evidence/latest'),
+    outputPath: null,
+    compact: false,
+  };
+
+  let positionalFileSeen = false;
+  let formattingFlag = 'pretty';
+  let framesSpecified = false;
+
+  for (let i = 0; i < args.length; i += 1) {
+    const token = args[i];
+
+    if (token === '--frames') {
+      const value = readRequiredOptionValueWithReasonCode(args, i, '--frames', 'invalid_evidence_args');
+      parsed.frames = parseNonNegativeIntegerArg(value, '--frames', 'invalid_evidence_args');
+      framesSpecified = true;
+      i += 1;
+      continue;
+    }
+    if (token.startsWith('--frames=')) {
+      parsed.frames = parseNonNegativeIntegerArg(token.slice('--frames='.length), '--frames', 'invalid_evidence_args');
+      framesSpecified = true;
+      continue;
+    }
+
+    if (token === '--replay') {
+      const value = readRequiredOptionValueWithReasonCode(args, i, '--replay', 'invalid_evidence_args');
+      parsed.replayPath = normalizeStateCommandInputPath(value, 'replay', 'invalid_evidence_args');
+      i += 1;
+      continue;
+    }
+    if (token.startsWith('--replay=')) {
+      parsed.replayPath = normalizeStateCommandInputPath(token.slice('--replay='.length), 'replay', 'invalid_evidence_args');
+      continue;
+    }
+
+    if (token === '--width') {
+      const value = readRequiredOptionValueWithReasonCode(args, i, '--width', 'invalid_evidence_args');
+      parsed.width = parsePositiveIntegerArg(value, '--width', 'invalid_evidence_args');
+      i += 1;
+      continue;
+    }
+    if (token.startsWith('--width=')) {
+      parsed.width = parsePositiveIntegerArg(token.slice('--width='.length), '--width', 'invalid_evidence_args');
+      continue;
+    }
+
+    if (token === '--height') {
+      const value = readRequiredOptionValueWithReasonCode(args, i, '--height', 'invalid_evidence_args');
+      parsed.height = parsePositiveIntegerArg(value, '--height', 'invalid_evidence_args');
+      i += 1;
+      continue;
+    }
+    if (token.startsWith('--height=')) {
+      parsed.height = parsePositiveIntegerArg(token.slice('--height='.length), '--height', 'invalid_evidence_args');
+      continue;
+    }
+
+    if (token === '--out-dir') {
+      const value = readRequiredOptionValueWithReasonCode(args, i, '--out-dir', 'invalid_evidence_args');
+      parsed.outDir = resolve(process.cwd(), value);
+      i += 1;
+      continue;
+    }
+    if (token.startsWith('--out-dir=')) {
+      parsed.outDir = resolve(process.cwd(), token.slice('--out-dir='.length));
+      continue;
+    }
+
+    if (token === '--output' || token === '--out') {
+      const value = readRequiredOptionValueWithReasonCode(args, i, token, 'invalid_evidence_args');
+      parsed.outputPath = normalizeStateExportOutput(value);
+      i += 1;
+      continue;
+    }
+    if (token.startsWith('--output=')) {
+      parsed.outputPath = normalizeStateExportOutput(token.slice('--output='.length));
+      continue;
+    }
+    if (token.startsWith('--out=')) {
+      parsed.outputPath = normalizeStateExportOutput(token.slice('--out='.length));
+      continue;
+    }
+
+    if (token === '--compact') {
+      if (formattingFlag === 'pretty') {
+        parsed.compact = true;
+        formattingFlag = 'compact';
+        continue;
+      }
+      if (formattingFlag === 'compact') {
+        continue;
+      }
+      throw new StateExportError('invalid_evidence_args', 'Cannot use --compact and --pretty together.');
+    }
+    if (token === '--pretty') {
+      if (formattingFlag === 'compact') {
+        throw new StateExportError('invalid_evidence_args', 'Cannot use --compact and --pretty together.');
+      }
+      parsed.compact = false;
+      formattingFlag = 'pretty';
+      continue;
+    }
+
+    if (token === '--file') {
+      const value = readRequiredOptionValueWithReasonCode(args, i, '--file', 'invalid_evidence_args');
+      parsed.file = normalizeStateExportFile(value);
+      i += 1;
+      continue;
+    }
+    if (token.startsWith('--file=')) {
+      parsed.file = normalizeStateExportFile(token.slice('--file='.length));
+      continue;
+    }
+
+    if (token.startsWith('--')) {
+      throw new StateExportError('invalid_evidence_args', `Unknown evidence option: ${token}`);
+    }
+
+    if (positionalFileSeen) {
+      throw new StateExportError('invalid_evidence_args', `Unexpected argument: ${token}`);
+    }
+    positionalFileSeen = true;
+    parsed.file = normalizeStateExportFile(token);
+  }
+
+  if (parsed.replayPath && framesSpecified !== true) {
+    parsed.frames = 0;
+  }
+
+  return parsed;
+}
+
+function parseReplayRunArgs(args) {
+  const parsed = {
+    replayPath: null,
+    file: null,
+    width: null,
+    height: null,
+    outputPath: null,
+    stateOutputPath: null,
+    compact: false,
+  };
+
+  let formattingFlag = 'pretty';
+
+  for (let i = 0; i < args.length; i += 1) {
+    const token = args[i];
+
+    if (token === '--output' || token === '--out') {
+      const value = readRequiredOptionValueWithReasonCode(args, i, token, 'invalid_replay_args');
+      parsed.outputPath = normalizeStateExportOutput(value);
+      i += 1;
+      continue;
+    }
+    if (token.startsWith('--output=')) {
+      parsed.outputPath = normalizeStateExportOutput(token.slice('--output='.length));
+      continue;
+    }
+    if (token.startsWith('--out=')) {
+      parsed.outputPath = normalizeStateExportOutput(token.slice('--out='.length));
+      continue;
+    }
+
+    if (token === '--state-output') {
+      const value = readRequiredOptionValueWithReasonCode(args, i, '--state-output', 'invalid_replay_args');
+      parsed.stateOutputPath = normalizeStateExportOutput(value);
+      i += 1;
+      continue;
+    }
+    if (token.startsWith('--state-output=')) {
+      parsed.stateOutputPath = normalizeStateExportOutput(token.slice('--state-output='.length));
+      continue;
+    }
+
+    if (token === '--file') {
+      const value = readRequiredOptionValueWithReasonCode(args, i, '--file', 'invalid_replay_args');
+      parsed.file = normalizeStateExportFile(value);
+      i += 1;
+      continue;
+    }
+    if (token.startsWith('--file=')) {
+      parsed.file = normalizeStateExportFile(token.slice('--file='.length));
+      continue;
+    }
+
+    if (token === '--width') {
+      const value = readRequiredOptionValueWithReasonCode(args, i, '--width', 'invalid_replay_args');
+      parsed.width = parsePositiveIntegerArg(value, '--width', 'invalid_replay_args');
+      i += 1;
+      continue;
+    }
+    if (token.startsWith('--width=')) {
+      parsed.width = parsePositiveIntegerArg(token.slice('--width='.length), '--width', 'invalid_replay_args');
+      continue;
+    }
+
+    if (token === '--height') {
+      const value = readRequiredOptionValueWithReasonCode(args, i, '--height', 'invalid_replay_args');
+      parsed.height = parsePositiveIntegerArg(value, '--height', 'invalid_replay_args');
+      i += 1;
+      continue;
+    }
+    if (token.startsWith('--height=')) {
+      parsed.height = parsePositiveIntegerArg(token.slice('--height='.length), '--height', 'invalid_replay_args');
+      continue;
+    }
+
+    if (token === '--compact') {
+      if (formattingFlag === 'pretty') {
+        parsed.compact = true;
+        formattingFlag = 'compact';
+        continue;
+      }
+      if (formattingFlag === 'compact') {
+        continue;
+      }
+      throw new StateExportError('invalid_replay_args', 'Cannot use --compact and --pretty together.');
+    }
+    if (token === '--pretty') {
+      if (formattingFlag === 'compact') {
+        throw new StateExportError('invalid_replay_args', 'Cannot use --compact and --pretty together.');
+      }
+      parsed.compact = false;
+      formattingFlag = 'pretty';
+      continue;
+    }
+
+    if (token.startsWith('--')) {
+      throw new StateExportError('invalid_replay_args', `Unknown replay option: ${token}`);
+    }
+
+    if (parsed.replayPath === null) {
+      parsed.replayPath = normalizeStateCommandInputPath(token, 'replay', 'invalid_replay_args');
+      continue;
+    }
+
+    throw new StateExportError('invalid_replay_args', `Unexpected argument: ${token}`);
+  }
+
+  if (!parsed.replayPath) {
+    throw new StateExportError('invalid_replay_args', 'Replay run requires a replay JSON path.');
+  }
+
+  return parsed;
+}
+
 function parseStateDiffArgs(args) {
   const parsed = {
     beforePath: null,
@@ -2757,10 +3126,7 @@ function parseDevArgs(args) {
 
 function normalizeDevTarget(value) {
   const normalized = String(value || '').trim().toLowerCase();
-  if (normalized === 'macos' || normalized === 'darwin' || normalized === 'mac') return 'mac';
-  if (normalized === 'win' || normalized === 'win32' || normalized === 'windows') return 'windows';
   if (normalized === 'browser' || normalized === 'web') return 'web';
-  if (normalized === 'linux') return 'linux';
   throw new StateExportError(
     'invalid_dev_args',
     `Unsupported dev target "${value}". Supported values: web.`,
@@ -3438,6 +3804,96 @@ function resolveBuildIdentity(config) {
   };
 }
 
+function sanitizeMobileIdentifierFragment(value, fallback = 'game') {
+  const normalized = String(value || '')
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '');
+  return normalized.length > 0 ? normalized : fallback;
+}
+
+function resolveAndroidBuildIdentity(identity) {
+  const slug = sanitizeExecutableBaseName(identity.executableBaseName || 'game').toLowerCase();
+  return {
+    name: identity.name,
+    slug,
+    applicationId: process.env.AURA_ANDROID_APPLICATION_ID
+      || `dev.aurajs.${sanitizeMobileIdentifierFragment(slug)}`,
+    versionCode: Number.parseInt(process.env.AURA_ANDROID_VERSION_CODE || '1', 10) || 1,
+    versionName: process.env.AURA_ANDROID_VERSION_NAME || identity.version,
+  };
+}
+
+function resolveIosBuildIdentity(identity) {
+  const slug = sanitizeExecutableBaseName(identity.executableBaseName || 'game').toLowerCase();
+  return {
+    appName: identity.name,
+    bundleId: process.env.AURA_IOS_BUNDLE_ID
+      || `com.aurajs.${sanitizeMobileIdentifierFragment(slug)}`,
+    version: identity.version,
+    buildNumber: process.env.AURA_IOS_BUILD_NUMBER || '1',
+  };
+}
+
+function buildMobileSourceArtifacts({
+  projectRoot,
+  outDir,
+  entryFile,
+  identity,
+  modules,
+  windowConfig,
+}) {
+  const sourceOutRoot = resolve(projectRoot, outDir, '.mobile-source');
+  const bundle = runBuildStage('bundle', () => bundleProject({
+    projectRoot,
+    mode: 'build',
+    entryFile,
+    outFile: resolve(sourceOutRoot, 'js/game.bundle.js'),
+  }));
+  const assets = runBuildStage('asset-pack', () => packageAssets({
+    projectRoot,
+    outRoot: sourceOutRoot,
+    mode: 'embed',
+  }));
+  const buildManifestPath = runBuildStage('build-contract', () => writeBuildManifest({
+    outRoot: sourceOutRoot,
+    bundlePath: bundle.outFile,
+    assetsManifestPath: assets.manifestPath,
+    executablePath: null,
+    assetMode: assets.mode,
+    identity: {
+      name: identity.name,
+      version: identity.version,
+      windowTitle: identity.name,
+      executableBaseName: identity.executableBaseName,
+      executableFileName: null,
+    },
+    icon: null,
+  }));
+  const runtimeConfigPath = runBuildStage('runtime-config', () => {
+    const capabilityDeclaration = readProjectCapabilityDeclaration({
+      projectRoot,
+      modules: modules || {},
+    });
+    const runtimeConfig = buildRuntimeConfig({
+      windowConfig: windowConfig || {},
+      modules: modules || {},
+      capabilityDeclaration,
+    });
+    const outPath = resolve(sourceOutRoot, 'runtime-config.json');
+    writeCanonicalJsonFile(outPath, runtimeConfig);
+    return outPath;
+  });
+
+  return {
+    outRoot: sourceOutRoot,
+    bundle,
+    assets,
+    buildManifestPath,
+    runtimeConfigPath,
+  };
+}
+
 function resolveBuildIcon({ projectRoot, targetOutRoot, iconPath, assetDir = 'assets' }) {
   const configuredPath = typeof iconPath === 'string' && iconPath.trim().length > 0
     ? iconPath.trim()
@@ -4221,7 +4677,7 @@ async function cmdDevNative(devArgs = {}) {
 
 async function cmdDev(args) {
   const parsed = parseDevArgs(args);
-  const target = parsed.target || parseTarget(args);
+  const target = parsed.target;
   if (target === 'web') {
     if (parsed.restoreKind || parsed.session !== null || parsed.sessionName || parsed.runtimeArgs.length > 0) {
       throw new StateExportError(
@@ -4238,7 +4694,7 @@ async function cmdDev(args) {
 async function cmdBuild(args, options = {}) {
   const target = parseTarget(args);
   if (target && !SUPPORTED_BUILD_TARGETS.has(target)) {
-    throw new Error(`Unsupported --target "${target}". Supported values: windows, mac, linux, all, web, gb, gbc, gba.`);
+    throw new Error(`Unsupported --target "${target}". Supported values: windows, mac, linux, all, web, android, ios, mobile, gb, gbc, gba.`);
   }
 
   const requestedTarget = target || currentPlatformTarget();
@@ -4247,6 +4703,8 @@ async function cmdBuild(args, options = {}) {
   const entryFile = options.entryFile || config.build.entry;
   const logOutput = options.log !== false;
   const identity = resolveBuildIdentity(config);
+  const cliAssetMode = parseAssetMode(args);
+  const selectedAssetMode = args.some((a) => a === '--asset-mode') ? cliAssetMode : config.build.assetMode;
   if (isRetroBuildTarget(requestedTarget)) {
     return buildRetroProject({
       projectRoot,
@@ -4304,6 +4762,136 @@ async function cmdBuild(args, options = {}) {
       loaderPath: webContract.loaderPath,
     };
   }
+  if (isMobileBuildTarget(requestedTarget)) {
+    if (selectedAssetMode !== 'embed') {
+      throw new Error('Mobile builds require `--asset-mode embed` in v1.');
+    }
+
+    const mobileSource = buildMobileSourceArtifacts({
+      projectRoot,
+      outDir: config.build.outDir,
+      entryFile,
+      identity,
+      modules: config.modules,
+      windowConfig: config.window,
+    });
+
+    const androidRequested = requestedTarget === 'android' || requestedTarget === 'mobile';
+    const iosRequested = requestedTarget === 'ios' || requestedTarget === 'mobile';
+
+    const androidHostArtifact = androidRequested
+      ? runBuildStage('android-host-artifact', () => produceAndroidHostArtifact({
+        sourceLibraryPath: process.env.AURA_ANDROID_NATIVE_HOST_LIBRARY || null,
+        env: process.env,
+      }))
+      : null;
+    const androidStage = androidRequested
+      ? runBuildStage('android-stage', () => stageAndroidProject({
+        projectRoot,
+        outRoot: resolve(projectRoot, config.build.outDir, 'android'),
+        bundlePath: mobileSource.bundle.outFile,
+        assetsPackPath: mobileSource.assets.packPath,
+        sourceBuildManifestPath: mobileSource.buildManifestPath,
+        runtimeConfigPath: mobileSource.runtimeConfigPath,
+        nativeHostLibraryPath: androidHostArtifact?.ok ? androidHostArtifact.distArtifactPath : null,
+        identity: resolveAndroidBuildIdentity(identity),
+      }))
+      : null;
+    const androidBuild = androidRequested
+      ? runBuildStage('android-build', () => buildAndroidArtifacts({
+        outRoot: androidStage.outRoot,
+        manifestPath: androidStage.manifestPath,
+        env: process.env,
+      }))
+      : null;
+    const iosHostArtifact = iosRequested
+      ? runBuildStage('ios-host-artifact', () => produceIosHostArtifact({
+        hostFrameworkPath: process.env.AURA_IOS_HOST_FRAMEWORK_PATH || null,
+        environment: process.env,
+      }))
+      : null;
+    const iosStage = iosRequested
+      ? runBuildStage('ios-stage', () => stageIosProject({
+        projectRoot,
+        outRoot: resolve(projectRoot, config.build.outDir, 'ios'),
+        sourceBuildRoot: mobileSource.outRoot,
+        buildManifestPath: mobileSource.buildManifestPath,
+        assetsManifestPath: mobileSource.assets.manifestPath,
+        bundlePath: mobileSource.bundle.outFile,
+        hostFrameworkPath: iosHostArtifact?.ok ? iosHostArtifact.artifactPath : null,
+        identity: resolveIosBuildIdentity(identity),
+      }))
+      : null;
+    const iosBuild = iosRequested
+      ? runBuildStage('ios-build', () => buildIosArtifacts({
+        outRoot: iosStage.outRoot,
+        manifestPath: iosStage.manifestPath,
+        environment: process.env,
+      }))
+      : null;
+
+    if (logOutput) {
+      console.log('\n  aura build: complete.');
+      console.log(`  Game: ${identity.name}`);
+      console.log(`  Version: ${identity.version}`);
+      console.log(`  Time: ${mobileSource.bundle.elapsedMs}ms`);
+      console.log(`  Assets: ${mobileSource.assets.assetCount} (${mobileSource.assets.mode})`);
+      console.log(
+        `  Asset updates: copied=${mobileSource.assets.incremental.copied} skipped=${mobileSource.assets.incremental.skipped} removed=${mobileSource.assets.incremental.removed}`,
+      );
+      console.log(`  Output target: ${requestedTarget}`);
+      if (androidStage) {
+        const androidToolchain = androidStage.toolchain.ready
+          ? 'ready'
+          : (androidStage.toolchain.reasonCodes.join(', ') || 'missing');
+        console.log(`  Android stage: ${resolve(projectRoot, config.build.outDir, 'android')}`);
+        console.log(`  Android host artifact: ${androidHostArtifact?.reasonCode || 'not_requested'}`);
+        console.log(`  Android toolchain: ${androidToolchain}`);
+        console.log(`  Android build: ${androidBuild?.reasonCode || 'not_run'}`);
+      }
+      if (iosStage) {
+        const iosToolchain = iosStage.toolchain.reasonCode;
+        console.log(`  iOS stage: ${resolve(projectRoot, config.build.outDir, 'ios')}`);
+        console.log(`  iOS host artifact: ${iosHostArtifact?.reasonCode || 'not_requested'}`);
+        console.log(`  iOS toolchain: ${iosToolchain}`);
+        console.log(`  iOS build: ${iosBuild?.reasonCode || 'not_run'}`);
+      }
+      console.log('  Note: mobile in v1 produces host artifacts, stages package roots, and runs Gradle/Xcode export when prerequisites are present; otherwise manifests stay reason-coded and staged.');
+      console.log('');
+    }
+
+    return {
+      projectRoot,
+      config,
+      requestedTarget,
+      platformTarget: currentPlatformTarget(),
+      effectiveTarget: requestedTarget,
+      targetKind: 'mobile',
+      targetOutRoot: resolve(projectRoot, config.build.outDir),
+      executablePath: null,
+      launchExecutablePath: null,
+      bundlePath: mobileSource.bundle.outFile,
+      assetsManifestPath: mobileSource.assets.manifestPath,
+      buildManifestPath: mobileSource.buildManifestPath,
+      assetMode: mobileSource.assets.mode,
+      identity,
+      icon: null,
+      androidBuildManifestPath: androidStage?.manifestPath || null,
+      iosBuildManifestPath: iosStage?.manifestPath || null,
+      mobileBuilds: {
+        android: androidRequested ? {
+          hostArtifact: androidHostArtifact,
+          stage: androidStage,
+          export: androidBuild,
+        } : null,
+        ios: iosRequested ? {
+          hostArtifact: iosHostArtifact,
+          stage: iosStage,
+          export: iosBuild,
+        } : null,
+      },
+    };
+  }
 
   const platformTarget = currentPlatformTarget();
   const effectiveTarget = platformTarget;
@@ -4311,8 +4899,7 @@ async function cmdBuild(args, options = {}) {
   const executableFileName = executableNameForPlatform(effectiveTarget, identity.executableBaseName);
 
   // CLI --asset-mode flag overrides config if provided.
-  const cliAssetMode = parseAssetMode(args);
-  const assetMode = args.some((a) => a === '--asset-mode') ? cliAssetMode : config.build.assetMode;
+  const assetMode = selectedAssetMode;
 
   const result = runBuildStage('bundle', () => bundleProject({
     projectRoot,
@@ -4700,6 +5287,9 @@ async function cmdRun(args) {
   if (built.targetKind === 'retro') {
     throw new Error('aura run does not support Aura Retro targets. Use `aura build --target <gb|gbc|gba>` and the generated preview/toolchain outputs instead.');
   }
+  if (built.targetKind === 'mobile') {
+    throw new Error('aura run does not support mobile package targets. Use `aura build --target android|ios|mobile` and continue with the staged mobile package lane.');
+  }
   if (built.effectiveTarget === 'web') {
     throw new Error('aura run does not support --target web. Serve build/web in a browser and use the web loader contract.');
   }
@@ -4901,6 +5491,74 @@ async function cmdTest(args) {
   console.log('');
 }
 
+async function cmdEvidence(args) {
+  const projectRoot = process.cwd();
+  const parsed = parseEvidenceArgs(args);
+  const config = await loadConfig({ projectRoot, mode: 'build' });
+  const replayPayload = parsed.replayPath
+    ? readJsonInputFile(parsed.replayPath, 'replay payload', 'replay_input')
+    : null;
+  const result = await captureHeadlessEvidenceBundle({
+    projectRoot,
+    file: parsed.file || config.build.entry,
+    frames: parsed.frames,
+    width: parsed.width ?? config.window.width,
+    height: parsed.height ?? config.window.height,
+    outDir: parsed.outDir,
+    replayPayload,
+  });
+
+  const manifestText = serializeEvidenceManifest(result.manifest, parsed.compact);
+  writeStateJsonOutput(parsed.outputPath, manifestText, 'evidence_output_write_failed');
+}
+
+async function cmdReplayRun(args) {
+  const projectRoot = process.cwd();
+  const parsed = parseReplayRunArgs(args);
+  const config = await loadConfig({ projectRoot, mode: 'build' });
+  const payload = readJsonInputFile(parsed.replayPath, 'replay payload', 'replay_input');
+  const result = await runHeadlessReplay({
+    projectRoot,
+    file: parsed.file || config.build.entry,
+    width: parsed.width ?? config.window.width,
+    height: parsed.height ?? config.window.height,
+    payload,
+  });
+
+  if (parsed.stateOutputPath !== null) {
+    writeStateJsonOutput(
+      parsed.stateOutputPath,
+      serializeCanonicalStatePayload(result.finalState, parsed.compact),
+      'replay_state_output_write_failed',
+    );
+  }
+  writeStateJsonOutput(
+    parsed.outputPath,
+    serializeReplayReport(result.report, parsed.compact),
+    'replay_output_write_failed',
+  );
+}
+
+async function cmdReplay(args) {
+  const subcommand = args[0];
+  if (!subcommand) {
+    throw new StateExportError(
+      'replay_subcommand_required',
+      'Missing replay subcommand. Usage: aura replay run <replay.json> [options]',
+    );
+  }
+
+  if (subcommand === 'run') {
+    await cmdReplayRun(args.slice(1));
+    return;
+  }
+
+  throw new StateExportError(
+    'replay_subcommand_unsupported',
+    `Unknown replay subcommand "${subcommand}". Supported subcommands: run.`,
+  );
+}
+
 async function runStateExportPayload(parsed) {
   const projectRoot = process.cwd();
   const config = await loadConfig({ projectRoot, mode: 'build' });
@@ -6257,6 +6915,8 @@ const HANDLERS = {
   create: (args) => cmdCreate(args, { error }),
   from: (args) => cmdFrom(args, { error }),
   make: (args) => cmdMake(args, { error }),
+  vendor: (args) => cmdVendor(args, { error }),
+  packs: (args) => cmdPacks(args, { error }),
   explain: (args) => cmdExplain(args, { error }),
   check: (args) => cmdCheck(args, { error }),
   dev: cmdDev,
@@ -6268,6 +6928,8 @@ const HANDLERS = {
   'external-assets': cmdExternalAssets,
   clean: cmdClean,
   test: cmdTest,
+  evidence: cmdEvidence,
+  replay: cmdReplay,
   conformance: cmdConformance,
   state: cmdState,
   inspect: cmdInspect,
@@ -6291,7 +6953,7 @@ async function main() {
     process.exit(0);
   }
 
-  if (argv.includes('--version') || argv.includes('-v')) {
+  if (argv[0] === '--version' || argv[0] === '-v') {
     console.log(VERSION);
     process.exit(0);
   }
@@ -6335,6 +6997,12 @@ async function main() {
     if (err instanceof StateArtifactError) {
       error(`${err.message} (reasonCode=${err.reasonCode})`, 6);
     }
+    if (err instanceof EvidenceBundleError) {
+      error(`${err.message} (reasonCode=${err.reasonCode})`, 6);
+    }
+    if (err instanceof ReplayError) {
+      error(`${err.message} (reasonCode=${err.reasonCode})`, 6);
+    }
     if (err instanceof HeadlessTestError) {
       if (Array.isArray(err.details?.failures) && err.details.failures.length > 0) {
         console.error('\n  aura test failures:');