expo-harmony-toolkit 1.5.0

package/build/core/env.js

@@ -0,0 +1,185 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildEnvReport = buildEnvReport;
+exports.renderEnvReport = renderEnvReport;
+exports.getStrictEnvExitCode = getStrictEnvExitCode;
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const path_1 = __importDefault(require("path"));
+const constants_1 = require("./constants");
+const project_1 = require("./project");
+const DEFAULT_DEVECO_STUDIO_CANDIDATES = [
+    '/Applications/DevEco-Studio.app',
+    path_1.default.join(process.env.HOME ?? '', 'Applications', 'DevEco-Studio.app'),
+];
+async function buildEnvReport(projectRoot, options = {}) {
+    const runtimeEnv = options.env ?? process.env;
+    const useDefaultLookups = runtimeEnv.EXPO_HARMONY_DISABLE_DEFAULT_PATHS !== '1';
+    const resolvedProjectRoot = await (0, project_1.resolveProjectRoot)(projectRoot);
+    await (0, project_1.ensureProjectPackageJsonPath)(resolvedProjectRoot);
+    const devecoStudioPath = await resolveExistingPath([
+        runtimeEnv.EXPO_HARMONY_DEVECO_STUDIO_PATH,
+        runtimeEnv.DEVECO_STUDIO_PATH,
+        runtimeEnv.DEVECO_STUDIO_HOME,
+        ...(useDefaultLookups ? DEFAULT_DEVECO_STUDIO_CANDIDATES : []),
+    ]);
+    const sdkRootCandidate = runtimeEnv.EXPO_HARMONY_DEVECO_SDK_ROOT ??
+        runtimeEnv.DEVECO_SDK_HOME ??
+        runtimeEnv.OHOS_SDK_HOME ??
+        (devecoStudioPath ? path_1.default.join(devecoStudioPath, 'Contents', 'sdk') : null);
+    const sdkRoot = await resolveExistingPath([sdkRootCandidate]);
+    const javaPath = await resolveExistingPath([
+        runtimeEnv.EXPO_HARMONY_JAVA_PATH,
+        runtimeEnv.JAVA_HOME ? path_1.default.join(runtimeEnv.JAVA_HOME, 'bin', 'java') : null,
+        useDefaultLookups ? findExecutableInPath('java', runtimeEnv) : null,
+    ]);
+    const ohpmPath = await resolveExistingPath([
+        runtimeEnv.EXPO_HARMONY_OHPM_PATH,
+        devecoStudioPath ? path_1.default.join(devecoStudioPath, 'Contents', 'tools', 'ohpm', 'bin', 'ohpm') : null,
+        useDefaultLookups ? findExecutableInPath('ohpm', runtimeEnv) : null,
+    ]);
+    const hvigorPath = await resolveExistingPath([
+        runtimeEnv.EXPO_HARMONY_HVIGOR_PATH,
+        devecoStudioPath ? path_1.default.join(devecoStudioPath, 'Contents', 'tools', 'hvigor', 'bin', 'hvigorw.js') : null,
+        devecoStudioPath ? path_1.default.join(devecoStudioPath, 'Contents', 'tools', 'hvigor', 'bin', 'hvigorw') : null,
+        useDefaultLookups ? findExecutableInPath('hvigorw', runtimeEnv) : null,
+        useDefaultLookups ? findExecutableInPath('hvigor', runtimeEnv) : null,
+    ]);
+    const hdcPath = await resolveExistingPath([
+        runtimeEnv.EXPO_HARMONY_HDC_PATH,
+        sdkRoot ? path_1.default.join(sdkRoot, 'default', 'openharmony', 'toolchains', 'hdc') : null,
+        useDefaultLookups ? findExecutableInPath('hdc', runtimeEnv) : null,
+    ]);
+    const harmonyProjectRootCandidate = path_1.default.join(resolvedProjectRoot, 'harmony');
+    const harmonyProjectRoot = (await fs_extra_1.default.pathExists(harmonyProjectRootCandidate))
+        ? harmonyProjectRootCandidate
+        : null;
+    const signingConfigured = harmonyProjectRoot
+        ? await detectSigningConfiguration(path_1.default.join(harmonyProjectRoot, 'build-profile.json5'))
+        : false;
+    const blockingIssues = [];
+    const advisories = [];
+    const warnings = [];
+    if (!devecoStudioPath || !sdkRoot) {
+        blockingIssues.push({
+            code: 'env.deveco_sdk.missing',
+            message: 'DevEco Studio or its Harmony SDK could not be located. Set EXPO_HARMONY_DEVECO_STUDIO_PATH or install DevEco Studio locally.',
+        });
+    }
+    if (!hvigorPath) {
+        blockingIssues.push({
+            code: 'env.hvigor.missing',
+            message: 'Hvigor could not be located. Install the DevEco hvigor toolchain or set EXPO_HARMONY_HVIGOR_PATH.',
+        });
+    }
+    if (!hdcPath) {
+        blockingIssues.push({
+            code: 'env.hdc.missing',
+            message: 'The Harmony device connector hdc could not be located. Install the DevEco device toolchain or set EXPO_HARMONY_HDC_PATH.',
+        });
+    }
+    if (!javaPath) {
+        warnings.push('Java could not be located from JAVA_HOME or PATH. Hvigor may still fail even when the DevEco SDK is present.');
+    }
+    if (!ohpmPath) {
+        warnings.push('ohpm could not be located. CLI HAP builds will fail until the DevEco package manager is available.');
+    }
+    if (!harmonyProjectRoot) {
+        warnings.push('Harmony sidecar files are not present yet. Run expo-harmony init before bundle or build-hap.');
+    }
+    else if (!signingConfigured) {
+        advisories.push({
+            code: 'env.signing.missing',
+            message: 'Harmony build-profile.json5 does not declare any signingConfigs yet. Debug GUI flows may still work, but release builds require signing.',
+        });
+    }
+    return {
+        generatedAt: new Date().toISOString(),
+        projectRoot: resolvedProjectRoot,
+        toolkitVersion: constants_1.TOOLKIT_VERSION,
+        devecoStudioPath,
+        sdkRoot,
+        harmonyProjectRoot,
+        javaPath,
+        ohpmPath,
+        hvigorPath,
+        hdcPath,
+        signingConfigured,
+        status: blockingIssues.length === 0 ? 'ready' : 'blocked',
+        blockingIssues,
+        advisories,
+        warnings,
+    };
+}
+function renderEnvReport(report) {
+    const lines = [
+        'Expo Harmony env report',
+        `Project: ${report.projectRoot}`,
+        `Status: ${report.status}`,
+        `DevEco Studio: ${report.devecoStudioPath ?? 'not found'}`,
+        `SDK root: ${report.sdkRoot ?? 'not found'}`,
+        `Harmony project: ${report.harmonyProjectRoot ?? 'not found'}`,
+        `Java: ${report.javaPath ?? 'not found'}`,
+        `ohpm: ${report.ohpmPath ?? 'not found'}`,
+        `hvigor: ${report.hvigorPath ?? 'not found'}`,
+        `hdc: ${report.hdcPath ?? 'not found'}`,
+        `Signing: ${report.signingConfigured ? 'configured' : 'not configured'}`,
+    ];
+    if (report.blockingIssues.length > 0) {
+        lines.push('', 'Blocking issues:', ...report.blockingIssues.map(renderIssueLine));
+    }
+    if (report.advisories.length > 0) {
+        lines.push('', 'Advisories:', ...report.advisories.map(renderIssueLine));
+    }
+    if (report.warnings.length > 0) {
+        lines.push('', 'Warnings:', ...report.warnings.map((warning) => `- ${warning}`));
+    }
+    return lines.join('\n');
+}
+function getStrictEnvExitCode() {
+    return constants_1.STRICT_ENV_EXIT_CODE;
+}
+async function resolveExistingPath(candidates) {
+    for (const candidate of candidates) {
+        if (!candidate) {
+            continue;
+        }
+        const resolvedCandidate = path_1.default.resolve(candidate);
+        if (await fs_extra_1.default.pathExists(resolvedCandidate)) {
+            return resolvedCandidate;
+        }
+    }
+    return null;
+}
+function findExecutableInPath(executableName, runtimeEnv) {
+    const pathValue = runtimeEnv.PATH;
+    if (!pathValue) {
+        return null;
+    }
+    for (const directory of pathValue.split(path_1.default.delimiter)) {
+        if (!directory) {
+            continue;
+        }
+        const candidatePath = path_1.default.join(directory, executableName);
+        if (fs_extra_1.default.existsSync(candidatePath)) {
+            return candidatePath;
+        }
+    }
+    return null;
+}
+async function detectSigningConfiguration(buildProfilePath) {
+    if (!(await fs_extra_1.default.pathExists(buildProfilePath))) {
+        return false;
+    }
+    const contents = await fs_extra_1.default.readFile(buildProfilePath, 'utf8');
+    const signingConfigsMatch = contents.match(/signingConfigs\s*:\s*\[([\s\S]*?)\]/m);
+    if (!signingConfigsMatch) {
+        return false;
+    }
+    return signingConfigsMatch[1].trim().length > 0;
+}
+function renderIssueLine(issue) {
+    return `- ${issue.code}: ${issue.message}${issue.subject ? ` (${issue.subject})` : ''}`;
+}

