reset-framework-cli 1.2.2 → 1.2.4

package/src/lib/project.js

@@ -1,265 +1,291 @@
-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
+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"))
+}
+
+function fileExists(filePath) {
+  return existsSync(filePath)
+}
+
+function getFrameworkBuildType(mode) {
+  return mode === "release" ? "Release" : "Debug"
+}
+
+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 normalizeStyling(value) {
-  if (value === "css" || value === "tailwindcss") {
-    return value
+function normalizeResolutionPaths(value) {
+  if (!Array.isArray(value)) {
+    return []
   }
 
-  throw new Error("project.styling must be either 'css' or 'tailwindcss'")
+  return value.filter((entry) => typeof entry === "string" && entry.trim() !== "")
 }
 
-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 resolvePackageJsonPath(packageName, resolutionPaths) {
+  const packageJsonSpecifier = `${packageName}/package.json`
 
-function normalizeProtocolRole(value) {
-  if (value === "Editor" || value === "Viewer" || value === "Shell" || value === "None") {
-    return value
+  if (resolutionPaths.length > 0) {
+    try {
+      return require.resolve(packageJsonSpecifier, { paths: resolutionPaths })
+    } catch {
+      return require.resolve(packageJsonSpecifier)
+    }
   }
 
-  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"))
+  return require.resolve(packageJsonSpecifier)
 }
 
-function fileExists(filePath) {
-  return existsSync(filePath)
-}
+function resolvePackageInfo(packageName, fallbackRoot, options = {}) {
+  const resolutionPaths = normalizeResolutionPaths(options.resolutionPaths)
 
-function getFrameworkBuildType(mode) {
-  return mode === "release" ? "Release" : "Debug"
-}
-
-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 packageJsonPath = resolvePackageJsonPath(packageName, resolutionPaths)
     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
-    }
+      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
+
+  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) {
+function resolveOptionalPackageInfo(packageName, fallbackRoot, options = {}) {
+  const resolutionPaths = normalizeResolutionPaths(options.resolutionPaths)
+
   try {
-    const packageJsonPath = require.resolve(`${packageName}/package.json`)
+    const packageJsonPath = resolvePackageJsonPath(packageName, resolutionPaths)
     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
-  }
-}
-
+
+    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
+    (descriptor) =>
+      descriptor.platform === process.platform &&
+      descriptor.arch === process.arch
   ) ?? null
 }
 
-function resolveRuntimePackage(packagesDir) {
+function resolveRuntimePackage(packagesDir, options = {}) {
   const descriptor = resolveCurrentRuntimeDescriptor()
 
   if (!descriptor) {
@@ -270,663 +296,664 @@ function resolveRuntimePackage(packagesDir) {
   const packageInfo = resolveOptionalWorkspacePackageInfo(
     descriptor.packageName,
     workspaceRoot,
-    resolveOptionalPackageInfo(descriptor.packageName, workspaceRoot)
+    resolveOptionalPackageInfo(descriptor.packageName, workspaceRoot, options)
   )
-
-  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() {
+
+  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(options = {}) {
   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 resolutionPaths = normalizeResolutionPaths([options.appRoot])
   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"))
+    resolveOptionalPackageInfo("@reset-framework/native", path.join(packagesDir, "native"), { resolutionPaths })
   )
   const sdkPackage = resolveWorkspacePackageInfo(
     "@reset-framework/sdk",
     path.join(packagesDir, "sdk"),
-    resolvePackageInfo("@reset-framework/sdk", path.join(packagesDir, "sdk"))
+    resolvePackageInfo("@reset-framework/sdk", path.join(packagesDir, "sdk"), { resolutionPaths })
   )
   const backendPackage = resolveWorkspacePackageInfo(
     "@reset-framework/backend",
     path.join(packagesDir, "backend"),
-    resolvePackageInfo("@reset-framework/backend", path.join(packagesDir, "backend"))
+    resolvePackageInfo("@reset-framework/backend", path.join(packagesDir, "backend"), { resolutionPaths })
   )
   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, backendPackage.packageRoot, 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,
-    backendPackage,
-    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"
-  const devRuntimeRoot = path.join(frameworkCacheRoot, "build", "dev", "runtime")
-  const releaseRuntimeRoot = path.join(frameworkCacheRoot, "build", "release", "runtime")
-  const devAppBinaryCandidates = isWindows
-    ? [
-        path.join(devRuntimeRoot, getFrameworkBuildType("dev"), "reset-framework.exe"),
-        path.join(devRuntimeRoot, "reset-framework.exe")
-      ]
-    : [
-        path.join(
-          frameworkCacheRoot,
-          "build",
-          "dev",
-          "runtime",
-          "reset-framework.app",
-          "Contents",
-          "MacOS",
-          "reset-framework"
-        )
-      ]
-  const releaseAppBinaryCandidates = isWindows
-    ? [
-        path.join(releaseRuntimeRoot, getFrameworkBuildType("release"), "reset-framework.exe"),
-        path.join(releaseRuntimeRoot, "reset-framework.exe")
-      ]
-    : [
-        path.join(
-          frameworkCacheRoot,
-          "build",
-          "release",
-          "runtime",
-          "reset-framework.app"
-        )
-      ]
-
-  return {
-    frameworkCacheRoot,
-    devBuildDir: path.join(frameworkCacheRoot, "build", "dev"),
-    releaseBuildDir: path.join(frameworkCacheRoot, "build", "release"),
-    devRuntimeOutputCandidates: isWindows
-      ? [path.join(devRuntimeRoot, getFrameworkBuildType("dev")), devRuntimeRoot]
-      : [path.join(frameworkCacheRoot, "build", "dev", "runtime", "reset-framework.app")],
-    releaseRuntimeOutputCandidates: isWindows
-      ? [path.join(releaseRuntimeRoot, getFrameworkBuildType("release")), releaseRuntimeRoot]
-      : [path.join(frameworkCacheRoot, "build", "release", "runtime", "reset-framework.app")],
-    devAppBinaryCandidates,
-    releaseAppBinaryCandidates,
-    devAppBinary: devAppBinaryCandidates[0],
-    releaseAppTemplate: releaseAppBinaryCandidates[0]
-  }
-}
-
-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])
-      : (frameworkBuildPaths.devAppBinaryCandidates ?? [frameworkBuildPaths.devAppBinary])
-  const existing = resolveExistingCandidate(candidates)
-
-  if (existing) {
-    return existing
-  }
-
-  if (mustExist) {
-    throw new Error(`Missing built runtime executable. Looked in: ${candidates.join(", ")}`)
-  }
-
-  return candidates[0]
-}
-
-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 ?? [])
-      : (frameworkBuildPaths.devRuntimeOutputCandidates ?? [])
-  const existing = resolveExistingCandidate(candidates)
-
-  if (existing) {
-    return existing
-  }
-
-  if (candidates.length > 0) {
-    if (mustExist) {
-      throw new Error(`Missing built runtime output directory. Looked in: ${candidates.join(", ")}`)
-    }
-
-    return candidates[0]
-  }
-
-  return path.dirname(resolveFrameworkRuntimeBinary(frameworkPaths, frameworkBuildPaths, mode, options))
-}
-
-export function resolveAppPaths(appRoot) {
-  return {
-    appRoot,
-    appPackageJsonPath: path.join(appRoot, "package.json"),
-    backendDir: path.join(appRoot, "backend"),
-    frontendDir: path.join(appRoot, "frontend"),
-    resetConfigPath: path.join(appRoot, "reset.config.json"),
-    legacyResetConfigPath: path.join(appRoot, "frontend", "reset.config.json")
-  }
-}
-
-export function resolveOptionalBackendEntry(appPaths) {
-  const candidates = [
-    path.join(appPaths.backendDir, "src", "index.ts"),
-    path.join(appPaths.backendDir, "src", "index.js"),
-    path.join(appPaths.backendDir, "index.ts"),
-    path.join(appPaths.backendDir, "index.js")
-  ]
-
-  return resolveExistingCandidate(candidates)
-}
-
-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 [
-    ["backend", frameworkPaths.backendPackage.packageJsonPath],
-    ["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],
-    ["backend", frameworkPaths.backendPackage.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)
-  const isWindows = process.platform === "win32"
-  const appBundleName = isWindows ? config.productName : `${config.productName}.app`
-  const platformDir = path.join(outputRoot, isWindows ? "windows" : "macos")
-  const appBundlePath = path.join(platformDir, appBundleName)
-  const resourcesDir = isWindows
-    ? path.join(appBundlePath, "resources")
-    : path.join(appBundlePath, "Contents", "Resources")
-  const packagesDir = path.join(outputRoot, "packages")
-
-  return {
-    outputRoot,
-    macosDir: isWindows ? undefined : platformDir,
-    windowsDir: isWindows ? platformDir : undefined,
-    appBundlePath,
-    appExecutablePath: isWindows
-      ? path.join(appBundlePath, `${config.productName}.exe`)
-      : undefined,
-    resourcesDir,
-    bundledConfigPath: path.join(resourcesDir, "reset.config.json"),
-    bundledBackendDir: path.join(resourcesDir, "backend"),
-    bundledBackendEntryPath: path.join(resourcesDir, "backend", "app.mjs"),
-    bundledBackendRunnerPath: path.join(resourcesDir, "backend", "runner.mjs"),
-    bundledBackendSupportModulePath: path.join(resourcesDir, "backend", "index.js"),
-    bundledBackendRuntimePath: path.join(
-      resourcesDir,
-      "backend",
-      process.platform === "win32" ? "backend-runtime.exe" : "backend-runtime"
-    ),
-    bundledFrontendDir: path.join(resourcesDir, config.frontend.distDir),
-    frontendDistDir: path.resolve(frontendDir, config.frontend.distDir),
-    frontendEntryFile: path.resolve(
-      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 resolveBackendDependencySpec(frameworkPaths) {
-  if (frameworkPaths.isWorkspaceLayout || frameworkPaths.backendPackage.localFallback) {
-    return `file:${frameworkPaths.backendPackage.packageRoot}`
-  }
-
-  return `^${frameworkPaths.backendPackage.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"
+    resolvePackageInfo("@reset-framework/schema", path.join(packagesDir, "schema"), { resolutionPaths })
   )
-}
+  const runtimePackage = resolveRuntimePackage(packagesDir, { resolutionPaths })
+  const isWorkspaceLayout =
+    isWorkspacePackagesDir &&
+    [cliDir, backendPackage.packageRoot, 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,
+    backendPackage,
+    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"
+  const devRuntimeRoot = path.join(frameworkCacheRoot, "build", "dev", "runtime")
+  const releaseRuntimeRoot = path.join(frameworkCacheRoot, "build", "release", "runtime")
+  const devAppBinaryCandidates = isWindows
+    ? [
+        path.join(devRuntimeRoot, getFrameworkBuildType("dev"), "reset-framework.exe"),
+        path.join(devRuntimeRoot, "reset-framework.exe")
+      ]
+    : [
+        path.join(
+          frameworkCacheRoot,
+          "build",
+          "dev",
+          "runtime",
+          "reset-framework.app",
+          "Contents",
+          "MacOS",
+          "reset-framework"
+        )
+      ]
+  const releaseAppBinaryCandidates = isWindows
+    ? [
+        path.join(releaseRuntimeRoot, getFrameworkBuildType("release"), "reset-framework.exe"),
+        path.join(releaseRuntimeRoot, "reset-framework.exe")
+      ]
+    : [
+        path.join(
+          frameworkCacheRoot,
+          "build",
+          "release",
+          "runtime",
+          "reset-framework.app"
+        )
+      ]
+
+  return {
+    frameworkCacheRoot,
+    devBuildDir: path.join(frameworkCacheRoot, "build", "dev"),
+    releaseBuildDir: path.join(frameworkCacheRoot, "build", "release"),
+    devRuntimeOutputCandidates: isWindows
+      ? [path.join(devRuntimeRoot, getFrameworkBuildType("dev")), devRuntimeRoot]
+      : [path.join(frameworkCacheRoot, "build", "dev", "runtime", "reset-framework.app")],
+    releaseRuntimeOutputCandidates: isWindows
+      ? [path.join(releaseRuntimeRoot, getFrameworkBuildType("release")), releaseRuntimeRoot]
+      : [path.join(frameworkCacheRoot, "build", "release", "runtime", "reset-framework.app")],
+    devAppBinaryCandidates,
+    releaseAppBinaryCandidates,
+    devAppBinary: devAppBinaryCandidates[0],
+    releaseAppTemplate: releaseAppBinaryCandidates[0]
+  }
+}
+
+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])
+      : (frameworkBuildPaths.devAppBinaryCandidates ?? [frameworkBuildPaths.devAppBinary])
+  const existing = resolveExistingCandidate(candidates)
+
+  if (existing) {
+    return existing
+  }
+
+  if (mustExist) {
+    throw new Error(`Missing built runtime executable. Looked in: ${candidates.join(", ")}`)
+  }
+
+  return candidates[0]
+}
+
+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 ?? [])
+      : (frameworkBuildPaths.devRuntimeOutputCandidates ?? [])
+  const existing = resolveExistingCandidate(candidates)
+
+  if (existing) {
+    return existing
+  }
+
+  if (candidates.length > 0) {
+    if (mustExist) {
+      throw new Error(`Missing built runtime output directory. Looked in: ${candidates.join(", ")}`)
+    }
+
+    return candidates[0]
+  }
+
+  return path.dirname(resolveFrameworkRuntimeBinary(frameworkPaths, frameworkBuildPaths, mode, options))
+}
+
+export function resolveAppPaths(appRoot) {
+  return {
+    appRoot,
+    appPackageJsonPath: path.join(appRoot, "package.json"),
+    backendDir: path.join(appRoot, "backend"),
+    frontendDir: path.join(appRoot, "frontend"),
+    resetConfigPath: path.join(appRoot, "reset.config.json"),
+    legacyResetConfigPath: path.join(appRoot, "frontend", "reset.config.json")
+  }
+}
+
+export function resolveOptionalBackendEntry(appPaths) {
+  const candidates = [
+    path.join(appPaths.backendDir, "src", "index.ts"),
+    path.join(appPaths.backendDir, "src", "index.js"),
+    path.join(appPaths.backendDir, "index.ts"),
+    path.join(appPaths.backendDir, "index.js")
+  ]
+
+  return resolveExistingCandidate(candidates)
+}
+
+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 [
+    ["backend", frameworkPaths.backendPackage.packageJsonPath],
+    ["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],
+    ["backend", frameworkPaths.backendPackage.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)
+  const isWindows = process.platform === "win32"
+  const appBundleName = isWindows ? config.productName : `${config.productName}.app`
+  const platformDir = path.join(outputRoot, isWindows ? "windows" : "macos")
+  const appBundlePath = path.join(platformDir, appBundleName)
+  const resourcesDir = isWindows
+    ? path.join(appBundlePath, "resources")
+    : path.join(appBundlePath, "Contents", "Resources")
+  const packagesDir = path.join(outputRoot, "packages")
+
+  return {
+    outputRoot,
+    macosDir: isWindows ? undefined : platformDir,
+    windowsDir: isWindows ? platformDir : undefined,
+    appBundlePath,
+    appExecutablePath: isWindows
+      ? path.join(appBundlePath, `${config.productName}.exe`)
+      : undefined,
+    resourcesDir,
+    bundledConfigPath: path.join(resourcesDir, "reset.config.json"),
+    bundledBackendDir: path.join(resourcesDir, "backend"),
+    bundledBackendEntryPath: path.join(resourcesDir, "backend", "app.mjs"),
+    bundledBackendRunnerPath: path.join(resourcesDir, "backend", "runner.mjs"),
+    bundledBackendSupportModulePath: path.join(resourcesDir, "backend", "index.js"),
+    bundledBackendRuntimePath: path.join(
+      resourcesDir,
+      "backend",
+      process.platform === "win32" ? "backend-runtime.exe" : "backend-runtime"
+    ),
+    bundledFrontendDir: path.join(resourcesDir, config.frontend.distDir),
+    frontendDistDir: path.resolve(frontendDir, config.frontend.distDir),
+    frontendEntryFile: path.resolve(
+      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 resolveBackendDependencySpec(frameworkPaths) {
+  if (frameworkPaths.isWorkspaceLayout || frameworkPaths.backendPackage.localFallback) {
+    return `file:${frameworkPaths.backendPackage.packageRoot}`
+  }
+
+  return `^${frameworkPaths.backendPackage.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"
+  )
+}