@auraindustry/aurajs 0.0.6 → 0.1.0

package/src/host-binary.mjs

@@ -1,20 +1,24 @@
 import { createRequire } from 'node:module';
 import { basename, dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import {
   accessSync,
   existsSync,
   readFileSync,
   mkdirSync,
   copyFileSync,
+  chmodSync,
   statSync,
   writeFileSync,
   unlinkSync,
+  renameSync,
   constants as fsConstants,
 } from 'node:fs';
 import { createHash } from 'node:crypto';
 import { homedir } from 'node:os';
 
 const requireFromHere = createRequire(import.meta.url);
+const CLI_PACKAGE_JSON_URL = new URL('../package.json', import.meta.url);
 
 const HOST_PACKAGE_SPECS = Object.freeze([
   Object.freeze({
@@ -51,6 +55,14 @@ function readJsonFile(path) {
   return JSON.parse(readFileSync(path, 'utf8'));
 }
 
+function defaultCliPackageVersion() {
+  try {
+    return readJsonFile(CLI_PACKAGE_JSON_URL).version || null;
+  } catch {
+    return null;
+  }
+}
+
 function findPackageRootFromResolvedFile(resolvedFile, packageName, readPackageJson) {
   let cursor = dirname(resolvedFile);
   while (true) {
@@ -84,6 +96,10 @@ function defaultCacheRoot() {
   return process.env.AURAJS_HOST_CACHE_DIR || join(homedir(), '.cache', 'aurajs', 'host-binaries');
 }
 
+function defaultReleaseBaseUrl() {
+  return process.env.AURAJS_HOST_RELEASE_BASE_URL || 'https://raw.githubusercontent.com/Aura-Industry';
+}
+
 function resolveOverrideHostBinaryPath({
   platform = process.platform,
   arch = process.arch,
@@ -119,15 +135,21 @@ function safeUnlink(path) {
   } catch {}
 }
 
-function resolveCacheInfo(spec, binaryPath, packageRoot, packageVersion, cacheRoot) {
-  const binaryStats = statSync(binaryPath);
+function resolveCachePaths(spec, packageVersion, cacheRoot, binaryRelativePath = spec.binaryRelativePath) {
   const cacheDir = resolve(cacheRoot, spec.target, packageVersion || 'unknown');
-  const cachedBinaryPath = resolve(cacheDir, basename(binaryPath));
+  const cachedBinaryPath = resolve(cacheDir, basename(binaryRelativePath));
   const manifestPath = resolve(cacheDir, 'manifest.json');
   return {
     cacheDir,
     cachedBinaryPath,
     manifestPath,
+  };
+}
+
+function resolveCacheInfo(spec, binaryPath, packageRoot, packageVersion, cacheRoot) {
+  const binaryStats = statSync(binaryPath);
+  return {
+    ...resolveCachePaths(spec, packageVersion, cacheRoot, binaryPath),
     sourceStat: {
       size: binaryStats.size,
       mtimeMs: binaryStats.mtimeMs,
@@ -138,6 +160,83 @@ function resolveCacheInfo(spec, binaryPath, packageRoot, packageVersion, cacheRo
   };
 }
 
+function readValidCachedBinary({ spec, packageVersion, cacheRoot }) {
+  const cache = resolveCachePaths(spec, packageVersion, cacheRoot);
+  if (!existsSync(cache.cachedBinaryPath) || !existsSync(cache.manifestPath)) {
+    return null;
+  }
+
+  try {
+    const manifest = readJsonFile(cache.manifestPath);
+    const cachedStats = statSync(cache.cachedBinaryPath);
+    const cachedHash = hashFile(cache.cachedBinaryPath);
+    const versionMatches = manifest?.packageVersion == null || manifest.packageVersion === (packageVersion || 'unknown');
+    if (
+      manifest?.packageName !== spec.packageName
+      || manifest?.target !== spec.target
+      || manifest?.sha256 !== cachedHash
+      || manifest?.size !== cachedStats.size
+      || !versionMatches
+    ) {
+      return null;
+    }
+
+    return {
+      ...cache,
+      manifest,
+      cachedStats,
+      cachedHash,
+    };
+  } catch {
+    return null;
+  }
+}
+
+function ensureCachedBinaryExecutable(path, platform) {
+  if (platform === 'win32') return;
+  try {
+    chmodSync(path, 0o755);
+  } catch {}
+}
+
+function formatReleaseRepo(spec) {
+  return `Aura-Industry/aurajs-${spec.target}`;
+}
+
+function buildReleaseSource(spec, packageVersion) {
+  const tag = `v${packageVersion}`;
+  const baseUrl = defaultReleaseBaseUrl().replace(/\/+$/, '');
+  const repo = formatReleaseRepo(spec);
+  const rootUrl = `${baseUrl}/aurajs-${spec.target}/${tag}`;
+  return {
+    repo,
+    tag,
+    rootUrl,
+    packageJsonUrl: `${rootUrl}/package.json`,
+  };
+}
+
+async function fetchText(url, fetchImpl) {
+  const response = await fetchImpl(url);
+  if (!response?.ok) {
+    throw new Error(`HTTP ${response?.status ?? 'ERR'} for ${url}`);
+  }
+  return response.text();
+}
+
+async function fetchBytes(url, fetchImpl) {
+  const response = await fetchImpl(url);
+  if (!response?.ok) {
+    throw new Error(`HTTP ${response?.status ?? 'ERR'} for ${url}`);
+  }
+  const buffer = await response.arrayBuffer();
+  return Buffer.from(buffer);
+}
+
+function writeCachedBinaryManifest(manifestPath, manifest) {
+  writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
+}
+
 export class HostBinaryResolutionError extends Error {
   constructor(message, { code = 'AURA_HOST_BINARY_ERROR', platform, arch, packageName, cause } = {}) {
     super(message, cause ? { cause } : undefined);
@@ -202,22 +301,43 @@ export function resolveAndCacheHostBinary({
   platform = process.platform,
   arch = process.arch,
   cacheRoot = defaultCacheRoot(),
-  packageJsonVersion,
+  packageJsonVersion = defaultCliPackageVersion(),
   resolvePackageRoot,
 } = {}) {
-  const resolved = resolveHostBinaryPath({ platform, arch, resolvePackageRoot });
-
-  if (resolved.override) {
+  const override = resolveOverrideHostBinaryPath({ platform, arch });
+  if (override) {
     return {
-      ...resolved,
-      cacheDir: dirname(resolved.binaryPath),
-      cachedBinaryPath: resolved.binaryPath,
+      ...override,
+      cacheDir: dirname(override.binaryPath),
+      cachedBinaryPath: override.binaryPath,
       manifestPath: null,
       cacheStatus: 'override',
       diagnostics: ['Using AURAJS_HOST_BINARY_PATH override; cache step skipped.'],
     };
   }
 
+  const spec = getHostPackageSpec({ platform, arch });
+  const versionedCacheHit = packageJsonVersion
+    ? readValidCachedBinary({ spec, packageVersion: packageJsonVersion, cacheRoot })
+    : null;
+  if (versionedCacheHit) {
+    ensureCachedBinaryExecutable(versionedCacheHit.cachedBinaryPath, platform);
+    return {
+      ...spec,
+      packageRoot: versionedCacheHit.manifest?.packageRoot || null,
+      cacheDir: versionedCacheHit.cacheDir,
+      cachedBinaryPath: versionedCacheHit.cachedBinaryPath,
+      manifestPath: versionedCacheHit.manifestPath,
+      cacheStatus: 'hit',
+      binaryPath: versionedCacheHit.cachedBinaryPath,
+      diagnostics: [],
+      packageVersion: versionedCacheHit.manifest?.packageVersion || packageJsonVersion || null,
+      release: versionedCacheHit.manifest?.release || null,
+    };
+  }
+
+  const resolved = resolveHostBinaryPath({ platform, arch, resolvePackageRoot });
+
   let packageVersion = packageJsonVersion;
   try {
     const packageJson = readJsonFile(resolve(resolved.packageRoot, 'package.json'));
@@ -237,6 +357,7 @@ export function resolveAndCacheHostBinary({
   const sourceHash = hashFile(cache.sourceBinaryPath);
   const manifest = {
     packageName: resolved.packageName,
+    packageVersion: packageVersion || 'unknown',
     target: resolved.target,
     sourceBinaryPath: cache.sourceBinaryPath,
     packageRoot: cache.packageRoot,
@@ -266,7 +387,8 @@ export function resolveAndCacheHostBinary({
   if (!cacheHit) {
     safeUnlink(cache.cachedBinaryPath);
     copyFileSync(cache.sourceBinaryPath, cache.cachedBinaryPath);
-    writeFileSync(cache.manifestPath, JSON.stringify(manifest, null, 2));
+    ensureCachedBinaryExecutable(cache.cachedBinaryPath, platform);
+    writeCachedBinaryManifest(cache.manifestPath, manifest);
   }
 
   return {
@@ -276,10 +398,181 @@ export function resolveAndCacheHostBinary({
     manifestPath: cache.manifestPath,
     cacheStatus: cacheHit ? 'hit' : 'refreshed',
     binaryPath: cache.cachedBinaryPath,
+    packageVersion,
     diagnostics: cacheHit
       ? []
-      : ['Host binary cache was missing/stale/corrupt and has been refreshed from optionalDependencies.'],
+      : ['Host binary cache was missing/stale/corrupt and has been refreshed from a packaged host binary.'],
+  };
+}
+
+export async function downloadAndCacheHostBinary({
+  platform = process.platform,
+  arch = process.arch,
+  cacheRoot = defaultCacheRoot(),
+  packageJsonVersion = defaultCliPackageVersion(),
+  fetchImpl = globalThis.fetch,
+} = {}) {
+  if (!packageJsonVersion) {
+    throw new HostBinaryResolutionError(
+      'Host binary download requires an explicit CLI package version.',
+      { code: 'AURA_HOST_VERSION_REQUIRED', platform, arch },
+    );
+  }
+
+  if (typeof fetchImpl !== 'function') {
+    throw new HostBinaryResolutionError(
+      'Global fetch is unavailable; cannot download the host binary.',
+      { code: 'AURA_HOST_DOWNLOAD_UNAVAILABLE', platform, arch },
+    );
+  }
+
+  const override = resolveOverrideHostBinaryPath({ platform, arch });
+  if (override) {
+    return {
+      ...override,
+      cacheDir: dirname(override.binaryPath),
+      cachedBinaryPath: override.binaryPath,
+      manifestPath: null,
+      cacheStatus: 'override',
+      diagnostics: ['Using AURAJS_HOST_BINARY_PATH override; cache step skipped.'],
+    };
+  }
+
+  const spec = getHostPackageSpec({ platform, arch });
+  const source = buildReleaseSource(spec, packageJsonVersion);
+  let remotePackage;
+
+  try {
+    remotePackage = JSON.parse(await fetchText(source.packageJsonUrl, fetchImpl));
+  } catch (cause) {
+    throw new HostBinaryResolutionError(
+      `Failed to load host package metadata for ${spec.packageName}@${packageJsonVersion} from ${source.repo} (${source.tag}).`,
+      { code: 'AURA_HOST_DOWNLOAD_METADATA_FAILED', platform, arch, packageName: spec.packageName, cause },
+    );
+  }
+
+  if (remotePackage?.name !== spec.packageName) {
+    throw new HostBinaryResolutionError(
+      `Downloaded host package metadata does not match expected package "${spec.packageName}".`,
+      { code: 'AURA_HOST_DOWNLOAD_METADATA_INVALID', platform, arch, packageName: spec.packageName },
+    );
+  }
+  if (remotePackage?.version !== packageJsonVersion) {
+    throw new HostBinaryResolutionError(
+      `Downloaded host package version mismatch for "${spec.packageName}": expected ${packageJsonVersion}, received ${remotePackage?.version || 'unknown'}.`,
+      { code: 'AURA_HOST_VERSION_MISMATCH', platform, arch, packageName: spec.packageName },
+    );
+  }
+
+  const remoteBinaryPath = remotePackage?.aurajsHost?.binaryPath;
+  const checksumAlgorithm = remotePackage?.aurajsHost?.checksumAlgorithm;
+  const checksum = remotePackage?.aurajsHost?.checksum;
+  if (typeof remoteBinaryPath !== 'string' || remoteBinaryPath.length === 0) {
+    throw new HostBinaryResolutionError(
+      `Downloaded host package metadata for "${spec.packageName}" is missing aurajsHost.binaryPath.`,
+      { code: 'AURA_HOST_DOWNLOAD_METADATA_INVALID', platform, arch, packageName: spec.packageName },
+    );
+  }
+  if (checksumAlgorithm !== 'sha256' || typeof checksum !== 'string' || checksum.length === 0) {
+    throw new HostBinaryResolutionError(
+      `Downloaded host package metadata for "${spec.packageName}" is missing a valid SHA256 checksum.`,
+      { code: 'AURA_HOST_DOWNLOAD_METADATA_INVALID', platform, arch, packageName: spec.packageName },
+    );
+  }
+
+  const binaryUrl = `${source.rootUrl}/${remoteBinaryPath}`;
+  let binaryBuffer;
+  try {
+    binaryBuffer = await fetchBytes(binaryUrl, fetchImpl);
+  } catch (cause) {
+    throw new HostBinaryResolutionError(
+      `Failed to download host binary for ${spec.packageName}@${packageJsonVersion} from ${source.repo} (${source.tag}).`,
+      { code: 'AURA_HOST_DOWNLOAD_BINARY_FAILED', platform, arch, packageName: spec.packageName, cause },
+    );
+  }
+
+  const binaryHash = createHash('sha256').update(binaryBuffer).digest('hex');
+  if (binaryHash !== checksum) {
+    throw new HostBinaryResolutionError(
+      `Downloaded host binary checksum mismatch for ${spec.packageName}@${packageJsonVersion}.`,
+      { code: 'AURA_HOST_CHECKSUM_MISMATCH', platform, arch, packageName: spec.packageName },
+    );
+  }
+
+  const cache = resolveCachePaths(spec, packageJsonVersion, cacheRoot, remoteBinaryPath);
+  mkdirSync(cache.cacheDir, { recursive: true });
+
+  const tempBinaryPath = `${cache.cachedBinaryPath}.download-${process.pid}-${Date.now()}`;
+  safeUnlink(tempBinaryPath);
+  safeUnlink(cache.cachedBinaryPath);
+
+  try {
+    writeFileSync(tempBinaryPath, binaryBuffer);
+    ensureCachedBinaryExecutable(tempBinaryPath, platform);
+    renameSync(tempBinaryPath, cache.cachedBinaryPath);
+  } finally {
+    safeUnlink(tempBinaryPath);
+  }
+
+  const manifest = {
+    packageName: spec.packageName,
+    packageVersion: packageJsonVersion,
+    target: spec.target,
+    sourceBinaryPath: binaryUrl,
+    packageRoot: null,
+    size: binaryBuffer.length,
+    mtimeMs: Date.now(),
+    mode: platform === 'win32' ? null : 0o755,
+    sha256: binaryHash,
+    release: {
+      repo: source.repo,
+      tag: source.tag,
+      packageJsonUrl: source.packageJsonUrl,
+      binaryUrl,
+    },
   };
+  writeCachedBinaryManifest(cache.manifestPath, manifest);
+
+  return {
+    ...spec,
+    packageRoot: null,
+    binaryPath: cache.cachedBinaryPath,
+    cacheDir: cache.cacheDir,
+    cachedBinaryPath: cache.cachedBinaryPath,
+    manifestPath: cache.manifestPath,
+    cacheStatus: 'downloaded',
+    packageVersion: packageJsonVersion,
+    diagnostics: [`Downloaded host binary from ${source.repo}@${source.tag}.`],
+    release: manifest.release,
+  };
+}
+
+export async function ensureHostBinaryAvailable(options = {}) {
+  try {
+    const defaultSearchFrom = dirname(fileURLToPath(CLI_PACKAGE_JSON_URL));
+    return resolveGateHostBinary({
+      platform: options.platform,
+      arch: options.arch,
+      searchFrom: options.searchFrom || defaultSearchFrom,
+      cacheRoot: options.cacheRoot,
+      resolveCachedBinary: (cachedOptions) => resolveAndCacheHostBinary({
+        ...options,
+        ...cachedOptions,
+      }),
+      resolvePackagedBinary: (packagedOptions) => resolveHostBinaryPath({
+        ...options,
+        ...packagedOptions,
+      }),
+    });
+  } catch (error) {
+    if (!(error instanceof HostBinaryResolutionError)) {
+      throw error;
+    }
+    if (!options?.packageJsonVersion) {
+      throw error;
+    }
+    return downloadAndCacheHostBinary(options);
+  }
 }
 
 function findInstalledPackageRoot(packageName, { requireResolve, readPackageJson }) {
@@ -295,7 +588,7 @@ function findInstalledPackageRoot(packageName, { requireResolve, readPackageJson
     resolvedEntrypoint = requireResolve(packageName);
   } catch (cause) {
     throw new HostBinaryResolutionError(
-      `Missing host package "${packageName}". Run "npm install" to install optional platform binaries.`,
+      `Missing packaged host binary "${packageName}". Run "npm install" to restore packaged binaries, or let AuraJS download the host on first run.`,
       { code: 'AURA_HOST_PACKAGE_MISSING', packageName, cause },
     );
   }
@@ -365,6 +658,23 @@ export function resolveGateHostBinary({
   const repoRoot = findRepoRootWithRustHost(searchFrom);
   const localCandidates = repoRoot ? resolveLocalHostBinaryCandidates(repoRoot, binaryName) : [];
   const checkedCandidates = localCandidates.map((candidate) => candidate.path);
+  const override = resolveOverrideHostBinaryPath({ platform, arch });
+
+  if (override) {
+    return {
+      ...override,
+      source: 'override',
+      reasonCode: 'host_binary_override_selected',
+      diagnostics: ['Using AURAJS_HOST_BINARY_PATH override; local build/package resolution skipped.'],
+      localBuild: {
+        repoRoot,
+        checked: checkedCandidates,
+      },
+      resolvedAt: new Date().toISOString(),
+    };
+  }
+
+  const availableLocalCandidates = [];
 
   for (const candidate of localCandidates) {
     if (!existsSync(candidate.path)) continue;
@@ -372,9 +682,27 @@ export function resolveGateHostBinary({
       diagnostics.push(`[host_binary_local_non_executable] Detected local ${candidate.kind} host binary but it is not executable: ${candidate.path}`);
       continue;
     }
+    availableLocalCandidates.push({
+      ...candidate,
+      mtimeMs: statSync(candidate.path).mtimeMs,
+    });
+  }
+
+  if (availableLocalCandidates.length > 0) {
+    availableLocalCandidates.sort((a, b) => {
+      if (a.kind !== b.kind) {
+        return a.kind === 'release' ? -1 : 1;
+      }
+      if (b.mtimeMs !== a.mtimeMs) {
+        return b.mtimeMs - a.mtimeMs;
+      }
+      return 0;
+    });
+
+    const candidate = availableLocalCandidates[0];
     if (candidate.kind === 'debug') {
       diagnostics.push(
-        `[host_binary_local_debug_fallback] Selected local debug host because release host is unavailable or not executable: ${candidate.path}`,
+        `[host_binary_local_debug_fallback] Selected newer local debug host: ${candidate.path}`,
       );
     }
 

package/src/icon-discovery.mjs

@@ -0,0 +1,64 @@
+import { existsSync, readdirSync } from 'node:fs';
+import { basename, extname, join, relative, resolve } from 'node:path';
+
+export const SUPPORTED_BUILD_ICON_EXTENSIONS = Object.freeze(['.png', '.jpg', '.jpeg', '.ico', '.icns']);
+
+function compareCandidates(a, b) {
+  if (a.exactBaseName !== b.exactBaseName) {
+    return a.exactBaseName ? -1 : 1;
+  }
+  if (a.extensionRank !== b.extensionRank) {
+    return a.extensionRank - b.extensionRank;
+  }
+  if (a.depth !== b.depth) {
+    return a.depth - b.depth;
+  }
+  return a.relativePath.localeCompare(b.relativePath);
+}
+
+function walk(dirPath, visit) {
+  for (const entry of readdirSync(dirPath, { withFileTypes: true })) {
+    const fullPath = join(dirPath, entry.name);
+    if (entry.isDirectory()) {
+      walk(fullPath, visit);
+      continue;
+    }
+    if (entry.isFile()) {
+      visit(fullPath);
+    }
+  }
+}
+
+export function discoverProjectIconPath({ projectRoot, assetDir = 'assets' } = {}) {
+  const normalizedAssetDir = String(assetDir || 'assets').trim() || 'assets';
+  const assetRoot = resolve(projectRoot, normalizedAssetDir);
+  if (!existsSync(assetRoot)) {
+    return null;
+  }
+
+  const candidates = [];
+  walk(assetRoot, (fullPath) => {
+    const extension = extname(fullPath).toLowerCase();
+    const extensionRank = SUPPORTED_BUILD_ICON_EXTENSIONS.indexOf(extension);
+    if (extensionRank === -1) {
+      return;
+    }
+    const fileBaseName = basename(fullPath, extension).toLowerCase();
+    if (!fileBaseName.startsWith('logo')) {
+      return;
+    }
+    const relativePath = relative(projectRoot, fullPath).split('\\').join('/');
+    candidates.push({
+      relativePath,
+      exactBaseName: fileBaseName === 'logo',
+      extensionRank,
+      depth: relativePath.split('/').length,
+    });
+  });
+
+  if (candidates.length === 0) {
+    return null;
+  }
+  candidates.sort(compareCandidates);
+  return candidates[0].relativePath;
+}

package/src/make-catalog.mjs

@@ -0,0 +1,109 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const CLI_SRC_DIR = dirname(fileURLToPath(import.meta.url));
+const CORE_MAKE_TEMPLATE_DIR = resolve(CLI_SRC_DIR, '../templates/make');
+const CORE_MAKE_CATALOG_PATH = resolve(CORE_MAKE_TEMPLATE_DIR, 'catalog.json');
+const STARTER_MAKE_TEMPLATE_DIR = resolve(CLI_SRC_DIR, '../templates/make-starters');
+
+function readJsonFile(path) {
+  return JSON.parse(readFileSync(path, 'utf8'));
+}
+
+function normalizeCatalogRows(source, { owner, scope, manifestDir }) {
+  const kinds = Array.isArray(source?.kinds) ? source.kinds : [];
+  return kinds.map((entry) => {
+    const id = String(entry?.id || '').trim();
+    const manifest = String(entry?.manifest || '').trim();
+    if (!id || !manifest) {
+      throw new Error(`Invalid make catalog entry for owner "${owner}".`);
+    }
+    return {
+      id,
+      owner,
+      scope,
+      manifestPath: resolve(manifestDir, manifest),
+      outputRoot: typeof entry?.outputRoot === 'string' && entry.outputRoot.trim().length > 0
+        ? entry.outputRoot.trim()
+        : null,
+      registerAs: typeof entry?.registerAs === 'string' && entry.registerAs.trim().length > 0
+        ? entry.registerAs.trim()
+        : null,
+      defaultRole: typeof entry?.defaultRole === 'string' && entry.defaultRole.trim().length > 0
+        ? entry.defaultRole.trim()
+        : null,
+      starterContentFamily: typeof entry?.starterContentFamily === 'string' && entry.starterContentFamily.trim().length > 0
+        ? entry.starterContentFamily.trim()
+        : null,
+      starterContentRegistry: typeof entry?.starterContentRegistry === 'string' && entry.starterContentRegistry.trim().length > 0
+        ? entry.starterContentRegistry.trim()
+        : null,
+    };
+  });
+}
+
+function loadProjectTemplate(projectRoot) {
+  if (!projectRoot) return 'blank';
+  const capabilitiesPath = resolve(projectRoot, 'aura.capabilities.json');
+  if (!existsSync(capabilitiesPath)) return 'blank';
+  try {
+    const capabilities = readJsonFile(capabilitiesPath);
+    if (typeof capabilities?.template === 'string' && capabilities.template.trim().length > 0) {
+      return capabilities.template.trim();
+    }
+  } catch {}
+  return 'blank';
+}
+
+export function loadCoreMakeCatalog() {
+  const catalog = readJsonFile(CORE_MAKE_CATALOG_PATH);
+  return normalizeCatalogRows(catalog, {
+    owner: 'core',
+    scope: 'core',
+    manifestDir: CORE_MAKE_TEMPLATE_DIR,
+  });
+}
+
+export function loadStarterMakeCatalog(template, options = {}) {
+  const normalizedTemplate = String(template || '').trim() || 'blank';
+  const starterCatalogRoot = resolve(options.catalogRoot || STARTER_MAKE_TEMPLATE_DIR);
+  const catalogPath = resolve(starterCatalogRoot, normalizedTemplate, 'catalog.json');
+  if (!existsSync(catalogPath)) return [];
+  const catalog = readJsonFile(catalogPath);
+  return normalizeCatalogRows(catalog, {
+    owner: `starter:${normalizedTemplate}`,
+    scope: normalizedTemplate,
+    manifestDir: dirname(catalogPath),
+  });
+}
+
+export function loadMakeCatalog(options = {}) {
+  const projectRoot = options.projectRoot ? resolve(options.projectRoot) : null;
+  const template = options.template || loadProjectTemplate(projectRoot);
+  const coreEntries = loadCoreMakeCatalog();
+  const starterEntries = loadStarterMakeCatalog(template, options);
+  const merged = new Map();
+
+  for (const entry of [...coreEntries, ...starterEntries]) {
+    if (merged.has(entry.id)) {
+      throw new Error(`Duplicate make kind "${entry.id}" in merged make catalog.`);
+    }
+    merged.set(entry.id, entry);
+  }
+
+  return [...merged.values()];
+}
+
+export function listMakeKinds(options = {}) {
+  return loadMakeCatalog(options).map((entry) => entry.id);
+}
+
+export function listCoreMakeKinds() {
+  return loadCoreMakeCatalog().map((entry) => entry.id);
+}
+
+export function resolveMakeKind(kind, options = {}) {
+  const normalizedKind = String(kind || '').trim();
+  return loadMakeCatalog(options).find((entry) => entry.id === normalizedKind) || null;
+}