package/build/core/metadata.d.ts

@@ -0,0 +1,9 @@
+import { BuildReport, EnvReport, ToolkitConfig, ToolkitManifest } from '../types';
+export declare function getManifestPath(projectRoot: string): string;
+export declare function getToolkitConfigPath(projectRoot: string): string;
+export declare function getEnvReportPath(projectRoot: string): string;
+export declare function getBuildReportPath(projectRoot: string): string;
+export declare function readManifest(projectRoot: string): Promise<ToolkitManifest | null>;
+export declare function readToolkitConfig(projectRoot: string): Promise<ToolkitConfig | null>;
+export declare function writeEnvReport(projectRoot: string, report: EnvReport, outputPath?: string): Promise<string>;
+export declare function writeBuildReport(projectRoot: string, report: BuildReport, outputPath?: string): Promise<string>;

package/build/core/metadata.js

@@ -0,0 +1,54 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getManifestPath = getManifestPath;
+exports.getToolkitConfigPath = getToolkitConfigPath;
+exports.getEnvReportPath = getEnvReportPath;
+exports.getBuildReportPath = getBuildReportPath;
+exports.readManifest = readManifest;
+exports.readToolkitConfig = readToolkitConfig;
+exports.writeEnvReport = writeEnvReport;
+exports.writeBuildReport = writeBuildReport;
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const path_1 = __importDefault(require("path"));
+const constants_1 = require("./constants");
+function getManifestPath(projectRoot) {
+    return path_1.default.join(projectRoot, constants_1.GENERATED_DIR, constants_1.MANIFEST_FILENAME);
+}
+function getToolkitConfigPath(projectRoot) {
+    return path_1.default.join(projectRoot, constants_1.GENERATED_DIR, constants_1.TOOLKIT_CONFIG_FILENAME);
+}
+function getEnvReportPath(projectRoot) {
+    return path_1.default.join(projectRoot, constants_1.GENERATED_DIR, constants_1.ENV_REPORT_FILENAME);
+}
+function getBuildReportPath(projectRoot) {
+    return path_1.default.join(projectRoot, constants_1.GENERATED_DIR, constants_1.BUILD_REPORT_FILENAME);
+}
+async function readManifest(projectRoot) {
+    const manifestPath = getManifestPath(projectRoot);
+    if (!(await fs_extra_1.default.pathExists(manifestPath))) {
+        return null;
+    }
+    return (await fs_extra_1.default.readJson(manifestPath));
+}
+async function readToolkitConfig(projectRoot) {
+    const toolkitConfigPath = getToolkitConfigPath(projectRoot);
+    if (!(await fs_extra_1.default.pathExists(toolkitConfigPath))) {
+        return null;
+    }
+    return (await fs_extra_1.default.readJson(toolkitConfigPath));
+}
+async function writeEnvReport(projectRoot, report, outputPath) {
+    const resolvedOutputPath = outputPath ?? getEnvReportPath(projectRoot);
+    await fs_extra_1.default.ensureDir(path_1.default.dirname(resolvedOutputPath));
+    await fs_extra_1.default.writeJson(resolvedOutputPath, report, { spaces: 2 });
+    return resolvedOutputPath;
+}
+async function writeBuildReport(projectRoot, report, outputPath) {
+    const resolvedOutputPath = outputPath ?? getBuildReportPath(projectRoot);
+    await fs_extra_1.default.ensureDir(path_1.default.dirname(resolvedOutputPath));
+    await fs_extra_1.default.writeJson(resolvedOutputPath, report, { spaces: 2 });
+    return resolvedOutputPath;
+}

