expo-harmony-toolkit 1.7.2 → 1.8.0

package/build/core/constants.d.ts

@@ -1,6 +1,6 @@
 export declare const TOOLKIT_PACKAGE_NAME = "expo-harmony-toolkit";
 export declare const CLI_NAME = "expo-harmony";
-export declare const TOOLKIT_VERSION = "1.7.2";
+export declare const TOOLKIT_VERSION = "1.8.0";
 export declare const TEMPLATE_VERSION = "rnoh-0.82.18";
 export declare const RNOH_VERSION = "0.82.18";
 export declare const RNOH_CLI_VERSION = "0.82.18";
@@ -8,6 +8,7 @@ export declare const SUPPORTED_EXPO_SDKS: number[];
 export declare const GENERATED_DIR = ".expo-harmony";
 export declare const GENERATED_SHIMS_DIR = ".expo-harmony/shims";
 export declare const SIGNING_LOCAL_FILENAME = "signing.local.json";
+export declare const SIGNING_LOCAL_EXAMPLE_FILENAME = "signing.local.example.json";
 export declare const MANIFEST_FILENAME = "manifest.json";
 export declare const DOCTOR_REPORT_FILENAME = "doctor-report.json";
 export declare const ENV_REPORT_FILENAME = "env-report.json";

package/build/core/constants.js

@@ -1,9 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DESIRED_PACKAGE_SCRIPTS = exports.HARMONY_RUNTIME_PRELUDE_RELATIVE_PATH = exports.HARMONY_ROUTER_ENTRY_FILENAME = exports.STRICT_ENV_EXIT_CODE = exports.STRICT_DOCTOR_EXIT_CODE = exports.DEFAULT_HVIGOR_PLUGIN_FILENAME = exports.PREBUILD_METADATA_FILENAME = exports.TOOLKIT_CONFIG_FILENAME = exports.BUILD_REPORT_FILENAME = exports.ENV_REPORT_FILENAME = exports.DOCTOR_REPORT_FILENAME = exports.MANIFEST_FILENAME = exports.SIGNING_LOCAL_FILENAME = exports.GENERATED_SHIMS_DIR = exports.GENERATED_DIR = exports.SUPPORTED_EXPO_SDKS = exports.RNOH_CLI_VERSION = exports.RNOH_VERSION = exports.TEMPLATE_VERSION = exports.TOOLKIT_VERSION = exports.CLI_NAME = exports.TOOLKIT_PACKAGE_NAME = void 0;
+exports.DESIRED_PACKAGE_SCRIPTS = exports.HARMONY_RUNTIME_PRELUDE_RELATIVE_PATH = exports.HARMONY_ROUTER_ENTRY_FILENAME = exports.STRICT_ENV_EXIT_CODE = exports.STRICT_DOCTOR_EXIT_CODE = exports.DEFAULT_HVIGOR_PLUGIN_FILENAME = exports.PREBUILD_METADATA_FILENAME = exports.TOOLKIT_CONFIG_FILENAME = exports.BUILD_REPORT_FILENAME = exports.ENV_REPORT_FILENAME = exports.DOCTOR_REPORT_FILENAME = exports.MANIFEST_FILENAME = exports.SIGNING_LOCAL_EXAMPLE_FILENAME = exports.SIGNING_LOCAL_FILENAME = exports.GENERATED_SHIMS_DIR = exports.GENERATED_DIR = exports.SUPPORTED_EXPO_SDKS = exports.RNOH_CLI_VERSION = exports.RNOH_VERSION = exports.TEMPLATE_VERSION = exports.TOOLKIT_VERSION = exports.CLI_NAME = exports.TOOLKIT_PACKAGE_NAME = void 0;
 exports.TOOLKIT_PACKAGE_NAME = 'expo-harmony-toolkit';
 exports.CLI_NAME = 'expo-harmony';
-exports.TOOLKIT_VERSION = '1.7.2';
+exports.TOOLKIT_VERSION = '1.8.0';
 exports.TEMPLATE_VERSION = 'rnoh-0.82.18';
 exports.RNOH_VERSION = '0.82.18';
 exports.RNOH_CLI_VERSION = '0.82.18';
@@ -11,6 +11,7 @@ exports.SUPPORTED_EXPO_SDKS = [53, 55];
 exports.GENERATED_DIR = '.expo-harmony';
 exports.GENERATED_SHIMS_DIR = `${exports.GENERATED_DIR}/shims`;
 exports.SIGNING_LOCAL_FILENAME = 'signing.local.json';
