pi-apexlang 0.1.0

package/skills/apexlang/tools/query-valid-props-runtime.mjs

@@ -0,0 +1,319 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import zlib from "node:zlib";
+
+/**
+ * Runtime discovery and JAR-reading helpers for compiler-backed property metadata.
+ */
+
+export const ORACLE_HOME_ENV_VARS = ["APEXLANG_ORACLE_HOME", "DBTOOLS_HOME", "SQLCL_HOME", "ORACLE_HOME"];
+export const MAX_METADATA_OUTPUT_BYTES = 64 * 1024 * 1024;
+const ZIP_EOCD_SIGNATURE = 0x06054b50;
+const ZIP_CENTRAL_DIRECTORY_SIGNATURE = 0x02014b50;
+const ZIP_LOCAL_FILE_SIGNATURE = 0x04034b50;
+const ZIP_STORED_METHOD = 0;
+const ZIP_DEFLATE_METHOD = 8;
+const ZIP_MAX_COMMENT_LENGTH = 0xffff;
+
+function isExecutableFile(candidate) {
+  return fs.existsSync(candidate) && fs.statSync(candidate).isFile();
+}
+
+/**
+ * Find the SQLcl sql executable on PATH across Unix and Windows shells.
+ */
+export function findSqlOnPath({
+  pathValue = process.env.PATH || "",
+  platform = process.platform,
+  pathExtValue = process.env.PATHEXT || ".EXE;.CMD;.BAT;.COM"
+} = {}) {
+  const pathEntries = pathValue.split(path.delimiter).filter(Boolean);
+  const executableNames = platform === "win32"
+    ? Array.from(new Set([
+        "sql",
+        ...pathExtValue
+          .split(";")
+          .map((value) => value.trim())
+          .filter(Boolean)
+          .map((value) => `sql${value.toLowerCase()}`)
+      ]))
+    : ["sql"];
+
+  for (const entry of pathEntries) {
+    for (const executableName of executableNames) {
+      const candidate = path.join(entry, executableName);
+      if (isExecutableFile(candidate)) {
+        return candidate;
+      }
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Build ordered Oracle runtime candidates from flags, environment variables, VS Code extensions, and PATH SQLcl.
+ */
+export function collectOracleHomeCandidates(explicitOracleHome) {
+  const candidates = [];
+  const seen = new Set();
+
+  function addCandidate(candidate, source) {
+    if (!candidate) {
+      return;
+    }
+    const resolved = path.resolve(candidate);
+    if (seen.has(resolved)) {
+      return;
+    }
+    seen.add(resolved);
+    candidates.push({ path: resolved, source });
+  }
+
+  if (explicitOracleHome) {
+    addCandidate(explicitOracleHome, "flag");
+    return candidates;
+  }
+
+  for (const envName of ORACLE_HOME_ENV_VARS) {
+    if (process.env[envName]) {
+      addCandidate(process.env[envName], `env:${envName}`);
+    }
+  }
+
+  const vscodeExtensionsDir = path.join(os.homedir(), ".vscode", "extensions");
+  if (fs.existsSync(vscodeExtensionsDir)) {
+    const extensionDirs = fs.readdirSync(vscodeExtensionsDir, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory() && entry.name.startsWith("oracle.sql-developer-"))
+      .map((entry) => path.join(vscodeExtensionsDir, entry.name))
+      .sort((left, right) => right.localeCompare(left));
+    for (const extensionDir of extensionDirs) {
+      addCandidate(extensionDir, "vscode_extension");
+    }
+  }
+
+  const resolvedSqlPath = findSqlOnPath();
+  if (resolvedSqlPath) {
+    addCandidate(path.dirname(path.dirname(resolvedSqlPath)), "path_sqlcl");
+  }
+
+  return candidates;
+}
+
+/**
+ * Return the newest APEXlang compiler JAR in a directory, when present.
+ */
+export function findCompilerJarInDirectory(directory) {
+  if (!fs.existsSync(directory) || !fs.statSync(directory).isDirectory()) {
+    return null;
+  }
+  const matches = fs.readdirSync(directory)
+    .filter((entry) => /^apexlang-compiler-.*\.jar$/.test(entry))
+    .sort((left, right) => right.localeCompare(left));
+  if (!matches.length) {
+    return null;
+  }
+  return path.join(directory, matches[0]);
+}
+
+/**
+ * Resolve one candidate path into the compiler JAR and runtime home used by metadata queries.
+ */
+export function resolveOracleRuntimeCandidate(candidate) {
+  const directPath = candidate.path;
+  const checks = [];
+
+  if (fs.existsSync(directPath) && fs.statSync(directPath).isFile() && directPath.endsWith(".jar")) {
+    checks.push({
+      compilerJarPath: directPath,
+      runtimeHome: path.dirname(path.dirname(directPath))
+    });
+  }
+
+  checks.push(
+    {
+      compilerJarPath: findCompilerJarInDirectory(path.join(directPath, "dbtools", "sqlcl", "lib")),
+      runtimeHome: path.join(directPath, "dbtools", "sqlcl")
+    },
+    {
+      compilerJarPath: findCompilerJarInDirectory(path.join(directPath, "sqlcl", "lib")),
+      runtimeHome: path.join(directPath, "sqlcl")
+    },
+    {
+      compilerJarPath: findCompilerJarInDirectory(path.join(directPath, "lib")),
+      runtimeHome: directPath
+    }
+  );
+
+  const buildRootCompilerJar = path.join(directPath, "lib", "ext", "apexlang-compiler.jar");
+  if (fs.existsSync(buildRootCompilerJar)) {
+    checks.push({
+      compilerJarPath: buildRootCompilerJar,
+      runtimeHome: directPath
+    });
+  }
+
+  for (const check of checks) {
+    if (!check.compilerJarPath || !fs.existsSync(check.compilerJarPath)) {
+      continue;
+    }
+    return {
+      compilerJarPath: check.compilerJarPath,
+      oracleHome: candidate.path,
+      runtimeHome: check.runtimeHome,
+      source: candidate.source
+    };
+  }
+
+  return null;
+}
+
+/**
+ * Resolve the first usable Oracle runtime or throw a clear setup error.
+ */
+export function resolveOracleRuntime(explicitOracleHome) {
+  const candidates = collectOracleHomeCandidates(explicitOracleHome);
+  for (const candidate of candidates) {
+    const resolved = resolveOracleRuntimeCandidate(candidate);
+    if (resolved) {
+      return resolved;
+    }
+  }
+
+  const details = candidates.map((candidate) => `- ${candidate.source}: ${candidate.path}`).join("\n");
+  throw new Error(
+    [
+      "Could not find an Oracle APEXlang runtime for query-valid-props.",
+      "Expected an installed Oracle VS Code extension, dbtools home, SQLcl home, or direct compiler jar path.",
+      "Checked:",
+      details || "- none"
+    ].join("\n")
+  );
+}
+
+function readUInt16(buffer, offset, context) {
+  if (offset < 0 || offset + 2 > buffer.length) {
+    throw new Error(`Malformed jar: could not read ${context}`);
+  }
+  return buffer.readUInt16LE(offset);
+}
+
+function readUInt32(buffer, offset, context) {
+  if (offset < 0 || offset + 4 > buffer.length) {
+    throw new Error(`Malformed jar: could not read ${context}`);
+  }
+  return buffer.readUInt32LE(offset);
+}
+
+function findEndOfCentralDirectory(buffer) {
+  const minimumLength = 22;
+  if (buffer.length < minimumLength) {
+    throw new Error("Malformed jar: file is too small to be a ZIP/JAR archive");
+  }
+
+  const start = Math.max(0, buffer.length - minimumLength - ZIP_MAX_COMMENT_LENGTH);
+  for (let offset = buffer.length - minimumLength; offset >= start; offset -= 1) {
+    if (buffer.readUInt32LE(offset) === ZIP_EOCD_SIGNATURE) {
+      return offset;
+    }
+  }
+  throw new Error("Malformed jar: could not find ZIP end of central directory");
+}
+
+function inflateEntryData(compressedData, entryName, jarPath) {
+  try {
+    return zlib.inflateRawSync(compressedData, { maxOutputLength: MAX_METADATA_OUTPUT_BYTES });
+  } catch (error) {
+    throw new Error(
+      `Could not decompress ${entryName} from ${jarPath}: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+}
+
+/**
+ * Locate and read one entry from a JAR/ZIP file without shelling out to unzip.
+ */
+export function readJarEntry(jarPath, entryName) {
+  const archive = fs.readFileSync(jarPath);
+  const eocdOffset = findEndOfCentralDirectory(archive);
+  const centralDirectorySize = readUInt32(archive, eocdOffset + 12, "central directory size");
+  const centralDirectoryOffset = readUInt32(archive, eocdOffset + 16, "central directory offset");
+  const centralDirectoryEnd = centralDirectoryOffset + centralDirectorySize;
+
+  if (centralDirectoryEnd > archive.length) {
+    throw new Error(`Malformed jar: central directory exceeds file length in ${jarPath}`);
+  }
+
+  let offset = centralDirectoryOffset;
+  while (offset < centralDirectoryEnd) {
+    const signature = readUInt32(archive, offset, "central directory signature");
+    if (signature !== ZIP_CENTRAL_DIRECTORY_SIGNATURE) {
+      throw new Error(`Malformed jar: invalid central directory entry in ${jarPath}`);
+    }
+
+    const compressionMethod = readUInt16(archive, offset + 10, "central directory compression method");
+    const compressedSize = readUInt32(archive, offset + 20, "central directory compressed size");
+    const uncompressedSize = readUInt32(archive, offset + 24, "central directory uncompressed size");
+    const fileNameLength = readUInt16(archive, offset + 28, "central directory file name length");
+    const extraFieldLength = readUInt16(archive, offset + 30, "central directory extra field length");
+    const fileCommentLength = readUInt16(archive, offset + 32, "central directory comment length");
+    const localHeaderOffset = readUInt32(archive, offset + 42, "central directory local header offset");
+    const nameOffset = offset + 46;
+    const nameEnd = nameOffset + fileNameLength;
+
+    if (nameEnd > archive.length) {
+      throw new Error(`Malformed jar: central directory entry name exceeds file length in ${jarPath}`);
+    }
+
+    const currentEntryName = archive.toString("utf8", nameOffset, nameEnd);
+    const nextOffset = nameEnd + extraFieldLength + fileCommentLength;
+    if (nextOffset > archive.length) {
+      throw new Error(`Malformed jar: central directory entry exceeds file length in ${jarPath}`);
+    }
+
+    if (currentEntryName === entryName) {
+      if (compressedSize > MAX_METADATA_OUTPUT_BYTES || uncompressedSize > MAX_METADATA_OUTPUT_BYTES) {
+        throw new Error(
+          `Jar entry ${entryName} in ${jarPath} exceeds the maximum supported size of ${MAX_METADATA_OUTPUT_BYTES} bytes`
+        );
+      }
+
+      if (readUInt32(archive, localHeaderOffset, "local file header signature") !== ZIP_LOCAL_FILE_SIGNATURE) {
+        throw new Error(`Malformed jar: invalid local file header for ${entryName} in ${jarPath}`);
+      }
+
+      const localNameLength = readUInt16(archive, localHeaderOffset + 26, "local file header name length");
+      const localExtraLength = readUInt16(archive, localHeaderOffset + 28, "local file header extra field length");
+      const dataOffset = localHeaderOffset + 30 + localNameLength + localExtraLength;
+      const dataEnd = dataOffset + compressedSize;
+      if (dataEnd > archive.length) {
+        throw new Error(`Malformed jar: entry data for ${entryName} exceeds file length in ${jarPath}`);
+      }
+
+      const compressedData = archive.subarray(dataOffset, dataEnd);
+      let entryData;
+      if (compressionMethod === ZIP_STORED_METHOD) {
+        entryData = Buffer.from(compressedData);
+      } else if (compressionMethod === ZIP_DEFLATE_METHOD) {
+        entryData = inflateEntryData(compressedData, entryName, jarPath);
+      } else {
+        throw new Error(
+          `Jar entry ${entryName} in ${jarPath} uses unsupported compression method ${compressionMethod}`
+        );
+      }
+
+      if (entryData.length !== uncompressedSize) {
+        throw new Error(
+          `Malformed jar: entry ${entryName} in ${jarPath} expected ${uncompressedSize} bytes, found ${entryData.length}`
+        );
+      }
+
+      return entryData.toString("utf8");
+    }
+
+    offset = nextOffset;
+  }
+
+  throw new Error(`Jar entry ${entryName} not found in ${jarPath}`);
+}

package/skills/apexlang/tools/query-valid-props-template-components.mjs

@@ -0,0 +1,330 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const SCRIPT_PATH = fileURLToPath(import.meta.url);
+const IS_PACKAGED_ROOT = path.basename(path.dirname(SCRIPT_PATH)) === "tools";
+const REPO_ROOT = IS_PACKAGED_ROOT
+  ? path.resolve(path.dirname(SCRIPT_PATH), "..")
+  : path.resolve(path.dirname(SCRIPT_PATH), "..", "..", "..");
+
+export const TEMPLATE_COMPONENT_ALIASES = {
+  actions: "actions-theme-universal-theme",
+  avatar: "avatar-theme-universal-theme",
+  badge: "badge-theme-universal-theme",
+  button: "button-theme-universal-theme",
+  comments: "comments-theme-universal-theme",
+  contentRow: "contentRow-theme-universal-theme",
+  flexboxContainer: "flexboxContainer-theme-universal-theme",
+  listItem: "listItem-theme-universal-theme",
+  mediaList: "mediaList-theme-universal-theme",
+  metricCard: "metricCard-theme-universal-theme",
+  timeline: "timeline-theme-universal-theme"
+};
+
+export const DISTILLED_TEMPLATE_COMPONENT_PROFILE_PATH = IS_PACKAGED_ROOT
+  ? path.join(REPO_ROOT, "templates", "template-components", "template-component-profiles.json")
+  : path.join(REPO_ROOT, "ai-context", "apexlang", "templates", "template-components", "template-component-profiles.json");
+
+function resolveTemplateComponentDir(sourceRoot, name) {
+  const aliasTarget = TEMPLATE_COMPONENT_ALIASES[name] || name;
+  const pluginDir = path.join(sourceRoot, aliasTarget);
+  if (!fs.existsSync(pluginDir) || !fs.statSync(pluginDir).isDirectory()) {
+    return null;
+  }
+  return {
+    requestedName: name,
+    resolvedName: aliasTarget,
+    pluginDir
+  };
+}
+
+function findParenBlock(text, keyword) {
+  const pattern = new RegExp(`(^|\\n)\\s*${keyword}\\s+([A-Za-z0-9_$-]+)\\s*\\(`, "m");
+  const match = pattern.exec(text);
+  if (!match) {
+    return null;
+  }
+
+  const start = match.index + match[1].length;
+  const identifier = match[2];
+  let depth = 0;
+  for (let index = start; index < text.length; index += 1) {
+    const ch = text[index];
+    if (ch === "(") depth += 1;
+    else if (ch === ")") {
+      depth -= 1;
+      if (depth === 0) {
+        return {
+          identifier,
+          block: text.slice(start, index + 1)
+        };
+      }
+    }
+  }
+  return null;
+}
+
+function extractScalar(text, key) {
+  if (!text) {
+    return null;
+  }
+
+  const blockPattern = new RegExp(`(^|\\n)\\s*${key}\\s*:\\s*\\\`\\\`\\\`(?:[A-Za-z0-9_-]+)?\\n([\\s\\S]*?)\\\`\\\`\\\``, "m");
+  const blockMatch = blockPattern.exec(text);
+  if (blockMatch) {
+    return blockMatch[2].trim();
+  }
+
+  const pattern = new RegExp(`(^|\\n)\\s*${key}\\s*:\\s*(.+)`, "m");
+  const match = pattern.exec(text);
+  return match ? match[2].trim() : null;
+}
+
+function extractBraceBlock(text, key) {
+  const pattern = new RegExp(`(^|\\n)\\s*${key}\\s*\\{`, "m");
+  const match = pattern.exec(text);
+  if (!match) {
+    return null;
+  }
+  const start = match.index + match[1].length + match[0].slice(match[1].length).lastIndexOf("{");
+  let depth = 0;
+  for (let index = start; index < text.length; index += 1) {
+    const ch = text[index];
+    if (ch === "{") depth += 1;
+    else if (ch === "}") {
+      depth -= 1;
+      if (depth === 0) {
+        return text.slice(start, index + 1);
+      }
+    }
+  }
+  return null;
+}
+
+function extractListItems(text, key) {
+  const pattern = new RegExp(`(^|\\n)\\s*${key}\\s*:\\s*\\[([^\\]]*)\\]`, "m");
+  const match = pattern.exec(text);
+  if (!match) {
+    return [];
+  }
+  return match[2]
+    .split(/\s+/)
+    .map((item) => item.trim())
+    .filter(Boolean);
+}
+
+function findAllParenBlocks(text, keyword) {
+  const results = [];
+  const pattern = new RegExp(`(^|\\n)\\s*${keyword}\\s+([A-Za-z0-9_$-]+)\\s*\\(`, "gm");
+  let match;
+  while ((match = pattern.exec(text)) !== null) {
+    const start = match.index + match[1].length;
+    const identifier = match[2];
+    let depth = 0;
+    for (let index = start; index < text.length; index += 1) {
+      const ch = text[index];
+      if (ch === "(") depth += 1;
+      else if (ch === ")") {
+        depth -= 1;
+        if (depth === 0) {
+          results.push({ identifier, block: text.slice(start, index + 1) });
+          pattern.lastIndex = index + 1;
+          break;
+        }
+      }
+    }
+  }
+  return results;
+}
+
+function parseAttributeGroupBlock(identifier, block) {
+  const advancedBlock = extractBraceBlock(block, "advanced") || "";
+  return {
+    identifier,
+    name: extractScalar(block, "name"),
+    sequence: extractScalar(block, "sequence"),
+    staticId: extractScalar(advancedBlock, "staticId")
+  };
+}
+
+function parseActionPositionBlock(identifier, block) {
+  const positionBlock = extractBraceBlock(block, "position") || "";
+  return {
+    identifier,
+    name: extractScalar(block, "name"),
+    staticId: extractScalar(block, "staticId"),
+    sequence: extractScalar(block, "sequence"),
+    positionType: extractScalar(positionBlock, "type")
+  };
+}
+
+function parseActionTemplateBlock(identifier, block) {
+  const advancedBlock = extractBraceBlock(block, "advanced") || "";
+  return {
+    identifier,
+    name: extractScalar(block, "name"),
+    type: extractScalar(block, "type"),
+    staticId: extractScalar(advancedBlock, "staticId")
+  };
+}
+
+function parseSlotBlock(identifier, block) {
+  const supportsBlock = extractBraceBlock(block, "supports") || "";
+  const gridLayoutBlock = extractBraceBlock(block, "gridLayout") || "";
+  return {
+    identifier,
+    name: extractScalar(block, "name"),
+    staticId: extractScalar(block, "staticId"),
+    supports: {
+      items: extractScalar(supportsBlock, "items"),
+      buttons: extractScalar(supportsBlock, "buttons")
+    },
+    gridLayout: {
+      newRow: extractScalar(gridLayoutBlock, "newRow")
+    }
+  };
+}
+
+function parseCustomAttributeBlock(identifier, block) {
+  const required = /^\s*required\s*:\s*true\s*$/m.test(extractBraceBlock(block, "validation") || "");
+  const appearanceBlock = extractBraceBlock(block, "appearance") || "";
+  const dependingOnBlock = extractBraceBlock(block, "dependingOn") || "";
+  const defaultBlock = extractBraceBlock(block, "default") || "";
+  const securityBlock = extractBraceBlock(block, "security") || "";
+  const entries = findAllParenBlocks(block, "entry").map(({ identifier: entryName, block: entryBlock }) => ({
+    name: entryName,
+    display: extractScalar(entryBlock, "display"),
+    returnValue: extractScalar(entryBlock, "return"),
+    sequence: extractScalar(entryBlock, "sequence")
+  }));
+  return {
+    identifier,
+    apexlangName: extractScalar(block, "apexlangName"),
+    attributeId: extractScalar(block, "attribute"),
+    name: extractScalar(block, "name"),
+    type: extractScalar(block, "type") || "text",
+    required,
+    defaultValue: extractScalar(defaultBlock, "value"),
+    sampleDataValue: extractScalar(defaultBlock, "sampleDataValue"),
+    attributeGroup: extractScalar(appearanceBlock, "attributeGroup"),
+    sequence: extractScalar(appearanceBlock, "sequence"),
+    dependencyAttribute: extractScalar(dependingOnBlock, "attribute"),
+    dependencyCondition: extractScalar(dependingOnBlock, "conditionType"),
+    dependencyValue: extractScalar(dependingOnBlock, "value"),
+    escapeMode: extractScalar(securityBlock, "escapeMode"),
+    helpText: extractScalar(extractBraceBlock(block, "help") || "", "helpText") || extractScalar(block, "helpText"),
+    entries
+  };
+}
+
+function loadTemplateComponentProfileFromSourceRoot(sourceRoot, name) {
+  const resolved = resolveTemplateComponentDir(sourceRoot, name);
+  if (!resolved) {
+    throw new Error(`Unknown template component '${name}'. Try one of: ${Object.keys(TEMPLATE_COMPONENT_ALIASES).join(", ")}`);
+  }
+
+  const pluginPath = path.join(resolved.pluginDir, "plugin.apx");
+  if (!fs.existsSync(pluginPath)) {
+    throw new Error(`No plugin.apx found for template component '${resolved.resolvedName}'`);
+  }
+  const pluginText = fs.readFileSync(pluginPath, "utf8");
+  const customAttributesText = fs.existsSync(path.join(resolved.pluginDir, "custom-attributes.apx"))
+    ? fs.readFileSync(path.join(resolved.pluginDir, "custom-attributes.apx"), "utf8")
+    : "";
+  const attributeGroupsText = fs.existsSync(path.join(resolved.pluginDir, "attribute-groups.apx"))
+    ? fs.readFileSync(path.join(resolved.pluginDir, "attribute-groups.apx"), "utf8")
+    : "";
+  const actionPositionsText = fs.existsSync(path.join(resolved.pluginDir, "action-positions.apx"))
+    ? fs.readFileSync(path.join(resolved.pluginDir, "action-positions.apx"), "utf8")
+    : "";
+  const actionTemplatesText = fs.existsSync(path.join(resolved.pluginDir, "action-templates.apx"))
+    ? fs.readFileSync(path.join(resolved.pluginDir, "action-templates.apx"), "utf8")
+    : "";
+  const slotsText = fs.existsSync(path.join(resolved.pluginDir, "slots.apx"))
+    ? fs.readFileSync(path.join(resolved.pluginDir, "slots.apx"), "utf8")
+    : "";
+  const pluginBlock = findParenBlock(pluginText, "plugin");
+  if (!pluginBlock) {
+    throw new Error(`Could not parse plugin.apx for ${resolved.resolvedName}`);
+  }
+  const templateComponentBlock = extractBraceBlock(pluginBlock.block, "templateComponent") || "";
+
+  return {
+    backend: "repo-theme-export",
+    theme: "universal-theme",
+    requestedName: resolved.requestedName,
+    resolvedName: resolved.resolvedName,
+    sourceDir: path.basename(resolved.pluginDir),
+    plugin: {
+      identifier: pluginBlock.identifier,
+      name: extractScalar(pluginBlock.block, "name"),
+      staticId: extractScalar(pluginBlock.block, "staticId"),
+      availableAs: extractListItems(templateComponentBlock, "availableAs"),
+      reportBody: extractScalar(templateComponentBlock, "reportBody"),
+      reportRow: extractScalar(templateComponentBlock, "reportRow"),
+      reportGroup: extractScalar(templateComponentBlock, "reportGroup"),
+      reportContainer: extractScalar(templateComponentBlock, "reportContainer"),
+      numberOfLazyLoadingSkeletons: extractScalar(templateComponentBlock, "numberOfLazyLoadingSkeletons")
+    },
+    attributeGroups: findAllParenBlocks(attributeGroupsText, "attributeGroup").map(({ identifier, block }) =>
+      parseAttributeGroupBlock(identifier, block)
+    ),
+    actionPositions: findAllParenBlocks(actionPositionsText, "actionPosition").map(({ identifier, block }) =>
+      parseActionPositionBlock(identifier, block)
+    ),
+    actionTemplates: findAllParenBlocks(actionTemplatesText, "actionTemplate").map(({ identifier, block }) =>
+      parseActionTemplateBlock(identifier, block)
+    ),
+    slots: findAllParenBlocks(slotsText, "slot").map(({ identifier, block }) => parseSlotBlock(identifier, block)),
+    customAttributes: findAllParenBlocks(customAttributesText, "customAttribute").map(({ identifier, block }) =>
+      parseCustomAttributeBlock(identifier, block)
+    )
+  };
+}
+
+export function buildTemplateComponentCatalogFromSourceRoot(sourceRoot) {
+  if (!fs.existsSync(sourceRoot)) {
+    throw new Error(`Template-component source root does not exist: ${sourceRoot}`);
+  }
+  const components = {};
+  for (const name of Object.keys(TEMPLATE_COMPONENT_ALIASES)) {
+    try {
+      components[name] = loadTemplateComponentProfileFromSourceRoot(sourceRoot, name);
+    } catch (error) {
+      if (/No plugin\.apx found/.test(String(error?.message))) {
+        continue;
+      }
+      throw error;
+    }
+  }
+  return {
+    schemaVersion: 1,
+    theme: "universal-theme",
+    source: "repo-theme-export",
+    aliases: TEMPLATE_COMPONENT_ALIASES,
+    components
+  };
+}
+
+export function loadTemplateComponentCatalog() {
+  if (!fs.existsSync(DISTILLED_TEMPLATE_COMPONENT_PROFILE_PATH)) {
+    throw new Error(
+      `Template-component profile catalog is unavailable: ${DISTILLED_TEMPLATE_COMPONENT_PROFILE_PATH}. Regenerate it before querying template-component metadata.`
+    );
+  }
+  return JSON.parse(fs.readFileSync(DISTILLED_TEMPLATE_COMPONENT_PROFILE_PATH, "utf8"));
+}
+
+export function loadTemplateComponentProfile(name) {
+  const catalog = loadTemplateComponentCatalog();
+  const aliasKey = catalog.components[name] ? name : Object.keys(catalog.aliases || {}).find((key) => catalog.aliases[key] === name);
+  if (!aliasKey || !catalog.components[aliasKey]) {
+    throw new Error(`Unknown template component '${name}'. Try one of: ${Object.keys(catalog.components).join(", ")}`);
+  }
+  const profile = catalog.components[aliasKey];
+  return {
+    ...profile,
+    requestedName: name
+  };
+}