claude: Replace Proxy-based quartoAPI with getQuartoAPI() function and dynamic engine registration

Refactored quartoAPI from Proxy-based lazy initialization to explicit
getQuartoAPI() function. This eliminates Proxy overhead on every property
access while maintaining lazy initialization semantics.

Key changes:
- src/core/api/index.ts: Replaced Proxy with memoized getQuartoAPI() function
- src/execute/engine.ts: Made engine registration dynamic
  - Removed module-scope registerExecutionEngine() calls
  - Added kStandardEngines array and enginesRegistered flag
  - Renamed reorderEngines() to resolveEngines()
  - Standard engines now registered on first resolveEngines() call
- src/command/command-utils.ts: Updated to use resolveEngines()

Benefits:
- Better performance: No Proxy overhead on property access
- Clearer semantics: Explicit function call for API initialization
- Simpler mental model: Standard memoization pattern
- Solves module initialization order issues
- Better naming: resolveEngines reflects dynamic loading

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

Author: gordonwoodhull

src/command/command-utils.ts

@@ -7,7 +7,7 @@
 import { initYamlIntelligenceResourcesFromFilesystem } from "../core/schema/utils.ts";
 import { projectContext } from "../project/project-context.ts";
 import { notebookContext } from "../render/notebook/notebook-context.ts";
-import { reorderEngines } from "../execute/engine.ts";
+import { resolveEngines } from "../execute/engine.ts";
 import type { ProjectContext } from "../project/types.ts";
 
 /**
@@ -68,5 +68,5 @@ export async function initializeProjectContextAndEngines(
     await zeroFileProjectContext(dir);
 
   // Register external engines from project config
-  await reorderEngines(context);
+  await resolveEngines(context);
 }

src/core/api/index.ts

@@ -29,20 +29,22 @@ export {
 } from "./registry.ts";
 
 /**
- * The global QuartoAPI instance
+ * The global QuartoAPI instance (cached after first call)
+ */
+let _quartoAPI: QuartoAPI | null = null;
+
+/**
+ * Get the global QuartoAPI instance
  *
- * This is created lazily on first access via a getter.
+ * This function returns the QuartoAPI instance, creating it on first call.
  * The register.ts module (imported in src/quarto.ts) ensures all
  * namespaces are registered before any code accesses the API.
+ *
+ * @returns {QuartoAPI} The complete API object with all namespaces
  */
-let _quartoAPI: QuartoAPI | null = null;
-
-export const quartoAPI = new Proxy({} as QuartoAPI, {
-  get(_target, prop) {
-    // Create API on first access
-    if (_quartoAPI === null) {
-      _quartoAPI = globalRegistry.createAPI();
-    }
-    return _quartoAPI[prop as keyof QuartoAPI];
-  },
-});
+export function getQuartoAPI(): QuartoAPI {
+  if (_quartoAPI === null) {
+    _quartoAPI = globalRegistry.createAPI();
+  }
+  return _quartoAPI;
+}

src/execute/engine.ts

@@ -36,12 +36,21 @@ import { pandocBuiltInFormats } from "../core/pandoc/pandoc-formats.ts";
 import { gitignoreEntries } from "../project/project-gitignore.ts";
 import { ensureFileInformationCache } from "../project/project-shared.ts";
 import { engineProjectContext } from "../project/engine-project-context.ts";
-import { quartoAPI } from "../core/api/index.ts";
+import { getQuartoAPI } from "../core/api/index.ts";
 import { satisfies } from "semver/mod.ts";
 import { quartoConfig } from "../core/quarto.ts";
 
 const kEngines: Map<string, ExecutionEngineDiscovery> = new Map();
 