package/build/core/project.d.ts

@@ -0,0 +1,18 @@
+import { DependencySource, ExpoHarmonyPluginProps, HarmonyIdentifiers, LoadedProject, PackageJson } from '../types';
+export declare function resolveProjectRoot(projectRoot?: string): Promise<string>;
+export declare function loadProject(projectRoot: string): Promise<LoadedProject>;
+export declare function ensureProjectPackageJsonPath(projectRoot: string): Promise<string>;
+export declare function findAppConfigPath(projectRoot: string): Promise<string | null>;
+export declare function collectDeclaredDependencies(packageJson: PackageJson): Array<{
+    name: string;
+    version: string;
+    source: DependencySource;
+}>;
+export declare function hasDeclaredDependency(packageJson: PackageJson, dependencyName: string): boolean;
+export declare function collectExpoPlugins(expoConfig: Record<string, any>): string[];
+export declare function collectExpoSchemes(expoConfig: Record<string, any>): string[];
+export declare function deriveHarmonyIdentifiers(expoConfig: Record<string, any>, packageJson?: PackageJson, props?: ExpoHarmonyPluginProps): HarmonyIdentifiers;
+export declare function detectExpoSdkVersion(packageJson: PackageJson): number | null;
+export declare function getExpoSdkWarning(expoSdkVersion: number | null): string | null;
+export declare function resolveRnohHvigorPluginFilename(projectRoot: string): Promise<string>;
+export declare function createGeneratedSha(contents: string | Buffer): string;

