reset-framework-cli 1.1.5 → 1.2.1

package/src/lib/project.js

@@ -1,112 +1,139 @@
-import { existsSync, readFileSync } from "node:fs"
-import { createRequire } from "node:module"
-import path from "node:path"
-import { fileURLToPath } from "node:url"
-
-const require = createRequire(import.meta.url)
-
-function requireString(object, key, scope) {
-  if (typeof object?.[key] !== "string" || object[key].trim() === "") {
-    throw new Error(`Missing or invalid string field '${scope}.${key}'`)
-  }
-
-  return object[key]
-}
-
-function optionalString(object, key, fallback) {
-  if (object == null || !(key in object)) {
-    return fallback
-  }
-
-  if (typeof object[key] !== "string" || object[key].trim() === "") {
-    throw new Error(`Missing or invalid string field '${key}'`)
-  }
-
-  return object[key]
-}
-
-function optionalObject(object, key) {
-  if (object == null || !(key in object)) {
-    return {}
-  }
-
-  if (typeof object[key] !== "object" || object[key] === null || Array.isArray(object[key])) {
-    throw new Error(`Missing or invalid object field '${key}'`)
-  }
-
-  return object[key]
-}
-
-function sanitizeName(value) {
-  return value
-    .toLowerCase()
-    .replace(/[^a-z0-9]+/g, "-")
-    .replace(/^-+|-+$/g, "") || "reset-app"
-}
-
-function normalizeFrontendDir(value) {
-  const trimmed = value.trim()
-
-  if (trimmed === "." || trimmed === "./") {
-    return "."
-  }
-
-  if (path.isAbsolute(trimmed)) {
-    throw new Error("project.frontendDir must be a relative path")
-  }
-
-  const normalized = path.normalize(trimmed).replace(/\\/g, "/").replace(/\/+$/g, "")
-
-  if (normalized === "" || normalized === ".") {
-    return "."
-  }
-
-  if (normalized.startsWith("../")) {
-    throw new Error("project.frontendDir cannot point outside the app root")
-  }
-
-  return normalized
-}
-
-function normalizeStyling(value) {
-  if (value === "css" || value === "tailwindcss") {
-    return value
-  }
-
-  throw new Error("project.styling must be either 'css' or 'tailwindcss'")
-}
-
-function normalizeProtocolScheme(value) {
-  if (typeof value !== "string" || value.trim() === "") {
-    throw new Error("protocols.schemes[].scheme must be a non-empty string")
-  }
-
-  const normalized = value.trim().toLowerCase()
-  if (!/^[a-z][a-z0-9+.-]*$/.test(normalized)) {
-    throw new Error(
-      "protocols.schemes[].scheme must start with a letter and only contain letters, numbers, '+', '-', and '.'"
-    )
-  }
-
-  return normalized
-}
-
-function normalizeProtocolRole(value) {
-  if (value === "Editor" || value === "Viewer" || value === "Shell" || value === "None") {
-    return value
-  }
-
-  throw new Error("protocols.schemes[].role must be one of Editor, Viewer, Shell, None")
-}
-
-function toTitleCase(value) {
-  return value
-    .split(/[^a-zA-Z0-9]+/)
-    .filter(Boolean)
-    .map((segment) => segment.charAt(0).toUpperCase() + segment.slice(1))
-    .join(" ") || "Reset App"
-}
-
+import { existsSync, readFileSync } from "node:fs"
+import { createRequire } from "node:module"
+import path from "node:path"
+import { fileURLToPath } from "node:url"
+
+const require = createRequire(import.meta.url)
+
+const runtimePackageDescriptors = [
+  {
+    packageName: "@reset-framework/runtime-darwin-arm64",
+    workspaceDirName: "runtime-darwin-arm64",
+    platform: "darwin",
+    arch: "arm64",
+    artifactRootSegments: ["dist", "darwin-arm64", "reset-framework.app"],
+    binarySegments: ["dist", "darwin-arm64", "reset-framework.app", "Contents", "MacOS", "reset-framework"]
+  },
+  {
+    packageName: "@reset-framework/runtime-darwin-x64",
+    workspaceDirName: "runtime-darwin-x64",
+    platform: "darwin",
+    arch: "x64",
+    artifactRootSegments: ["dist", "darwin-x64", "reset-framework.app"],
+    binarySegments: ["dist", "darwin-x64", "reset-framework.app", "Contents", "MacOS", "reset-framework"]
+  },
+  {
+    packageName: "@reset-framework/runtime-win32-x64",
+    workspaceDirName: "runtime-win32-x64",
+    platform: "win32",
+    arch: "x64",
+    artifactRootSegments: ["dist", "win32-x64"],
+    binarySegments: ["dist", "win32-x64", "reset-framework.exe"]
+  }
+]
+
+function requireString(object, key, scope) {
+  if (typeof object?.[key] !== "string" || object[key].trim() === "") {
+    throw new Error(`Missing or invalid string field '${scope}.${key}'`)
+  }
+
+  return object[key]
+}
+
+function optionalString(object, key, fallback) {
+  if (object == null || !(key in object)) {
+    return fallback
+  }
+
+  if (typeof object[key] !== "string" || object[key].trim() === "") {
+    throw new Error(`Missing or invalid string field '${key}'`)
+  }
+
+  return object[key]
+}
+
+function optionalObject(object, key) {
+  if (object == null || !(key in object)) {
+    return {}
+  }
+
+  if (typeof object[key] !== "object" || object[key] === null || Array.isArray(object[key])) {
+    throw new Error(`Missing or invalid object field '${key}'`)
+  }
+
+  return object[key]
+}
+
+function sanitizeName(value) {
+  return value
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "") || "reset-app"
+}
+
+function normalizeFrontendDir(value) {
+  const trimmed = value.trim()
+
+  if (trimmed === "." || trimmed === "./") {
+    return "."
+  }
+
+  if (path.isAbsolute(trimmed)) {
+    throw new Error("project.frontendDir must be a relative path")
+  }
+
+  const normalized = path.normalize(trimmed).replace(/\\/g, "/").replace(/\/+$/g, "")
+
+  if (normalized === "" || normalized === ".") {
+    return "."
+  }
+
+  if (normalized.startsWith("../")) {
+    throw new Error("project.frontendDir cannot point outside the app root")
+  }
+
+  return normalized
+}
+
+function normalizeStyling(value) {
+  if (value === "css" || value === "tailwindcss") {
+    return value
+  }
+
+  throw new Error("project.styling must be either 'css' or 'tailwindcss'")
+}
+
+function normalizeProtocolScheme(value) {
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new Error("protocols.schemes[].scheme must be a non-empty string")
+  }
+
+  const normalized = value.trim().toLowerCase()
+  if (!/^[a-z][a-z0-9+.-]*$/.test(normalized)) {
+    throw new Error(
+      "protocols.schemes[].scheme must start with a letter and only contain letters, numbers, '+', '-', and '.'"
+    )
+  }
+
+  return normalized
+}
+
+function normalizeProtocolRole(value) {
+  if (value === "Editor" || value === "Viewer" || value === "Shell" || value === "None") {
+    return value
+  }
+
+  throw new Error("protocols.schemes[].role must be one of Editor, Viewer, Shell, None")
+}
+
+function toTitleCase(value) {
+  return value
+    .split(/[^a-zA-Z0-9]+/)
+    .filter(Boolean)
+    .map((segment) => segment.charAt(0).toUpperCase() + segment.slice(1))
+    .join(" ") || "Reset App"
+}
+
 function readJsonFile(filePath) {
   return JSON.parse(readFileSync(filePath, "utf8"))
 }