+// Standard engines to register on first resolveEngines() call
+const kStandardEngines: ExecutionEngineDiscovery[] = [
+  knitrEngineDiscovery,
+  jupyterEngineDiscovery,
+  markdownEngineDiscovery,
+];
+
+let enginesRegistered = false;
+
 /**
  * Check if an engine's Quarto version requirement is satisfied
  * @param engine The engine to check
@@ -76,15 +85,6 @@ export function executionEngine(name: string) {
   return kEngines.get(name);
 }
 
-// Register the standard engines with discovery interface
-registerExecutionEngine(knitrEngineDiscovery);
-
-// Register jupyter engine with discovery interface
-registerExecutionEngine(jupyterEngineDiscovery);
-
-// Register markdown engine with discovery interface
-registerExecutionEngine(markdownEngineDiscovery);
-
 export function registerExecutionEngine(engine: ExecutionEngineDiscovery) {
   if (kEngines.has(engine.name)) {
     throw new Error(`Execution engine ${engine.name} already registered`);
@@ -95,7 +95,7 @@ export function registerExecutionEngine(engine: ExecutionEngineDiscovery) {
 
   kEngines.set(engine.name, engine);
   if (engine.init) {
-    engine.init(quartoAPI);
+    engine.init(getQuartoAPI());
   }
 }
 
@@ -192,7 +192,15 @@ export function markdownExecutionEngine(
   return markdownEngineDiscovery.launch(engineProjectContext(project));
 }
 
-export async function reorderEngines(project: ProjectContext) {
+export async function resolveEngines(project: ProjectContext) {
+  // Register standard engines on first call
+  if (!enginesRegistered) {
+    enginesRegistered = true;
+    for (const engine of kStandardEngines) {
+      registerExecutionEngine(engine);
+    }
+  }
+
   const userSpecifiedOrder: string[] = [];
   const projectEngines = project.config?.engines as
     | (string | ExternalEngine)[]
@@ -231,7 +239,7 @@ export async function reorderEngines(project: ProjectContext) {
         userSpecifiedOrder.push(extEngine.name);
         kEngines.set(extEngine.name, extEngine);
         if (extEngine.init) {
-          extEngine.init(quartoAPI);
+          extEngine.init(getQuartoAPI());
         }
       } catch (err: any) {
         // Throw error for engine import failures as this is a serious configuration issue
@@ -278,6 +286,9 @@ export async function fileExecutionEngine(
   flags: RenderFlags | undefined,
   project: ProjectContext,
 ): Promise<ExecutionEngineInstance | undefined> {
+  // Resolve engines first (registers standard engines on first call)
+  const engines = await resolveEngines(project);
+
   // get the extension and validate that it can be handled by at least one of our engines
   const ext = extname(file).toLowerCase();
   if (
@@ -288,10 +299,8 @@ export async function fileExecutionEngine(
     return undefined;
   }
 
-  const reorderedEngines = await reorderEngines(project);
-
   // try to find an engine that claims this extension outright
-  for (const [_, engine] of reorderedEngines) {
+  for (const [_, engine] of engines) {
     if (engine.claimsFile(file, ext)) {
       return engine.launch(engineProjectContext(project));
     }
@@ -308,7 +317,7 @@ export async function fileExecutionEngine(
       return markdownExecutionEngine(
         project,
         markdown ? markdown.value : Deno.readTextFileSync(file),
-        reorderedEngines,
+        engines,
         flags,
       );
     } catch (error) {

src/execute/jupyter/jupyter-kernel.ts

@@ -13,7 +13,7 @@ import {
   JupyterCapabilities,
   JupyterKernelspec,
 } from "../../core/jupyter/types.ts";
-import { quartoAPI as quarto } from "../../core/api/index.ts";
+import { getQuartoAPI } from "../../core/api/index.ts";
 import type { ProcessResult } from "../../core/process-types.ts";
 
 import {
@@ -175,6 +175,7 @@ async function execJupyter(
   options: Record<string, unknown>,
   kernelspec: JupyterKernelspec,
 ): Promise<ProcessResult> {
+  const quarto = getQuartoAPI();
   try {
     const cmd = await quarto.jupyter.pythonExec(kernelspec);
     const result = await quarto.system.execProcess(
@@ -219,6 +220,7 @@ export async function printExecDiagnostics(
   kernelspec: JupyterKernelspec,
   stderr?: string,
 ) {
+  const quarto = getQuartoAPI();
   const caps = await quarto.jupyter.capabilities(kernelspec);
   if (caps && !caps.jupyter_core) {
     info("Python 3 installation:");
@@ -247,6 +249,7 @@ function pythonVersionMessage() {
 }
 
 function maybePrintUnactivatedEnvMessage(caps: JupyterCapabilities) {
+  const quarto = getQuartoAPI();
   const envMessage = quarto.jupyter.unactivatedEnvMessage(caps);
   if (envMessage) {
     info(envMessage);
@@ -298,6 +301,7 @@ interface KernelTransport {
 }
 
 function kernelTransportFile(target: string) {
+  const quarto = getQuartoAPI();
   let transportsDir: string;
 
   try {
@@ -321,6 +325,7 @@ function kernelTransportFile(target: string) {
 }
 
 function kernelLogFile() {
+  const quarto = getQuartoAPI();
   const logsDir = quarto.path.dataDir("logs");
   const kernelLog = join(logsDir, "jupyter-kernel.log");
   if (!existsSync(kernelLog)) {

src/execute/jupyter/jupyter.ts

@@ -67,13 +67,18 @@ interface JupyterTargetData {
 }
 
 // Import quartoAPI directly since we're in core codebase
-import { quartoAPI as quarto } from "../../core/api/index.ts";
+import type { QuartoAPI } from "../../core/api/index.ts";
+
+let quarto: QuartoAPI;
 import { MappedString } from "../../core/mapped-text.ts";
 import { kJupyterPercentScriptExtensions } from "../../core/jupyter/percent.ts";
 import type { CheckConfiguration } from "../../command/check/check.ts";
 
 export const jupyterEngineDiscovery: ExecutionEngineDiscovery = {
-  // we don't need init() because we use Quarto API directly
+  init: (quartoAPI) => {
+    quarto = quartoAPI;
+  },
+
   name: kJupyterEngine,
   defaultExt: ".qmd",
   defaultYaml: (kernel?: string) => [

src/execute/rmd.ts

@@ -11,7 +11,9 @@ import { basename, extname } from "../deno_ral/path.ts";
 import * as colors from "fmt/colors";
 
 // Import quartoAPI directly since we're in core codebase
-import { quartoAPI as quarto } from "../core/api/index.ts";
+import type { QuartoAPI } from "../core/api/index.ts";
+
+let quarto: QuartoAPI;
 
 import { rBinaryPath } from "../core/resources.ts";
 
@@ -48,6 +50,10 @@ import {
 const kRmdExtensions = [".rmd", ".rmarkdown"];
 
 export const knitrEngineDiscovery: ExecutionEngineDiscovery = {
+  init: (quartoAPI) => {
+    quarto = quartoAPI;
+  },
+
   // Discovery methods
   name: kKnitrEngine,