package/build/core/project.js

@@ -0,0 +1,206 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveProjectRoot = resolveProjectRoot;
+exports.loadProject = loadProject;
+exports.ensureProjectPackageJsonPath = ensureProjectPackageJsonPath;
+exports.findAppConfigPath = findAppConfigPath;
+exports.collectDeclaredDependencies = collectDeclaredDependencies;
+exports.hasDeclaredDependency = hasDeclaredDependency;
+exports.collectExpoPlugins = collectExpoPlugins;
+exports.collectExpoSchemes = collectExpoSchemes;
+exports.deriveHarmonyIdentifiers = deriveHarmonyIdentifiers;
+exports.detectExpoSdkVersion = detectExpoSdkVersion;
+exports.getExpoSdkWarning = getExpoSdkWarning;
+exports.resolveRnohHvigorPluginFilename = resolveRnohHvigorPluginFilename;
+exports.createGeneratedSha = createGeneratedSha;
+const config_1 = require("@expo/config");
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const node_crypto_1 = __importDefault(require("node:crypto"));
+const path_1 = __importDefault(require("path"));
+const semver_1 = __importDefault(require("semver"));
+const constants_1 = require("./constants");
+const APP_CONFIG_CANDIDATES = [
+    'app.json',
+    'app.config.ts',
+    'app.config.js',
+    'app.config.mjs',
+    'app.config.cjs',
+];
+async function resolveProjectRoot(projectRoot) {
+    return path_1.default.resolve(projectRoot ?? process.cwd());
+}
+async function loadProject(projectRoot) {
+    const resolvedRoot = await resolveProjectRoot(projectRoot);
+    const packageJsonPath = await ensureProjectPackageJsonPath(resolvedRoot);
+    const packageJson = (await fs_extra_1.default.readJson(packageJsonPath));
+    const appConfigPath = await findAppConfigPath(resolvedRoot);
+    if (!appConfigPath && !hasExpoDependency(packageJson)) {
+        throw new Error(`No Expo app config found in ${resolvedRoot}. Expected app.json/app.config.* or an expo dependency.`);
+    }
+    const expoConfig = await readExpoConfig(resolvedRoot, appConfigPath);
+    return {
+        projectRoot: resolvedRoot,
+        packageJson,
+        expoConfig,
+        appConfigPath,
+    };
+}
+async function ensureProjectPackageJsonPath(projectRoot) {
+    const resolvedRoot = await resolveProjectRoot(projectRoot);
+    const packageJsonPath = path_1.default.join(resolvedRoot, 'package.json');
+    if (!(await fs_extra_1.default.pathExists(packageJsonPath))) {
+        throw new Error(`No package.json found at ${resolvedRoot}`);
+    }
+    return packageJsonPath;
+}
+async function findAppConfigPath(projectRoot) {
+    for (const candidate of APP_CONFIG_CANDIDATES) {
+        const candidatePath = path_1.default.join(projectRoot, candidate);
+        if (await fs_extra_1.default.pathExists(candidatePath)) {
+            return candidatePath;
+        }
+    }
+    return null;
+}
+function collectDeclaredDependencies(packageJson) {
+    const entries = [];
+    for (const [source, section] of [
+        ['dependency', packageJson.dependencies],
+        ['devDependency', packageJson.devDependencies],
+        ['peerDependency', packageJson.peerDependencies],
+    ]) {
+        for (const [name, version] of Object.entries(section ?? {})) {
+            entries.push({ name, version, source });
+        }
+    }
+    return entries.sort((left, right) => left.name.localeCompare(right.name));
+}
+function hasDeclaredDependency(packageJson, dependencyName) {
+    return Boolean(packageJson.dependencies?.[dependencyName] ||
+        packageJson.devDependencies?.[dependencyName] ||
+        packageJson.peerDependencies?.[dependencyName]);
+}
+function collectExpoPlugins(expoConfig) {
+    const plugins = expoConfig.plugins;
+    if (!Array.isArray(plugins)) {
+        return [];
+    }
+    const names = new Set();
+    for (const plugin of plugins) {
+        if (typeof plugin === 'string') {
+            names.add(plugin);
+            continue;
+        }
+        if (Array.isArray(plugin) && typeof plugin[0] === 'string') {
+            names.add(plugin[0]);
+        }
+    }
+    return [...names].sort((left, right) => left.localeCompare(right));
+}
+function collectExpoSchemes(expoConfig) {
+    const rawScheme = expoConfig.scheme;
+    if (typeof rawScheme === 'string' && rawScheme.trim().length > 0) {
+        return [rawScheme.trim()];
+    }
+    if (Array.isArray(rawScheme)) {
+        return rawScheme
+            .filter((value) => typeof value === 'string' && value.trim().length > 0)
+            .map((value) => value.trim())
+            .sort((left, right) => left.localeCompare(right));
+    }
+    return [];
+}
+function deriveHarmonyIdentifiers(expoConfig, packageJson, props) {
+    const slug = sanitizeSlug(expoConfig.slug ?? packageJson?.name ?? 'expo-harmony-app');
+    const appName = String(expoConfig.name ?? packageJson?.name ?? 'Expo Harmony App');
+    const androidPackage = normalizeIdentifier(expoConfig.android?.package);
+    const iosBundleIdentifier = normalizeIdentifier(expoConfig.ios?.bundleIdentifier);
+    return {
+        appName,
+        slug,
+        bundleName: normalizeIdentifier(props?.bundleName) ??
+            androidPackage ??
+            iosBundleIdentifier ??
+            `com.expoharmony.${slug}`,
+        entryModuleName: sanitizeIdentifierSegment(props?.entryModuleName ?? 'entry'),
+        androidPackage,
+        iosBundleIdentifier,
+    };
+}
+function detectExpoSdkVersion(packageJson) {
+    const rawVersion = packageJson.dependencies?.expo ??
+        packageJson.devDependencies?.expo ??
+        packageJson.peerDependencies?.expo;
+    if (!rawVersion) {
+        return null;
+    }
+    const coerced = semver_1.default.coerce(rawVersion);
+    return coerced?.major ?? null;
+}
+function getExpoSdkWarning(expoSdkVersion) {
+    if (expoSdkVersion === null) {
+        return 'Expo SDK version could not be detected from package.json.';
+    }
+    if (!constants_1.SUPPORTED_EXPO_SDKS.includes(expoSdkVersion)) {
+        return `Expo SDK ${expoSdkVersion} detected. The toolkit currently validates only against Expo SDK ${constants_1.SUPPORTED_EXPO_SDKS.join(' and ')} project shapes.`;
+    }
+    return null;
+}
+async function resolveRnohHvigorPluginFilename(projectRoot) {
+    const harmonyCliDir = path_1.default.join(projectRoot, 'node_modules', '@react-native-oh', 'react-native-harmony-cli', 'harmony');
+    if (!(await fs_extra_1.default.pathExists(harmonyCliDir))) {
+        return constants_1.DEFAULT_HVIGOR_PLUGIN_FILENAME;
+    }
+    const entries = await fs_extra_1.default.readdir(harmonyCliDir);
+    const tgzEntry = entries.find((entry) => entry.startsWith('rnoh-hvigor-plugin-') && entry.endsWith('.tgz'));
+    return tgzEntry ?? constants_1.DEFAULT_HVIGOR_PLUGIN_FILENAME;
+}
+function createGeneratedSha(contents) {
+    return node_crypto_1.default.createHash('sha1').update(contents).digest('hex');
+}
+async function readExpoConfig(projectRoot, appConfigPath) {
+    try {
+        const { exp } = (0, config_1.getConfig)(projectRoot, {
+            skipSDKVersionRequirement: true,
+            isPublicConfig: true,
+        });
+        return exp;
+    }
+    catch (error) {
+        if (!appConfigPath || !appConfigPath.endsWith('app.json')) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new Error(`Failed to load Expo config: ${message}`);
+        }
+        const appJson = await fs_extra_1.default.readJson(appConfigPath);
+        return (appJson.expo ?? appJson);
+    }
+}
+function hasExpoDependency(packageJson) {
+    return Boolean(packageJson.dependencies?.expo ||
+        packageJson.devDependencies?.expo ||
+        packageJson.peerDependencies?.expo);
+}
+function sanitizeSlug(value) {
+    return String(value)
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '') || 'expo-harmony-app';
+}
+function normalizeIdentifier(value) {
+    if (typeof value !== 'string' || value.trim().length === 0) {
+        return null;
+    }
+    const trimmed = value.trim();
+    return /^[a-zA-Z][a-zA-Z0-9_.]+$/.test(trimmed) ? trimmed : null;
+}
+function sanitizeIdentifierSegment(value) {
+    const cleaned = String(value)
+        .trim()
+        .replace(/[^a-zA-Z0-9_]/g, '_')
+        .replace(/^_+/, '');
+    return cleaned.length > 0 ? cleaned : 'entry';
+}

package/build/core/report.d.ts

@@ -0,0 +1,4 @@
+import { DoctorReport } from '../types';
+export declare function buildDoctorReport(projectRoot: string): Promise<DoctorReport>;
+export declare function writeDoctorReport(projectRoot: string, report: DoctorReport, outputPath?: string): Promise<string>;
+export declare function renderDoctorReport(report: DoctorReport): string;