@@ -122,105 +149,219 @@ function getFrameworkBuildType(mode) {
 function resolveExistingCandidate(candidates) {
   return candidates.find((candidate) => existsSync(candidate)) ?? null
 }
-
-function isPathInside(parentDir, candidatePath) {
-  const relative = path.relative(parentDir, candidatePath)
-  return relative !== "" && !relative.startsWith("..") && !path.isAbsolute(relative)
-}
-
-function resolvePackageInfo(packageName, fallbackRoot) {
-  try {
-    const packageJsonPath = require.resolve(`${packageName}/package.json`)
-    const packageRoot = path.dirname(packageJsonPath)
-    const manifest = readJsonFile(packageJsonPath)
-
-    return {
-      packageName: manifest.name ?? packageName,
-      packageRoot,
-      packageJsonPath,
-      version: manifest.version ?? "0.0.0",
-      localFallback: false
-    }
-  } catch {
-    const packageJsonPath = path.join(fallbackRoot, "package.json")
-    const manifest = readJsonFile(packageJsonPath)
-
-    return {
-      packageName: manifest.name ?? packageName,
-      packageRoot: fallbackRoot,
-      packageJsonPath,
-      version: manifest.version ?? "0.0.0",
-      localFallback: true
-    }
-  }
-}
-
-function resolveWorkspacePackageInfo(packageName, workspaceRoot, fallbackInfo) {
-  const packageJsonPath = path.join(workspaceRoot, "package.json")
-
-  if (!existsSync(packageJsonPath)) {
-    return fallbackInfo
-  }
-
-  const manifest = readJsonFile(packageJsonPath)
-
-  return {
-    packageName: manifest.name ?? packageName,
-    packageRoot: workspaceRoot,
-    packageJsonPath,
-    version: manifest.version ?? fallbackInfo.version,
-    localFallback: true
-  }
-}
-
-export function resolveFrameworkPaths() {
-  const moduleDir = path.dirname(fileURLToPath(import.meta.url))
-  const cliDir = path.resolve(moduleDir, "../..")
-  const packagesDir = path.resolve(cliDir, "..")
-  const cliPackageJsonPath = path.join(cliDir, "package.json")
-  const cliManifest = readJsonFile(cliPackageJsonPath)
-  const nativePackage = resolveWorkspacePackageInfo(
-    "@reset-framework/native",
-    path.join(packagesDir, "native"),
-    resolvePackageInfo("@reset-framework/native", path.join(packagesDir, "native"))
-  )
-  const sdkPackage = resolveWorkspacePackageInfo(
-    "@reset-framework/sdk",
-    path.join(packagesDir, "sdk"),
-    resolvePackageInfo("@reset-framework/sdk", path.join(packagesDir, "sdk"))
-  )
-  const schemaPackage = resolveWorkspacePackageInfo(
-    "@reset-framework/schema",
-    path.join(packagesDir, "schema"),
-    resolvePackageInfo("@reset-framework/schema", path.join(packagesDir, "schema"))
-  )
-  const isWorkspaceLayout = [nativePackage, sdkPackage, schemaPackage].every((pkg) =>
-    isPathInside(packagesDir, pkg.packageRoot)
-  )
-
-  return {
-    cliDir,
-    cliPackage: {
-      packageName: cliManifest.name,
-      packageRoot: cliDir,
-      packageJsonPath: cliPackageJsonPath,
-      version: cliManifest.version ?? "0.0.0",
-      localFallback: true
-    },
-    packagesDir,
-    frameworkRoot: nativePackage.packageRoot,
-    frameworkPackage: nativePackage,
-    isWorkspaceLayout,
-    sdkPackage,
-    schemaPackage,
-    runtimeDir: path.join(nativePackage.packageRoot, "runtime"),
-    rootCMakePath: path.join(nativePackage.packageRoot, "CMakeLists.txt"),
-    cmakePresetsPath: path.join(nativePackage.packageRoot, "CMakePresets.json"),
-    vcpkgManifestPath: path.join(nativePackage.packageRoot, "vcpkg.json"),
-    templatesDir: path.join(cliDir, "templates"),
-  }
-}
-
+
+function isPathInside(parentDir, candidatePath) {
+  const relative = path.relative(parentDir, candidatePath)
+  return relative !== "" && !relative.startsWith("..") && !path.isAbsolute(relative)
+}
+
+function resolvePackageInfo(packageName, fallbackRoot) {
+  try {
+    const packageJsonPath = require.resolve(`${packageName}/package.json`)
+    const packageRoot = path.dirname(packageJsonPath)
+    const manifest = readJsonFile(packageJsonPath)
+
+    return {
+      packageName: manifest.name ?? packageName,
+      packageRoot,
+      packageJsonPath,
+      version: manifest.version ?? "0.0.0",
+      localFallback: false
+    }
+  } catch {
+    const packageJsonPath = path.join(fallbackRoot, "package.json")
+    const manifest = readJsonFile(packageJsonPath)
+
+    return {
+      packageName: manifest.name ?? packageName,
+      packageRoot: fallbackRoot,
+      packageJsonPath,
+      version: manifest.version ?? "0.0.0",
+      localFallback: true
+    }
+  }
+}
+
+function resolveWorkspacePackageInfo(packageName, workspaceRoot, fallbackInfo) {
+  const packageJsonPath = path.join(workspaceRoot, "package.json")
+
+  if (!existsSync(packageJsonPath)) {
+    return fallbackInfo
+  }
+
+  const manifest = readJsonFile(packageJsonPath)
+
+  return {
+    packageName: manifest.name ?? packageName,
+    packageRoot: workspaceRoot,
+    packageJsonPath,
+    version: manifest.version ?? fallbackInfo.version,
+    localFallback: true
+  }
+}
+
+function resolveOptionalPackageInfo(packageName, fallbackRoot) {
+  try {
+    const packageJsonPath = require.resolve(`${packageName}/package.json`)
+    const packageRoot = path.dirname(packageJsonPath)
+    const manifest = readJsonFile(packageJsonPath)
+
+    return {
+      packageName: manifest.name ?? packageName,
+      packageRoot,
+      packageJsonPath,
+      version: manifest.version ?? "0.0.0",
+      localFallback: false
+    }
+  } catch {
+    const packageJsonPath = path.join(fallbackRoot, "package.json")
+
+    if (!existsSync(packageJsonPath)) {
+      return null
+    }
+
+    const manifest = readJsonFile(packageJsonPath)
+
+    return {
+      packageName: manifest.name ?? packageName,
+      packageRoot: fallbackRoot,
+      packageJsonPath,
+      version: manifest.version ?? "0.0.0",
+      localFallback: true
+    }
+  }
+}
+
+function resolveOptionalWorkspacePackageInfo(packageName, workspaceRoot, fallbackInfo) {
+  const packageJsonPath = path.join(workspaceRoot, "package.json")
+
+  if (!existsSync(packageJsonPath)) {
+    return fallbackInfo
+  }
+
+  const manifest = readJsonFile(packageJsonPath)
+  const version = fallbackInfo?.version ?? manifest.version ?? "0.0.0"
+
+  return {
+    packageName: manifest.name ?? packageName,
+    packageRoot: workspaceRoot,
+    packageJsonPath,
+    version,
+    localFallback: true
+  }
+}
+
+function resolveCurrentRuntimeDescriptor() {
+  return runtimePackageDescriptors.find(
+    (descriptor) =>
+      descriptor.platform === process.platform &&
+      descriptor.arch === process.arch
+  ) ?? null
+}
+
+function resolveRuntimePackage(packagesDir) {
+  const descriptor = resolveCurrentRuntimeDescriptor()
+
+  if (!descriptor) {
+    return null
+  }
+
+  const workspaceRoot = path.join(packagesDir, descriptor.workspaceDirName)
+  const packageInfo = resolveOptionalWorkspacePackageInfo(
+    descriptor.packageName,
+    workspaceRoot,
+    resolveOptionalPackageInfo(descriptor.packageName, workspaceRoot)
+  )
+
+  return {
+    descriptor,
+    packageInfo,
+    artifactRoot: packageInfo ? path.join(packageInfo.packageRoot, ...descriptor.artifactRootSegments) : null,
+    binaryPath: packageInfo ? path.join(packageInfo.packageRoot, ...descriptor.binarySegments) : null
+  }
+}
+
+function hasSourceRuntimeLayout(frameworkPaths) {
+  return Boolean(
+    frameworkPaths.frameworkPackage &&
+    frameworkPaths.frameworkRoot &&
+    frameworkPaths.runtimeDir &&
+    frameworkPaths.rootCMakePath &&
+    frameworkPaths.vcpkgManifestPath &&
+    existsSync(frameworkPaths.frameworkPackage.packageJsonPath) &&
+    existsSync(frameworkPaths.frameworkRoot) &&
+    existsSync(frameworkPaths.runtimeDir) &&
+    existsSync(frameworkPaths.rootCMakePath) &&
+    existsSync(frameworkPaths.vcpkgManifestPath)
+  )
+}
+
+function isSourceRuntimeRequested(options = {}) {
+  if (options.preferSource === true) {
+    return true
+  }
+
+  const raw = process.env.RESET_FRAMEWORK_RUNTIME_SOURCE
+  if (typeof raw !== "string") {
+    return false
+  }
+
+  return ["1", "true", "yes", "on", "source"].includes(raw.trim().toLowerCase())
+}
+
+export function resolveFrameworkPaths() {
+  const moduleDir = path.dirname(fileURLToPath(import.meta.url))
+  const cliDir = path.resolve(moduleDir, "../..")
+  const packagesDir = path.resolve(cliDir, "..")
+  const isWorkspacePackagesDir = path.basename(packagesDir) === "packages"
+  const cliPackageJsonPath = path.join(cliDir, "package.json")
+  const cliManifest = readJsonFile(cliPackageJsonPath)
+  const nativePackage = resolveOptionalWorkspacePackageInfo(
+    "@reset-framework/native",
+    path.join(packagesDir, "native"),
+    resolveOptionalPackageInfo("@reset-framework/native", path.join(packagesDir, "native"))
+  )
+  const sdkPackage = resolveWorkspacePackageInfo(
+    "@reset-framework/sdk",
+    path.join(packagesDir, "sdk"),
+    resolvePackageInfo("@reset-framework/sdk", path.join(packagesDir, "sdk"))
+  )
+  const schemaPackage = resolveWorkspacePackageInfo(
+    "@reset-framework/schema",
+    path.join(packagesDir, "schema"),
+    resolvePackageInfo("@reset-framework/schema", path.join(packagesDir, "schema"))
+  )
+  const runtimePackage = resolveRuntimePackage(packagesDir)
+  const isWorkspaceLayout =
+    isWorkspacePackagesDir &&
+    [cliDir, sdkPackage.packageRoot, schemaPackage.packageRoot].every((packageRoot) =>
+      isPathInside(packagesDir, packageRoot)
+    )
+
+  return {
+    cliDir,
+    cliPackage: {
+      packageName: cliManifest.name,
+      packageRoot: cliDir,
+      packageJsonPath: cliPackageJsonPath,
+      version: cliManifest.version ?? "0.0.0",
+      localFallback: isWorkspaceLayout
+    },
+    packagesDir,
+    frameworkRoot: nativePackage?.packageRoot ?? null,
+    frameworkPackage: nativePackage,
+    isWorkspaceLayout,
+    sdkPackage,
+    schemaPackage,
+    runtimePackage,
+    runtimeDir: nativePackage ? path.join(nativePackage.packageRoot, "runtime") : null,
+    rootCMakePath: nativePackage ? path.join(nativePackage.packageRoot, "CMakeLists.txt") : null,
+    cmakePresetsPath: nativePackage ? path.join(nativePackage.packageRoot, "CMakePresets.json") : null,
+    vcpkgManifestPath: nativePackage ? path.join(nativePackage.packageRoot, "vcpkg.json") : null,
+    templatesDir: path.join(cliDir, "templates")
+  }
+}
+
 export function resolveFrameworkBuildPaths(appPaths) {
   const frameworkCacheRoot = path.join(appPaths.appRoot, ".reset", "framework")
   const isWindows = process.platform === "win32"
@@ -275,8 +416,83 @@ export function resolveFrameworkBuildPaths(appPaths) {
   }
 }
 
-export function resolveFrameworkRuntimeBinary(frameworkBuildPaths, mode, options = {}) {
+export function resolveFrameworkRuntimeStrategy(frameworkPaths, options = {}) {
+  const sourceRequested = isSourceRuntimeRequested(options)
+  const runtimePackage = frameworkPaths.runtimePackage
+  const hasPrebuiltRuntime =
+    Boolean(runtimePackage?.packageInfo) &&
+    Boolean(runtimePackage?.artifactRoot) &&
+    Boolean(runtimePackage?.binaryPath) &&
+    existsSync(runtimePackage.artifactRoot) &&
+    existsSync(runtimePackage.binaryPath)
+  const hasSourceRuntime = hasSourceRuntimeLayout(frameworkPaths)
+
+  if (sourceRequested) {
+    if (!hasSourceRuntime) {
+      throw new Error(
+        "Source runtime was requested, but @reset-framework/native is not installed in this CLI environment."
+      )
+    }
+
+    return {
+      kind: "source",
+      packageInfo: frameworkPaths.frameworkPackage,
+      label: `${frameworkPaths.frameworkPackage.packageName}@${frameworkPaths.frameworkPackage.version}`
+    }
+  }
+
+  if (hasPrebuiltRuntime) {
+    return {
+      kind: "prebuilt",
+      packageInfo: runtimePackage.packageInfo,
+      descriptor: runtimePackage.descriptor,
+      artifactRoot: runtimePackage.artifactRoot,
+      binaryPath: runtimePackage.binaryPath,
+      label: `${runtimePackage.packageInfo.packageName}@${runtimePackage.packageInfo.version}`
+    }
+  }
+
+  if (hasSourceRuntime) {
+    return {
+      kind: "source",
+      packageInfo: frameworkPaths.frameworkPackage,
+      label: `${frameworkPaths.frameworkPackage.packageName}@${frameworkPaths.frameworkPackage.version}`
+    }
+  }
+
+  if (runtimePackage?.packageInfo) {
+    throw new Error(
+      `Installed runtime package ${runtimePackage.packageInfo.packageName} is missing bundled runtime artifacts under ${runtimePackage.artifactRoot}.`
+    )
+  }
+
+  if (runtimePackage?.descriptor) {
+    throw new Error(
+      `No bundled runtime package is installed for ${process.platform}-${process.arch}. Expected ${runtimePackage.descriptor.packageName}.`
+    )
+  }
+
+  throw new Error(
+    `Reset Framework does not currently provide a bundled runtime for ${process.platform}-${process.arch}.`
+  )
+}
+
+export function resolveFrameworkRuntimeBinary(frameworkPaths, frameworkBuildPaths, mode, options = {}) {
   const { mustExist = false } = options
+  const strategy = options.strategy ?? resolveFrameworkRuntimeStrategy(frameworkPaths, options)
+
+  if (strategy.kind === "prebuilt") {
+    if (existsSync(strategy.binaryPath)) {
+      return strategy.binaryPath
+    }
+
+    if (mustExist) {
+      throw new Error(`Missing bundled runtime executable at ${strategy.binaryPath}.`)
+    }
+
+    return strategy.binaryPath
+  }
+
   const candidates =
     mode === "release"
       ? (frameworkBuildPaths.releaseAppBinaryCandidates ?? [frameworkBuildPaths.releaseAppTemplate])
@@ -294,8 +510,22 @@ export function resolveFrameworkRuntimeBinary(frameworkBuildPaths, mode, options
   return candidates[0]
 }
 
-export function resolveFrameworkRuntimeOutputDir(frameworkBuildPaths, mode, options = {}) {
+export function resolveFrameworkRuntimeOutputDir(frameworkPaths, frameworkBuildPaths, mode, options = {}) {
   const { mustExist = false } = options
+  const strategy = options.strategy ?? resolveFrameworkRuntimeStrategy(frameworkPaths, options)
+
+  if (strategy.kind === "prebuilt") {
+    if (existsSync(strategy.artifactRoot)) {
+      return strategy.artifactRoot
+    }
+
+    if (mustExist) {
+      throw new Error(`Missing bundled runtime output directory at ${strategy.artifactRoot}.`)
+    }
+
+    return strategy.artifactRoot
+  }
+
   const candidates =
     mode === "release"
       ? (frameworkBuildPaths.releaseRuntimeOutputCandidates ?? [])
@@ -314,163 +544,224 @@ export function resolveFrameworkRuntimeOutputDir(frameworkBuildPaths, mode, opti
     return candidates[0]
   }
 
-  return path.dirname(resolveFrameworkRuntimeBinary(frameworkBuildPaths, mode, options))
-}
-
-export function resolveAppPaths(appRoot) {
-  return {
-    appRoot,
-    appPackageJsonPath: path.join(appRoot, "package.json"),
-    frontendDir: path.join(appRoot, "frontend"),
-    resetConfigPath: path.join(appRoot, "reset.config.json"),
-    legacyResetConfigPath: path.join(appRoot, "frontend", "reset.config.json")
-  }
-}
-
-export function resolveConfigPath(appPaths) {
-  if (existsSync(appPaths.resetConfigPath)) {
-    return appPaths.resetConfigPath
-  }
-
-  if (existsSync(appPaths.legacyResetConfigPath)) {
-    return appPaths.legacyResetConfigPath
-  }
-
-  return appPaths.resetConfigPath
-}
-
-export function getFrameworkChecks(frameworkPaths) {
-  return [
-    ["native", frameworkPaths.frameworkPackage.packageJsonPath],
-    ["sdk", frameworkPaths.sdkPackage.packageJsonPath],
-    ["schema", frameworkPaths.schemaPackage.packageJsonPath],
-    ["cmake", frameworkPaths.rootCMakePath],
-    ["runtime", frameworkPaths.runtimeDir],
-    ["vcpkg", frameworkPaths.vcpkgManifestPath],
-    ["templates", frameworkPaths.templatesDir]
-  ]
-}
-
-export function getAppChecks(appPaths) {
-  return [["config", resolveConfigPath(appPaths)]]
-}
-
-export function assertFrameworkInstall(frameworkPaths) {
-  const missing = getFrameworkChecks(frameworkPaths)
-    .filter(([, filePath]) => !existsSync(filePath))
-    .map(([label]) => label)
-
-  if (missing.length > 0) {
-    throw new Error(
-      `Reset CLI installation is incomplete. Missing: ${missing.join(", ")}`
-    )
-  }
-}
-
-export function assertAppProject(appPaths, config) {
-  const checks = [...getAppChecks(appPaths)]
-
-  if (config) {
-    checks.unshift(["frontend", resolveFrontendDir(appPaths, config)])
-  }
-
-  const missing = checks
-    .filter(([, filePath]) => !existsSync(filePath))
-    .map(([label]) => label)
-
-  if (missing.length > 0) {
-    throw new Error(
-      `Current directory does not look like a Reset app. Missing: ${missing.join(", ")}`
-    )
-  }
-}
-
-export function validateResetConfig(rawConfig) {
-  const frontend = optionalObject(rawConfig, "frontend")
-  const build = optionalObject(rawConfig, "build")
-  const project = optionalObject(rawConfig, "project")
-  const security = optionalObject(rawConfig, "security")
-  const protocols = optionalObject(rawConfig, "protocols")
-  const windowConfig = optionalObject(rawConfig, "window")
-  const rawProtocolSchemes = Array.isArray(protocols.schemes) ? protocols.schemes : []
-  const seenProtocolSchemes = new Set()
-
-  return {
-    ...rawConfig,
-    name: sanitizeName(requireString(rawConfig, "name", "config")),
-    productName: requireString(rawConfig, "productName", "config"),
-    appId: requireString(rawConfig, "appId", "config"),
-    version: requireString(rawConfig, "version", "config"),
-    window: {
-      title: optionalString(windowConfig, "title", "Reset App")
-    },
-    frontend: {
-      devUrl: requireString(frontend, "devUrl", "frontend"),
-      distDir: optionalString(frontend, "distDir", "dist"),
-      entryHtml: optionalString(frontend, "entryHtml", "index.html")
-    },
-    project: {
-      frontendDir: normalizeFrontendDir(optionalString(project, "frontendDir", "frontend")),
-      styling: normalizeStyling(optionalString(project, "styling", "css"))
-    },
-    build: {
-      outputDir: optionalString(build, "outputDir", ".reset/build")
-    },
-    security: {
-      permissions: Array.isArray(security.permissions)
-        ? security.permissions.map((value) => {
-            if (typeof value !== "string" || value.trim() === "") {
-              throw new Error("Missing or invalid string field 'security.permissions'")
-            }
-
-            return value
-          })
-        : []
-    },
-    protocols: {
-      schemes: rawProtocolSchemes.map((entry) => {
-        if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
-          throw new Error("protocols.schemes entries must be objects")
-        }
-
-        const scheme = normalizeProtocolScheme(entry.scheme)
-        if (seenProtocolSchemes.has(scheme)) {
-          throw new Error(`Duplicate protocol scheme '${scheme}'`)
-        }
-
-        seenProtocolSchemes.add(scheme)
-
-        return {
-          scheme,
-          name:
-            typeof entry.name === "string" && entry.name.trim() !== ""
-              ? entry.name
-              : scheme,
-          role:
-            entry.role === undefined
-              ? "Viewer"
-              : normalizeProtocolRole(entry.role)
-        }
-      })
-    }
-  }
-}
-
-export function loadResetConfig(appPaths) {
-  const configPath = resolveConfigPath(appPaths)
-  const raw = readFileSync(configPath, "utf8")
-
-  try {
-    return validateResetConfig(JSON.parse(raw))
-  } catch (error) {
-    if (error instanceof SyntaxError) {
-      throw new Error(`Invalid JSON in ${configPath}: ${error.message}`)
-    }
-
-    throw error
-  }
-}
-
+  return path.dirname(resolveFrameworkRuntimeBinary(frameworkPaths, frameworkBuildPaths, mode, options))
+}
+
+export function resolveAppPaths(appRoot) {
+  return {
+    appRoot,
+    appPackageJsonPath: path.join(appRoot, "package.json"),
+    frontendDir: path.join(appRoot, "frontend"),
+    resetConfigPath: path.join(appRoot, "reset.config.json"),
+    legacyResetConfigPath: path.join(appRoot, "frontend", "reset.config.json")
+  }
+}
+
+export function resolveConfigPath(appPaths) {
+  if (existsSync(appPaths.resetConfigPath)) {
+    return appPaths.resetConfigPath
+  }
+
+  if (existsSync(appPaths.legacyResetConfigPath)) {
+    return appPaths.legacyResetConfigPath
+  }
+
+  return appPaths.resetConfigPath
+}
+
+export function getFrameworkChecks(frameworkPaths) {
+  return [
+    ["sdk", frameworkPaths.sdkPackage.packageJsonPath],
+    ["schema", frameworkPaths.schemaPackage.packageJsonPath],
+    ["templates", frameworkPaths.templatesDir]
+  ]
+}
+
+export function getFrameworkRuntimeChecks(frameworkPaths) {
+  const checks = []
+
+  if (frameworkPaths.runtimePackage?.packageInfo) {
+    checks.push(["runtime package", frameworkPaths.runtimePackage.packageInfo.packageJsonPath])
+    if (frameworkPaths.runtimePackage.artifactRoot) {
+      checks.push(["runtime artifact", frameworkPaths.runtimePackage.artifactRoot])
+    }
+  }
+
+  if (frameworkPaths.frameworkPackage) {
+    checks.push(["native source", frameworkPaths.frameworkPackage.packageJsonPath])
+  }
+
+  if (frameworkPaths.rootCMakePath) {
+    checks.push(["cmake", frameworkPaths.rootCMakePath])
+  }
+
+  if (frameworkPaths.runtimeDir) {
+    checks.push(["runtime source", frameworkPaths.runtimeDir])
+  }
+
+  if (frameworkPaths.vcpkgManifestPath) {
+    checks.push(["vcpkg", frameworkPaths.vcpkgManifestPath])
+  }
+
+  return checks
+}
+
+export function getFrameworkRuntimeModeSummary(frameworkPaths, options = {}) {
+  const strategy = resolveFrameworkRuntimeStrategy(frameworkPaths, options)
+
+  return {
+    kind: strategy.kind,
+    label: strategy.label
+  }
+}
+
+export function hasFrameworkSourcePackage(frameworkPaths) {
+  return hasSourceRuntimeLayout(frameworkPaths)
+}
+
+export function isFrameworkSourceRequested(options = {}) {
+  return isSourceRuntimeRequested(options)
+}
+
+export function assertFrameworkInstall(frameworkPaths) {
+  const missing = getFrameworkChecks(frameworkPaths)
+    .filter(([, filePath]) => !existsSync(filePath))
+    .map(([label]) => label)
+
+  if (missing.length > 0) {
+    throw new Error(
+      `Reset CLI installation is incomplete. Missing: ${missing.join(", ")}`
+    )
+  }
+}
+
+export function assertFrameworkSourceInstall(frameworkPaths) {
+  const missing = [
+    ["native source", frameworkPaths.frameworkPackage?.packageJsonPath],
+    ["sdk", frameworkPaths.sdkPackage.packageJsonPath],
+    ["cmake", frameworkPaths.rootCMakePath],
+    ["runtime", frameworkPaths.runtimeDir],
+    ["vcpkg", frameworkPaths.vcpkgManifestPath],
+    ["templates", frameworkPaths.templatesDir]
+  ]
+    .filter(([, filePath]) => !filePath || !existsSync(filePath))
+    .map(([label]) => label)
+
+  if (missing.length > 0) {
+    throw new Error(
+      `Source runtime is unavailable in this CLI installation. Missing: ${missing.join(", ")}`
+    )
+  }
+}
+
+export function getAppChecks(appPaths) {
+  return [["config", resolveConfigPath(appPaths)]]
+}
+
+export function assertAppProject(appPaths, config) {
+  const checks = [...getAppChecks(appPaths)]
+
+  if (config) {
+    checks.unshift(["frontend", resolveFrontendDir(appPaths, config)])
+  }
+
+  const missing = checks
+    .filter(([, filePath]) => !existsSync(filePath))
+    .map(([label]) => label)
+
+  if (missing.length > 0) {
+    throw new Error(
+      `Current directory does not look like a Reset app. Missing: ${missing.join(", ")}`
+    )
+  }
+}
+
+export function validateResetConfig(rawConfig) {
+  const frontend = optionalObject(rawConfig, "frontend")
+  const build = optionalObject(rawConfig, "build")
+  const project = optionalObject(rawConfig, "project")
+  const security = optionalObject(rawConfig, "security")
+  const protocols = optionalObject(rawConfig, "protocols")
+  const windowConfig = optionalObject(rawConfig, "window")
+  const rawProtocolSchemes = Array.isArray(protocols.schemes) ? protocols.schemes : []
+  const seenProtocolSchemes = new Set()
+
+  return {
+    ...rawConfig,
+    name: sanitizeName(requireString(rawConfig, "name", "config")),
+    productName: requireString(rawConfig, "productName", "config"),
+    appId: requireString(rawConfig, "appId", "config"),
+    version: requireString(rawConfig, "version", "config"),
+    window: {
+      title: optionalString(windowConfig, "title", "Reset App")
+    },
+    frontend: {
+      devUrl: requireString(frontend, "devUrl", "frontend"),
+      distDir: optionalString(frontend, "distDir", "dist"),
+      entryHtml: optionalString(frontend, "entryHtml", "index.html")
+    },
+    project: {
+      frontendDir: normalizeFrontendDir(optionalString(project, "frontendDir", "frontend")),
+      styling: normalizeStyling(optionalString(project, "styling", "css"))
+    },
+    build: {
+      outputDir: optionalString(build, "outputDir", ".reset/build")
+    },
+    security: {
+      permissions: Array.isArray(security.permissions)
+        ? security.permissions.map((value) => {
+            if (typeof value !== "string" || value.trim() === "") {
+              throw new Error("Missing or invalid string field 'security.permissions'")
+            }
+
+            return value
+          })
+        : []
+    },
+    protocols: {
+      schemes: rawProtocolSchemes.map((entry) => {
+        if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
+          throw new Error("protocols.schemes entries must be objects")
+        }
+
+        const scheme = normalizeProtocolScheme(entry.scheme)
+        if (seenProtocolSchemes.has(scheme)) {
+          throw new Error(`Duplicate protocol scheme '${scheme}'`)
+        }
+
+        seenProtocolSchemes.add(scheme)
+
+        return {
+          scheme,
+          name:
+            typeof entry.name === "string" && entry.name.trim() !== ""
+              ? entry.name
+              : scheme,
+          role:
+            entry.role === undefined
+              ? "Viewer"
+              : normalizeProtocolRole(entry.role)
+        }
+      })
+    }
+  }
+}
+
+export function loadResetConfig(appPaths) {
+  const configPath = resolveConfigPath(appPaths)
+  const raw = readFileSync(configPath, "utf8")
+
+  try {
+    return validateResetConfig(JSON.parse(raw))
+  } catch (error) {
+    if (error instanceof SyntaxError) {
+      throw new Error(`Invalid JSON in ${configPath}: ${error.message}`)
+    }
+
+    throw error
+  }
+}
+
 export function resolveAppOutputPaths(appPaths, config) {
   const outputRoot = path.resolve(appPaths.appRoot, config.build.outputDir)
   const frontendDir = resolveFrontendDir(appPaths, config)
@@ -496,109 +787,109 @@ export function resolveAppOutputPaths(appPaths, config) {
     bundledFrontendDir: path.join(resourcesDir, config.frontend.distDir),
     frontendDistDir: path.resolve(frontendDir, config.frontend.distDir),
     frontendEntryFile: path.resolve(
-      frontendDir,
-      config.frontend.distDir,
-      config.frontend.entryHtml
+      frontendDir,
+      config.frontend.distDir,
+      config.frontend.entryHtml
     ),
     packagesDir,
     zipPath: path.join(packagesDir, `${config.name}-${isWindows ? "windows" : "macos"}.zip`)
   }
 }
-
-export function resolveFrontendDir(appPaths, config) {
-  return path.resolve(appPaths.appRoot, config.project.frontendDir)
-}
-
-export function resolveDevServerOptions(config) {
-  const url = new URL(config.frontend.devUrl)
-
-  return {
-    host: url.hostname,
-    port: url.port || "5173",
-    url: url.toString()
-  }
-}
-
-export function makeAppMetadata(appName) {
-  const name = sanitizeName(appName)
-  const productName = toTitleCase(appName)
-
-  return {
-    name,
-    productName,
-    appId: `com.example.${name}`,
-    title: productName
-  }
-}
-
-export function resolveSdkDependencySpec(frameworkPaths) {
-  if (frameworkPaths.isWorkspaceLayout || frameworkPaths.sdkPackage.localFallback) {
-    return `file:${frameworkPaths.sdkPackage.packageRoot}`
-  }
-
-  return `^${frameworkPaths.sdkPackage.version}`
-}
-
-export function resolveCliDependencySpec(frameworkPaths) {
-  if (frameworkPaths.isWorkspaceLayout || frameworkPaths.cliPackage.localFallback) {
-    return `file:${frameworkPaths.cliPackage.packageRoot}`
-  }
-
-  return `^${frameworkPaths.cliPackage.version}`
-}
-
-function detectPackageManagerFromManifest(packageJsonPath) {
-  if (!fileExists(packageJsonPath)) {
-    return null
-  }
-
-  const manifest = readJsonFile(packageJsonPath)
-  const raw = typeof manifest.packageManager === "string" ? manifest.packageManager.trim() : ""
-  if (raw === "") {
-    return null
-  }
-
-  const [name] = raw.split("@")
-  if (name === "npm" || name === "pnpm" || name === "yarn" || name === "bun") {
-    return name
-  }
-
-  return null
-}
-
-function detectPackageManagerFromLocks(directory) {
-  if (!fileExists(directory)) {
-    return null
-  }
-
-  if (fileExists(path.join(directory, "bun.lock")) || fileExists(path.join(directory, "bun.lockb"))) {
-    return "bun"
-  }
-
-  if (fileExists(path.join(directory, "pnpm-lock.yaml"))) {
-    return "pnpm"
-  }
-
-  if (fileExists(path.join(directory, "yarn.lock"))) {
-    return "yarn"
-  }
-
-  if (fileExists(path.join(directory, "package-lock.json"))) {
-    return "npm"
-  }
-
-  return null
-}
-
-export function resolveAppPackageManager(appPaths, config) {
-  const frontendDir = resolveFrontendDir(appPaths, config)
-  const frontendPackageJsonPath = path.join(frontendDir, "package.json")
-
-  return (
-    detectPackageManagerFromManifest(appPaths.appPackageJsonPath) ??
-    detectPackageManagerFromManifest(frontendPackageJsonPath) ??
-    detectPackageManagerFromLocks(appPaths.appRoot) ??
-    detectPackageManagerFromLocks(frontendDir) ??
-    "npm"
-  )
-}
+
+export function resolveFrontendDir(appPaths, config) {
+  return path.resolve(appPaths.appRoot, config.project.frontendDir)
+}
+
+export function resolveDevServerOptions(config) {
+  const url = new URL(config.frontend.devUrl)
+
+  return {
+    host: url.hostname,
+    port: url.port || "5173",
+    url: url.toString()
+  }
+}
+
+export function makeAppMetadata(appName) {
+  const name = sanitizeName(appName)
+  const productName = toTitleCase(appName)
+
+  return {
+    name,
+    productName,
+    appId: `com.example.${name}`,
+    title: productName
+  }
+}
+
+export function resolveSdkDependencySpec(frameworkPaths) {
+  if (frameworkPaths.isWorkspaceLayout || frameworkPaths.sdkPackage.localFallback) {
+    return `file:${frameworkPaths.sdkPackage.packageRoot}`
+  }
+
+  return `^${frameworkPaths.sdkPackage.version}`
+}
+
+export function resolveCliDependencySpec(frameworkPaths) {
+  if (frameworkPaths.isWorkspaceLayout || frameworkPaths.cliPackage.localFallback) {
+    return `file:${frameworkPaths.cliPackage.packageRoot}`
+  }
+
+  return `^${frameworkPaths.cliPackage.version}`
+}
+
+function detectPackageManagerFromManifest(packageJsonPath) {
+  if (!fileExists(packageJsonPath)) {
+    return null
+  }
+
+  const manifest = readJsonFile(packageJsonPath)
+  const raw = typeof manifest.packageManager === "string" ? manifest.packageManager.trim() : ""
+  if (raw === "") {
+    return null
+  }
+
+  const [name] = raw.split("@")
+  if (name === "npm" || name === "pnpm" || name === "yarn" || name === "bun") {
+    return name
+  }
+
+  return null
+}
+
+function detectPackageManagerFromLocks(directory) {
+  if (!fileExists(directory)) {
+    return null
+  }
+
+  if (fileExists(path.join(directory, "bun.lock")) || fileExists(path.join(directory, "bun.lockb"))) {
+    return "bun"
+  }
+
+  if (fileExists(path.join(directory, "pnpm-lock.yaml"))) {
+    return "pnpm"
+  }
+
+  if (fileExists(path.join(directory, "yarn.lock"))) {
+    return "yarn"
+  }
+
+  if (fileExists(path.join(directory, "package-lock.json"))) {
+    return "npm"
+  }
+
+  return null
+}
+
+export function resolveAppPackageManager(appPaths, config) {
+  const frontendDir = resolveFrontendDir(appPaths, config)
+  const frontendPackageJsonPath = path.join(frontendDir, "package.json")
+
+  return (
+    detectPackageManagerFromManifest(appPaths.appPackageJsonPath) ??
+    detectPackageManagerFromManifest(frontendPackageJsonPath) ??
+    detectPackageManagerFromLocks(appPaths.appRoot) ??
+    detectPackageManagerFromLocks(frontendDir) ??
+    "npm"
+  )
+}