+exports.SIGNING_LOCAL_EXAMPLE_FILENAME = 'signing.local.example.json';
 exports.MANIFEST_FILENAME = 'manifest.json';
 exports.DOCTOR_REPORT_FILENAME = 'doctor-report.json';
 exports.ENV_REPORT_FILENAME = 'env-report.json';

package/build/core/dependencyInspection.d.ts

@@ -0,0 +1,2 @@
+import { DetectedDependency } from '../types';
+export declare function annotateDependencyBuildability(projectRoot: string, dependencies: DetectedDependency[]): Promise<DetectedDependency[]>;

package/build/core/dependencyInspection.js

@@ -0,0 +1,130 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.annotateDependencyBuildability = annotateDependencyBuildability;
+const node_module_1 = require("node:module");
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const path_1 = __importDefault(require("path"));
+const NATIVE_DIRECTORY_CANDIDATES = ['android', 'ios', 'harmony'];
+const NATIVE_CONFIG_CANDIDATES = [
+    'oh-package.json5',
+    'react-native.config.js',
+    'react-native.config.cjs',
+    'react-native.config.mjs',
+    'react-native.config.ts',
+    'expo-module.config.json',
+    'expo-module.config.js',
+    'expo-module.config.cjs',
+    'expo-module.config.mjs',
+    'expo-module.config.ts',
+];
+const PACKAGE_JSON_NATIVE_HINT_KEYS = [
+    'codegenConfig',
+    'expo-module',
+    'harmony',
+    'nativePackageName',
+    'podspecPath',
+    'react-native',
+    'react-native-builder-bob',
+];
+const PACKAGE_NAME_NATIVE_PATTERNS = [
+    /^expo(?:-|$)/,
+    /^@expo\//,
+    /^react-native(?:-|$)/,
+    /^@react-native\//,
+    /^@react-native-community\//,
+];
+async function annotateDependencyBuildability(projectRoot, dependencies) {
+    return Promise.all(dependencies.map(async (dependency) => ({
+        ...dependency,
+        buildabilityRisk: await resolveDependencyBuildabilityRisk(projectRoot, dependency),
+    })));
+}
+async function resolveDependencyBuildabilityRisk(projectRoot, dependency) {
+    if (dependency.status !== 'unknown') {
+        return 'known';
+    }
+    const packageJsonPath = resolveInstalledDependencyPackageJson(projectRoot, dependency.name, dependency.version);
+    if (!packageJsonPath || !(await fs_extra_1.default.pathExists(packageJsonPath))) {
+        return 'unresolved';
+    }
+    const packageRoot = path_1.default.dirname(packageJsonPath);
+    const dependencyPackageJson = (await fs_extra_1.default.readJson(packageJsonPath));
+    if (looksLikeNativeDependencyByPackageName(dependency.name)) {
+        return 'native-risk';
+    }
+    if (await hasNativeSurface(packageRoot, dependencyPackageJson)) {
+        return 'native-risk';
+    }
+    return 'js-only-unknown';
+}
+function resolveInstalledDependencyPackageJson(projectRoot, dependencyName, dependencyVersion) {
+    const localPackageJsonPath = resolveLocalDependencyPackageJson(projectRoot, dependencyVersion);
+    if (localPackageJsonPath) {
+        return localPackageJsonPath;
+    }
+    try {
+        const projectRequire = (0, node_module_1.createRequire)(path_1.default.join(projectRoot, 'package.json'));
+        return projectRequire.resolve(`${dependencyName}/package.json`);
+    }
+    catch {
+        return null;
+    }
+}
+function resolveLocalDependencyPackageJson(projectRoot, dependencyVersion) {
+    const trimmedVersion = dependencyVersion.trim();
+    for (const prefix of ['file:', 'link:', 'portal:']) {
+        if (!trimmedVersion.startsWith(prefix)) {
+            continue;
+        }
+        const relativeTarget = trimmedVersion.slice(prefix.length).trim();
+        if (!relativeTarget) {
+            return null;
+        }
+        return path_1.default.resolve(projectRoot, relativeTarget, 'package.json');
+    }
+    return null;
+}
+function looksLikeNativeDependencyByPackageName(dependencyName) {
+    return PACKAGE_NAME_NATIVE_PATTERNS.some((pattern) => pattern.test(dependencyName));
+}
+async function hasNativeSurface(packageRoot, dependencyPackageJson) {
+    for (const directoryName of NATIVE_DIRECTORY_CANDIDATES) {
+        if (await fs_extra_1.default.pathExists(path_1.default.join(packageRoot, directoryName))) {
+            return true;
+        }
+    }
+    for (const fileName of NATIVE_CONFIG_CANDIDATES) {
+        if (await fs_extra_1.default.pathExists(path_1.default.join(packageRoot, fileName))) {
+            return true;
+        }
+    }
+    if (await hasPodspecFile(packageRoot)) {
+        return true;
+    }
+    if (PACKAGE_JSON_NATIVE_HINT_KEYS.some((key) => dependencyPackageJson[key] !== undefined)) {
+        return true;
+    }
+    const files = Array.isArray(dependencyPackageJson.files)
+        ? dependencyPackageJson.files.filter((entry) => typeof entry === 'string')
+        : [];
+    if (files.some((entry) => hasNativePathHint(entry))) {
+        return true;
+    }
+    const keywords = Array.isArray(dependencyPackageJson.keywords)
+        ? dependencyPackageJson.keywords.filter((entry) => typeof entry === 'string')
+        : [];
+    if (keywords.some((keyword) => keyword === 'react-native' || keyword === 'expo-module')) {
+        return true;
+    }
+    return false;
+}
+async function hasPodspecFile(packageRoot) {
+    const entries = await fs_extra_1.default.readdir(packageRoot);
+    return entries.some((entry) => entry.endsWith('.podspec'));
+}
+function hasNativePathHint(value) {
+    return /(^|\/)(android|ios|harmony)(\/|$)/.test(value) || value.endsWith('.podspec');
+}

package/build/core/env.js

@@ -95,7 +95,7 @@ async function buildEnvReport(projectRoot, options = {}) {
     else if (!signingConfigured) {
         advisories.push({
             code: 'env.signing.missing',
-            message: 'Neither .expo-harmony/signing.local.json nor harmony/build-profile.json5 declares usable signingConfigs yet. Debug GUI flows may still work, but release builds require signing.',
+            message: 'Neither .expo-harmony/signing.local.json nor harmony/build-profile.json5 declares usable signingConfigs yet. Copy .expo-harmony/signing.local.example.json to signing.local.json and fill your real release credentials before running release builds.',
         });
     }
     return {

package/build/core/report.js

@@ -10,6 +10,7 @@ const fs_extra_1 = __importDefault(require("fs-extra"));
 const path_1 = __importDefault(require("path"));
 const semver_1 = __importDefault(require("semver"));
 const constants_1 = require("./constants");
+const dependencyInspection_1 = require("./dependencyInspection");
 const dependencyCatalog_1 = require("../data/dependencyCatalog");
 const validatedMatrices_1 = require("../data/validatedMatrices");
 const capabilities_1 = require("../data/capabilities");
@@ -22,6 +23,8 @@ const DEFAULT_RECORD = {
     supportTier: 'unsupported',
     note: 'This dependency is not in the current compatibility catalog yet.',
 };
+const BARE_WORKFLOW_DIRECTORY_NAMES = ['android', 'ios'];
+const BARE_WORKFLOW_DEPENDENCIES = new Set(['expo-build-properties', 'expo-dev-client']);
 async function buildDoctorReport(projectRoot, options = {}) {
     const loadedProject = await (0, project_1.loadProject)(projectRoot);
     const expoSdkVersion = (0, project_1.detectExpoSdkVersion)(loadedProject.packageJson);
@@ -39,7 +42,7 @@ async function buildDoctorReport(projectRoot, options = {}) {
             dependencyRecords.set(pluginName, createDependencyRecord(pluginName, 'configured', 'expo-plugin'));
         }
     }
-    const dependencies = [...dependencyRecords.values()].sort((left, right) => left.name.localeCompare(right.name));
+    const dependencies = await (0, dependencyInspection_1.annotateDependencyBuildability)(loadedProject.projectRoot, [...dependencyRecords.values()].sort((left, right) => left.name.localeCompare(right.name)));
     const blockingIssues = await collectBlockingIssues(loadedProject.projectRoot, loadedProject.expoConfig, loadedProject.packageJson, expoPlugins, expoSchemes, expoSdkVersion, dependencies, matrix, targetTier);
     const capabilities = (0, capabilities_1.getCapabilityDefinitionsForProject)(loadedProject.packageJson).map((definition) => ({
         id: definition.id,
@@ -48,6 +51,7 @@ async function buildDoctorReport(projectRoot, options = {}) {
         supportTier: definition.supportTier,
         runtimeMode: definition.runtimeMode,
         evidence: { ...definition.evidence },
+        evidenceSource: { ...definition.evidenceSource },
         note: definition.note,
         docsUrl: definition.docsUrl,
         nativePackageNames: [...definition.nativePackageNames],
@@ -55,13 +59,22 @@ async function buildDoctorReport(projectRoot, options = {}) {
         sampleRoute: definition.sampleRoute,
         acceptanceChecklist: [...definition.acceptanceChecklist],
     }));
+    const coverageProfile = await detectCoverageProfile(loadedProject.projectRoot, loadedProject.packageJson, dependencies);
     const blockingDependencyNames = new Set(blockingIssues
         .filter((issue) => issue.code.startsWith('dependency.') && issue.subject)
         .map((issue) => issue.subject));
     const resolvedDependencies = dependencies.map((dependency) => ({
         ...dependency,
+        gapCategory: resolveDependencyGapCategory(dependency, coverageProfile),
         blocking: blockingDependencyNames.has(dependency.name),
     }));
+    const nextActions = buildNextActions({
+        targetTier,
+        coverageProfile,
+        blockingIssues,
+        dependencies: resolvedDependencies,
+        capabilities,
+    });
     const warnings = buildWarnings(loadedProject.expoConfig, expoSdkVersion, resolvedDependencies);
     const advisories = buildAdvisories(loadedProject.expoConfig);
     return {
@@ -76,6 +89,7 @@ async function buildDoctorReport(projectRoot, options = {}) {
         rnohCliVersion: constants_1.RNOH_CLI_VERSION,
         expoSdkVersion,
         targetTier,
+        coverageProfile,
         expoConfig: {
             name: loadedProject.expoConfig.name ?? null,
             slug: loadedProject.expoConfig.slug ?? null,
@@ -100,6 +114,7 @@ async function buildDoctorReport(projectRoot, options = {}) {
         },
         capabilities,
         blockingIssues,
+        nextActions,
         advisories,
         warnings,
     };
@@ -118,6 +133,7 @@ function renderDoctorReport(report) {
         `Expo SDK: ${report.expoSdkVersion ?? 'unknown'} (recognized ${constants_1.SUPPORTED_EXPO_SDKS.join(', ')})`,
         `Matrix: ${report.matrixId ?? 'none'}`,
         `Target tier: ${report.targetTier}`,
+        `Coverage profile: ${report.coverageProfile}`,
         `Eligibility: ${report.eligibility}`,
         `Schemes: ${report.expoConfig.schemes.join(', ') || 'none'}`,
         `Plugins: ${report.expoConfig.plugins.join(', ') || 'none'}`,
@@ -129,7 +145,7 @@ function renderDoctorReport(report) {
         ...report.dependencies.map((dependency) => {
             const replacement = dependency.replacement ? ` | replacement: ${dependency.replacement}` : '';
             const blocking = dependency.blocking ? ' | blocking: yes' : '';
-            return `- [${dependency.status}/${dependency.supportTier}] ${dependency.name}@${dependency.version} (${dependency.source}) - ${dependency.note}${replacement}${blocking}`;
+            return `- [${dependency.status}/${dependency.supportTier}] ${dependency.name}@${dependency.version} (${dependency.source}) - ${dependency.note} | buildability: ${renderDependencyBuildabilityRisk(dependency.buildabilityRisk)} | gap: ${dependency.gapCategory}${replacement}${blocking}`;
         }),
     ];
     if (report.capabilities.length > 0) {
@@ -138,7 +154,7 @@ function renderDoctorReport(report) {
                 ? ` | permissions: ${capability.harmonyPermissions.join(', ')}`
                 : '';
             const missingEvidence = getMissingCapabilityEvidence(capability.evidence);
-            const evidence = ` | evidence: ${renderCapabilityEvidence(capability.evidence)}`;
+            const evidence = ` | evidence: ${renderCapabilityEvidence(capability.evidence, capability.evidenceSource)}`;
             const promotionGaps = buildCapabilityPromotionGaps(capability.runtimeMode, missingEvidence);
             const gapSuffix = promotionGaps.length > 0
                 ? ` | verified gaps: ${promotionGaps.join(', ')}`
@@ -149,6 +165,9 @@ function renderDoctorReport(report) {
     if (report.blockingIssues.length > 0) {
         sections.push('', 'Blocking issues:', ...report.blockingIssues.map((issue) => `- ${issue.code}: ${issue.message}${issue.subject ? ` (${issue.subject})` : ''}`));
     }
+    if (report.nextActions.length > 0) {
+        sections.push('', 'Next actions:', ...report.nextActions.map((action, index) => `${index + 1}. ${action}`));
+    }
     if (report.advisories.length > 0) {
         sections.push('', 'Advisories:', ...report.advisories.map((advisory) => `- ${advisory}`));
     }
@@ -157,12 +176,12 @@ function renderDoctorReport(report) {
     }
     return sections.join('\n');
 }
-function renderCapabilityEvidence(evidence) {
+function renderCapabilityEvidence(evidence, evidenceSource) {
     return [
-        `bundle=${evidence.bundle ? 'yes' : 'no'}`,
-        `debugBuild=${evidence.debugBuild ? 'yes' : 'no'}`,
-        `device=${evidence.device ? 'yes' : 'no'}`,
-        `release=${evidence.release ? 'yes' : 'no'}`,
+        `bundle=${evidence.bundle ? 'yes' : 'no'}[${evidenceSource.bundle}]`,
+        `debugBuild=${evidence.debugBuild ? 'yes' : 'no'}[${evidenceSource.debugBuild}]`,
+        `device=${evidence.device ? 'yes' : 'no'}[${evidenceSource.device}]`,
+        `release=${evidence.release ? 'yes' : 'no'}[${evidenceSource.release}]`,
     ].join(', ');
 }
 function getMissingCapabilityEvidence(evidence) {
@@ -185,6 +204,8 @@ function createDependencyRecord(name, version, source) {
         source,
         status: matrixRecord.status,
         supportTier: matrixRecord.supportTier,
+        buildabilityRisk: 'known',
+        gapCategory: 'matrix-drift',
         blocking: false,
         note: matrixRecord.note,
         replacement: matrixRecord.replacement,
@@ -332,6 +353,114 @@ async function collectBlockingIssues(projectRoot, expoConfig, packageJson, expoP
     }
     return dedupeIssues(issues);
 }
+async function detectCoverageProfile(projectRoot, packageJson, dependencies) {
+    for (const directoryName of BARE_WORKFLOW_DIRECTORY_NAMES) {
+        if (await fs_extra_1.default.pathExists(path_1.default.join(projectRoot, directoryName))) {
+            return 'bare';
+        }
+    }
+    if (dependencies.some((dependency) => isThirdPartyNativeGapDependency(dependency))) {
+        return 'third-party-native-heavy';
+    }
+    if ((0, capabilities_1.getCapabilityDefinitionsForProject)(packageJson).length > 0 ||
+        dependencies.some((dependency) => isOfficialExpoDependencyName(dependency.name) && dependency.supportTier !== 'verified')) {
+        return 'managed-native-heavy';
+    }
+    return 'managed-core';
+}
+function resolveDependencyGapCategory(dependency, coverageProfile) {
+    if (coverageProfile === 'bare' &&
+        (BARE_WORKFLOW_DEPENDENCIES.has(dependency.name) ||
+            dependency.name === 'expo' ||
+            dependency.name === 'react-native')) {
+        return 'bare-workflow-gap';
+    }
+    if (isOfficialExpoDependencyName(dependency.name) || capabilities_1.CAPABILITY_BY_PACKAGE[dependency.name]) {
+        return dependency.supportTier === 'verified' && dependency.status === 'supported'
+            ? 'matrix-drift'
+            : 'official-module-gap';
+    }
+    if (isThirdPartyNativeGapDependency(dependency)) {
+        return 'third-party-native-gap';
+    }
+    if (coverageProfile === 'bare') {
+        return 'bare-workflow-gap';
+    }
+    return 'matrix-drift';
+}
+function isOfficialExpoDependencyName(dependencyName) {
+    return dependencyName === 'expo' || dependencyName.startsWith('expo-') || dependencyName.startsWith('@expo/');
+}
+function isThirdPartyNativeGapDependency(dependency) {
+    if (dependency.name === 'react-native-gesture-handler' ||
+        dependency.name === '@react-native-oh-tpl/react-native-gesture-handler') {
+        return true;
+    }
+    if (dependency.buildabilityRisk === 'native-risk') {
+        return true;
+    }
+    return (dependency.supportTier !== 'verified' &&
+        !isOfficialExpoDependencyName(dependency.name) &&
+        dependency.name.startsWith('react-native'));
+}
+function buildNextActions(input) {
+    const actions = [];
+    const { targetTier, coverageProfile, blockingIssues, dependencies, capabilities } = input;
+    const hasPreviewCapabilities = capabilities.some((capability) => capability.supportTier === 'preview');
+    const hasRouterBlockingIssues = blockingIssues.some((issue) => [
+        'dependency.router_peer_missing',
+        'config.router_plugin.missing',
+        'config.scheme.missing',
+        'config.bundle_script.mismatch',
+    ].includes(issue.code));
+    if (hasBlockingIssueCode(blockingIssues, 'matrix.expo_sdk.unsupported') ||
+        hasBlockingIssueCode(blockingIssues, 'dependency.version_mismatch') ||
+        hasBlockingIssueCode(blockingIssues, 'dependency.specifier_mismatch') ||
+        hasBlockingIssueCode(blockingIssues, 'dependency.required_missing')) {
+        actions.push(`Align Expo SDK, React Native, RNOH, and validated adapter versions to ${validatedMatrices_1.DEFAULT_VALIDATED_MATRIX_ID}, then rerun \`expo-harmony doctor --project-root . --strict\`.`);
+    }
+    if (targetTier === 'verified' && hasPreviewCapabilities) {
+        actions.push('Use `expo-harmony doctor --project-root . --target-tier preview` to measure the current preview-capability baseline while keeping `latest` pinned to verified-only releases.');
+    }
+    if (hasPreviewCapabilities) {
+        actions.push('Keep combined sample smoke for regression coverage, but track bundle/debug/device/release evidence separately for each preview capability before promotion.');
+    }
+    switch (coverageProfile) {
+        case 'managed-core':
+            actions.push('Stay on the verified lane: rerun `expo-harmony sync-template --project-root .`, `expo-harmony bundle --project-root .`, and `expo-harmony build-hap --project-root . --mode debug` before claiming release readiness.');
+            break;
+        case 'managed-native-heavy':
+            actions.push('After every native-capability change, rerun `expo-harmony sync-template --project-root .`, `expo-harmony bundle --project-root .`, and `expo-harmony build-hap --project-root . --mode debug` to keep the managed sidecar and preview evidence aligned.');
+            break;
+        case 'bare':
+            actions.push('Keep this project on the bare workflow track for now: preserve the native directories, use `expo-harmony doctor --project-root .` for classification, and only claim verified support after bare workflow support lands in the mainline capability catalog.');
+            break;
+        case 'third-party-native-heavy':
+            actions.push('Isolate third-party native packages and onboard them through the mainline capability catalog one by one; start with `react-native-gesture-handler` if it is present, and treat unknown native surfaces as explicit unblockers rather than matrix drift.');
+            break;
+    }
+    if (hasRouterBlockingIssues) {
+        actions.push('Add the missing expo-router peers/plugin/scheme or update the Harmony bundle script to use `expo-harmony bundle`, then rerun doctor before trusting router builds.');
+    }
+    if (blockingIssues.some((issue) => issue.code === 'dependency.not_allowed' &&
+        (issue.subject === 'react-native-gesture-handler' ||
+            issue.subject === '@react-native-oh-tpl/react-native-gesture-handler'))) {
+        actions.push('Keep `react-native-gesture-handler` out of the verified lane until its Harmony adapter path has stable doctor, sample, and build coverage.');
+    }
+    if (hasBlockingIssueCode(blockingIssues, 'config.native_identifier.missing')) {
+        actions.push('Set `android.package` or `ios.bundleIdentifier` in Expo config before expecting a strict Harmony build path.');
+    }
+    if (dependencies.some((dependency) => dependency.buildabilityRisk === 'native-risk')) {
+        actions.push('Inspect unknown native-looking dependencies and either replace them, gate them behind preview work, or onboard them explicitly before promising Harmony portability.');
+    }
+    if (dependencies.some((dependency) => dependency.buildabilityRisk === 'js-only-unknown')) {
+        actions.push('Unknown JavaScript-only packages still sit outside the public matrix; verify bundling manually, but prioritize native gaps first.');
+    }
+    return dedupeStrings(actions);
+}
+function hasBlockingIssueCode(issues, code) {
+    return issues.some((issue) => issue.code === code);
+}
 function buildWarnings(expoConfig, expoSdkVersion, dependencies) {
     const warnings = [];
     const expoSdkWarning = (0, project_1.getExpoSdkWarning)(expoSdkVersion);
@@ -350,8 +479,14 @@ function buildWarnings(expoConfig, expoSdkVersion, dependencies) {
     if (dependencies.some((dependency) => dependency.supportTier === 'experimental')) {
         warnings.push('Experimental-tier dependencies were detected. Expect bridge drift, runtime gaps, or additional manual validation before claiming release readiness.');
     }
-    if (dependencies.some((dependency) => dependency.status === 'unknown')) {
-        warnings.push('Unknown dependencies were detected. The toolkit can scaffold the project, but runtime portability is not guaranteed.');
+    if (dependencies.some((dependency) => dependency.buildabilityRisk === 'js-only-unknown')) {
+        warnings.push('Some unknown dependencies look JavaScript-only. They remain outside the public matrix, but they are less likely to block bundling or a debug HAP build outright.');
+    }
+    if (dependencies.some((dependency) => dependency.buildabilityRisk === 'native-risk')) {
+        warnings.push('Some unknown dependencies appear to carry native surfaces. Treat them as real Harmony portability risks until they are explicitly onboarded.');
+    }
+    if (dependencies.some((dependency) => dependency.buildabilityRisk === 'unresolved')) {
+        warnings.push('Some unknown dependencies could not be inspected because their installed package metadata was unavailable. Install dependencies before treating the doctor report as a buildability signal.');
     }
     return warnings;
 }
@@ -384,6 +519,20 @@ function matchesVersionRange(rawVersion, range) {
 function matchesDependencySpecifier(rawSpecifier, expectedSpecifier) {
     return rawSpecifier.trim() === expectedSpecifier.trim();
 }
+function renderDependencyBuildabilityRisk(buildabilityRisk) {
+    switch (buildabilityRisk) {
+        case 'known':
+            return 'known';
+        case 'js-only-unknown':
+            return 'unknown-js';
+        case 'native-risk':
+            return 'unknown-native';
+        case 'unresolved':
+            return 'unresolved';
+        default:
+            return buildabilityRisk;
+    }
+}
 function dedupeIssues(issues) {
     const seen = new Set();
     return issues.filter((issue) => {
@@ -395,3 +544,6 @@ function dedupeIssues(issues) {
         return true;
     });
 }
+function dedupeStrings(values) {
+    return [...new Set(values)];
+}

package/build/core/signing.d.ts

@@ -4,8 +4,10 @@ type SigningLocalAppFragment = {
     products?: JsonRecord[];
 };
 export declare function getSigningLocalPath(projectRoot: string): string;
+export declare function getSigningLocalExamplePath(projectRoot: string): string;
 export declare function readSigningLocalConfig(projectRoot: string): Promise<SigningLocalAppFragment | null>;
 export declare function mergeSigningLocalConfigIntoBuildProfile(rawBuildProfileContents: string, signingLocalConfig: SigningLocalAppFragment | null): string;
 export declare function hasSigningConfiguration(rawBuildProfileContents: string | null, signingLocalConfig?: SigningLocalAppFragment | null): boolean;
 export declare function hasSigningLocalConfiguration(signingLocalConfig: SigningLocalAppFragment | null): boolean;
+export declare function renderSigningLocalExampleConfig(): string;
 export {};

package/build/core/signing.js

@@ -4,10 +4,12 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getSigningLocalPath = getSigningLocalPath;
+exports.getSigningLocalExamplePath = getSigningLocalExamplePath;
 exports.readSigningLocalConfig = readSigningLocalConfig;
 exports.mergeSigningLocalConfigIntoBuildProfile = mergeSigningLocalConfigIntoBuildProfile;
 exports.hasSigningConfiguration = hasSigningConfiguration;
 exports.hasSigningLocalConfiguration = hasSigningLocalConfiguration;
+exports.renderSigningLocalExampleConfig = renderSigningLocalExampleConfig;
 const fs_extra_1 = __importDefault(require("fs-extra"));
 const json5_1 = __importDefault(require("json5"));
 const path_1 = __importDefault(require("path"));
@@ -15,6 +17,9 @@ const constants_1 = require("./constants");
 function getSigningLocalPath(projectRoot) {
     return path_1.default.join(projectRoot, constants_1.GENERATED_DIR, constants_1.SIGNING_LOCAL_FILENAME);
 }
+function getSigningLocalExamplePath(projectRoot) {
+    return path_1.default.join(projectRoot, constants_1.GENERATED_DIR, constants_1.SIGNING_LOCAL_EXAMPLE_FILENAME);
+}
 async function readSigningLocalConfig(projectRoot) {
     const signingLocalPath = getSigningLocalPath(projectRoot);
     if (!(await fs_extra_1.default.pathExists(signingLocalPath))) {
@@ -49,6 +54,31 @@ function hasSigningConfiguration(rawBuildProfileContents, signingLocalConfig = n
 function hasSigningLocalConfiguration(signingLocalConfig) {
     return hasNonEmptySigningConfigList(signingLocalConfig?.signingConfigs);
 }
+function renderSigningLocalExampleConfig() {
+    return (JSON.stringify({
+        signingConfigs: [
+            {
+                name: 'default',
+                type: 'HarmonyOS',
+                material: {
+                    storeFile: './signing/release.p12',
+                    storePassword: '<replace-with-store-password>',
+                    keyAlias: '<replace-with-key-alias>',
+                    keyPassword: '<replace-with-key-password>',
+                    signAlg: 'SHA256withECDSA',
+                    profile: './signing/release.p7b',
+                    certpath: './signing/release.cer',
+                },
+            },
+        ],
+        products: [
+            {
+                name: 'default',
+                signingConfig: 'default',
+            },
+        ],
+    }, null, 2) + '\n');
+}
 function normalizeSigningLocalConfig(rawConfig) {
     const candidate = rawConfig && typeof rawConfig === 'object' && !Array.isArray(rawConfig)
         ? 'app' in rawConfig &&

package/build/core/template/capabilityRegistry.d.ts

@@ -0,0 +1,9 @@
+import { CapabilityDefinition } from '../../types';
+type ManagedExpoHarmonyModuleRenderer = {
+    filename: string;
+    render: () => string;
+};
+export declare const MANAGED_EXPO_HARMONY_MODULE_RENDERERS: readonly ManagedExpoHarmonyModuleRenderer[];
+export declare function renderCapabilityModuleShim(capability: CapabilityDefinition): string;
+export declare function renderUnsupportedCapabilityShim(capability: CapabilityDefinition): string;
+export {};

package/build/core/template/capabilityRegistry.js

@@ -0,0 +1,84 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MANAGED_EXPO_HARMONY_MODULE_RENDERERS = void 0;
+exports.renderCapabilityModuleShim = renderCapabilityModuleShim;
+exports.renderUnsupportedCapabilityShim = renderUnsupportedCapabilityShim;
+const camera_1 = require("./renderers/camera");
+const fileSystem_1 = require("./renderers/fileSystem");
+const imagePicker_1 = require("./renderers/imagePicker");
+const location_1 = require("./renderers/location");
+const CAPABILITY_SHIM_RENDERERS = {
+    'expo-file-system': {
+        adapter: fileSystem_1.renderExpoFileSystemHarmonyAdapterShim,
+        preview: fileSystem_1.renderExpoFileSystemPreviewShim,
+    },
+    'expo-image-picker': {
+        adapter: imagePicker_1.renderExpoImagePickerHarmonyAdapterShim,
+        preview: imagePicker_1.renderExpoImagePickerPreviewShim,
+    },
+    'expo-location': {
+        adapter: location_1.renderExpoLocationHarmonyAdapterShim,
+        preview: location_1.renderExpoLocationPreviewShim,
+    },
+    'expo-camera': {
+        adapter: camera_1.renderExpoCameraHarmonyAdapterShim,
+        preview: camera_1.renderExpoCameraPreviewShim,
+    },
+};
+exports.MANAGED_EXPO_HARMONY_MODULE_RENDERERS = [
+    {
+        filename: 'ExpoHarmonyFileSystemTurboModule.ts',
+        render: fileSystem_1.renderExpoHarmonyFileSystemTurboModule,
+    },
+    {
+        filename: 'ExpoHarmonyImagePickerTurboModule.ts',
+        render: imagePicker_1.renderExpoHarmonyImagePickerTurboModule,
+    },
+    {
+        filename: 'ExpoHarmonyLocationTurboModule.ts',
+        render: location_1.renderExpoHarmonyLocationTurboModule,
+    },
+    {
+        filename: 'ExpoHarmonyCameraTurboModule.ts',
+        render: camera_1.renderExpoHarmonyCameraTurboModule,
+    },
+];
+function renderCapabilityModuleShim(capability) {
+    const renderer = CAPABILITY_SHIM_RENDERERS[capability.packageName];
+    if (!renderer) {
+        return renderUnsupportedCapabilityShim(capability);
+    }
+    return capability.runtimeMode !== 'shim'
+        ? renderer.adapter(capability)
+        : renderer.preview(capability);
+}
+function renderUnsupportedCapabilityShim(capability) {
+    return `'use strict';
+
+const { CodedError } = require('expo-modules-core');
+
+function createPreviewError() {
+  return new CodedError(
+    'ERR_EXPO_HARMONY_PREVIEW',
+    '${capability.packageName} is classified as ${capability.supportTier} for Harmony, but no managed runtime shim has been wired yet.',
+  );
+}
+
+function unavailable() {
+  throw createPreviewError();
+}
+
+module.exports = new Proxy(
+  {},
+  {
+    get(_target, propertyName) {
+      if (propertyName === '__esModule') {
+        return true;
+      }
+
+      return unavailable;
+    },
+  },
+);
+`;
+}

package/build/core/template/expoModulesCoreShim.d.ts

@@ -0,0 +1,2 @@
+import { HarmonyIdentifiers } from '../../types';
+export declare function renderExpoModulesCoreHarmonyShim(expoConfig: Record<string, any>, identifiers: HarmonyIdentifiers): string;